---
updatedAt: 2026-06-17T07:20:34.000Z
agentTools:
  projectIndex: https://readme.cipherowl.ai/llms.txt
---

# Screen address

Screens a single blockchain address against a risk configuration and returns a fast yes/no risk verdict (`found_risk`). This is the lowest-latency SRR endpoint, intended for real-time compliance checks such as gating a deposit, withdrawal, or counterparty before a transaction is allowed.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "API ENDPOINTS",
    "description": "CipherOwl blockchain compliance and risk assessment APIs.",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://svc.cipherowl.ai"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "SRR API",
      "description": "Screen blockchain addresses for risk, retrieve risk reasons, breakdowns, scores, and generate reports. Risk is evaluated per chain, so these endpoints take a chain (`/chains/{chain}/…`, e.g. `evm`)."
    }
  ],
  "paths": {
    "/api/screen/v1/chains/{chain}/addresses/{address}": {
      "get": {
        "summary": "Screen address",
        "description": "Screens a single blockchain address against a risk configuration and returns a fast yes/no risk verdict (`found_risk`). This is the lowest-latency SRR endpoint, intended for real-time compliance checks such as gating a deposit, withdrawal, or counterparty before a transaction is allowed.",
        "operationId": "ScreenService_ScreenAddress",
        "responses": {
          "200": {
            "description": "A successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/v1ScreenAddressResponse"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "chain",
            "description": "Chain of the address, for example `evm`, `bitcoin` or `tron`. Risk is\nevaluated per chain, so pass the chain, not a network such as\n`ethereum_mainnet`.",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "bitcoin"
            }
          },
          {
            "name": "address",
            "description": "The blockchain address to screen",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "17mhyeBX617ABZ1ffThhUTJkHUcMvCkfd5"
            }
          },
          {
            "name": "config",
            "description": "Selects the risk configuration (preconfigured risk model — categories,\nhop depths, thresholds) to apply for this address. Accepted values are\nmoniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix\nwith `co-` to reference a CipherOwl-managed configuration. An\nunprefixed name resolves against your organization's customized\nconfigurations. When omitted or empty, the server resolves\nyour organization's default configuration for the requested chain and\nreturns the resolved name on the response. See\nhttps://readme.cipherowl.ai/reference/parameters for the current list.",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "reference",
            "description": "Optional opaque reference for customer-side attribution of this request\n(e.g. sub-tenant, team, workflow). Contract:\n - Opaque: the server never parses or interprets the value.\n - Format: dot-separated segments of [a-z0-9_], max 256 characters.\n   Input is trimmed and lowercased before validation; violations return\n   400 INVALID_ARGUMENT. Example: \"binance.compliance.apac\".\n - Empty or whitespace-only means absent (unreferenced).\n - Does not affect screening logic. Propagation: echoed on the response\n   as applied, stamped on structured screening logs (audit trail) and on\n   the Simple Case screening event. Never a metric label.\n - Customer-supplied and reusable across requests; never generated by\n   the server. Distinct from address label tags and from XRP/XLM\n   destination tags.",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hops",
            "description": "Hop distance for multihop bloomfilter queries (0-8).\nWhen set, uses multihop bloomfilter and checks all hops from 0 to this value.\nWhen not set, uses legacy single-hop bloomfilter behavior.",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "trackAlert",
            "description": "Opt this request out of Case tracking by setting it to false. Omitted\nmeans true (APP-5011): screenings are tracked by default, and the\nparameter exists so callers can opt out per request.\nEvent publication still requires global producer enablement, org-config\nallow_case_management=true, and a risk_found=true result.\nField is named track_alert for wire-compatibility; it means\n\"create a Case from this screening if it triggers.\"",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "tags": [
          "SRR API"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "OAuth 2.0 access token obtained from /oauth/token using client credentials."
      }
    },
    "schemas": {
      "v1ScreenAddressResponse": {
        "type": "object",
        "properties": {
          "config": {
            "type": "string",
            "description": "Canonical name of the risk configuration that was actually applied.\nMay differ from the requested value when the request omitted `config`\nand the server resolved the organization's default."
          },
          "chain": {
            "type": "string",
            "description": "Chain of the address (for example `evm`)."
          },
          "address": {
            "type": "string",
            "title": "The blockchain address that was screened"
          },
          "foundRisk": {
            "type": "boolean",
            "title": "Whether the address has a risk signal"
          },
          "version": {
            "type": "string",
            "title": "The version of the screening bloom filter used"
          },
          "reference": {
            "type": "string",
            "description": "The reference applied to this screening, after normalization\n(trim + lowercase). Absent when the request carried none."
          },
          "explanations": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "title": "LLM explanations dictionary"
          }
        }
      }
    }
  }
}
```