--- updatedAt: 2026-06-17T07:20:34.000Z agentTools: projectIndex: https://readme.cipherowl.ai/llms.txt --- # Get risk detail Returns the most detailed risk explanation for an address. For each matched risk category and transaction direction it includes the number of hops to the risky entity, total USD and percentage exposure, first/last exposure timestamps, and the actual transaction paths (including cross-chain paths) connecting the address to risky entities. Use it when you need the full evidence behind a risky verdict — for investigations, case files, or audit trails. # 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/reason/v2/chains/{chain}/addresses/{address}/detail": { "get": { "summary": "Get risk detail", "description": "Returns the most detailed risk explanation for an address. For each matched risk category and transaction direction it includes the number of hops to the risky entity, total USD and percentage exposure, first/last exposure timestamps, and the actual transaction paths (including cross-chain paths) connecting the address to risky entities. Use it when you need the full evidence behind a risky verdict — for investigations, case files, or audit trails.", "operationId": "RiskReasonService_GetAddressRiskReasonDetail", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1GetAddressRiskReasonDetailResponse" } } } } }, "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 analyze", "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": "hops", "description": "Optional hop depth limit. Caps the max hops used for filtering risk results.\nMust be between 0 and 8. When omitted, uses the config's default hops.", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "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": { "apirisk_reasonv1Path": { "type": "object", "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "title": "List of addresses in the path" }, "direct_usd_value": { "type": "number", "format": "double", "description": "Cumulative USD on the hop adjacent to the queried address: first for SEND,\nlast for RECEIVE. Absent when the hop's USD amount is unknown." }, "min_expose_usd_value": { "type": "number", "format": "double", "description": "Minimum cumulative USD across every hop in this path. A capacity upper\nbound, not attributed exposure. Absent if any hop's USD amount is unknown." } }, "title": "Transaction path representation" }, "v1AddressRiskReasonDetailItem": { "type": "object", "properties": { "category": { "type": "string", "title": "Risk category (e.g., sanctions, scam, darknet)" }, "direction": { "allOf": [ { "$ref": "#/components/schemas/v1TransactionDirection" } ], "title": "Transaction direction" }, "hops": { "type": "integer", "format": "int32", "title": "Number of hops to the risky entities in this risk category" }, "totalUsdValue": { "type": "number", "format": "double", "title": "Total USD value of exposure to this risk category" }, "totalPercentage": { "type": "number", "format": "double", "description": "Total percentage of exposure to this risk category compared to the address's total transactions value.\nRange is 0 - 100." }, "firstExposureTimestamp": { "type": "string", "format": "int64", "title": "Timestamp of the first exposure (Unix timestamp in seconds)" }, "lastExposureTimestamp": { "type": "string", "format": "int64", "title": "Timestamp of the last exposure (Unix timestamp in seconds)" }, "paths": { "type": "array", "items": { "$ref": "#/components/schemas/apirisk_reasonv1Path" }, "title": "Transaction paths between the address and risky entities in this risk category" }, "isPartialSet": { "type": "boolean", "title": "Indicates if the paths is a partial result set" }, "label": { "type": "string", "title": "Label for Coinbase M2M API calls (mapped from category or original label)" }, "standardLabel": { "type": "string", "title": "Standard label for Coinbase M2M API calls (target label from mapping)" }, "pathsWithChain": { "type": "array", "items": { "$ref": "#/components/schemas/v1PathWithChain" }, "title": "Transaction paths with chain information for cross-chain transactions\nEach path contains chain-address pairs showing the chain for each address" } }, "title": "Detailed risk information for v1 API (full details)" }, "v1ChainAddress": { "type": "object", "properties": { "chain": { "type": "string", "description": "Chain of the address (for example `evm`, `bitcoin`, `solana` or `tron`)." }, "address": { "type": "string", "description": "The address on that chain." } }, "title": "Chain-address pair for cross-chain path representation" }, "v1GetAddressRiskReasonDetailResponse": { "type": "object", "properties": { "chain": { "type": "string", "description": "Chain of the address (for example `evm`)." }, "address": { "type": "string", "title": "The blockchain address" }, "config": { "type": "string", "description": "Canonical name of the risk configuration that was actually applied\n(e.g., co-defi, co-institution, co-vasp). May differ from the requested\nvalue when the request omitted `config` and the server resolved the\norganization's default." }, "foundRisk": { "type": "boolean", "title": "Indicates if any risk was found" }, "riskLevel": { "type": "string", "title": "Deprecated, use found_risk instead" }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/v1AddressRiskReasonDetailItem" }, "title": "List of detailed risk reasons of this address" }, "version": { "type": "string", "description": "The version of the risk dataset these reasons came from. Empty when\nunavailable." }, "path_usd_lookup_failed": { "type": "boolean", "description": "True if any path USD lookup batch failed. Successful batches are retained.\nFalse means no lookup failed, not that every edge has known pricing; this\nalso covers responses with no path edges. Missing on older servers." } }, "title": "Response message for GetAddressRiskReasonDetail" }, "v1PathWithChain": { "type": "object", "properties": { "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/v1ChainAddress" }, "title": "List of chain-address pairs in the path" }, "direct_usd_value": { "type": "number", "format": "double", "description": "Same per-path amounts as Path, including cross-chain hops when priced." }, "min_expose_usd_value": { "type": "number", "format": "double" } }, "title": "Path with chain information for cross-chain transactions" }, "v1TransactionDirection": { "type": "string", "enum": [ "TRANSACTION_DIRECTION_UNSPECIFIED", "SEND", "RECEIVE" ], "default": "TRANSACTION_DIRECTION_UNSPECIFIED", "description": "- TRANSACTION_DIRECTION_UNSPECIFIED: Default value for unspecified direction\n - SEND: Transaction sent from the address\n - RECEIVE: Transaction received by the address", "title": "TransactionDirection represents the direction of a transaction flow" } } } } ```