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

# Get risk breakdown

Returns a categorized summary of an address's risk exposures — the set of matched risk categories and whether each exposure is direct or indirect — without the full per-path evidence. It is a lighter-weight view than the detail endpoint, intended for rendering an at-a-glance risk profile or dashboard for an address.

# 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}/risk-breakdown": {
      "get": {
        "summary": "Get risk breakdown",
        "description": "Returns a categorized summary of an address's risk exposures — the set of matched risk categories and whether each exposure is direct or indirect — without the full per-path evidence. It is a lighter-weight view than the detail endpoint, intended for rendering an at-a-glance risk profile or dashboard for an address.",
        "operationId": "RiskReasonService_GetAddressRiskBreakdown2",
        "responses": {
          "200": {
            "description": "A successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/v1GetAddressRiskBreakdownResponse"
                }
              }
            }
          }
        },
        "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": {
      "v1GetAddressRiskBreakdownResponse": {
        "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."
          },
          "risks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/v1RiskBreakdown"
            },
            "title": "List of risk breakdowns"
          },
          "version": {
            "type": "string",
            "description": "The version of the risk dataset this breakdown came from. Empty when\nunavailable."
          }
        },
        "title": "Response message for GetAddressRiskBreakdown"
      },
      "v1RiskBreakdown": {
        "type": "object",
        "properties": {
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/v1RiskType"
              }
            ],
            "title": "Risk type"
          },
          "category": {
            "type": "string",
            "title": "Risk category (e.g., sanctions, scam, darknet)"
          },
          "direction": {
            "allOf": [
              {
                "$ref": "#/components/schemas/v1TransactionDirection"
              }
            ],
            "title": "Transaction direction - only populated for INDIRECT risk type"
          },
          "percentage": {
            "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."
          },
          "hops": {
            "type": "integer",
            "format": "int32",
            "title": "Number of hops to the risk entity - only for INDIRECT"
          },
          "totalUsdValue": {
            "type": "number",
            "format": "double",
            "title": "Total USD value of exposure to this risk category - only for INDIRECT"
          }
        },
        "title": "Risk breakdown detail"
      },
      "v1RiskType": {
        "type": "string",
        "enum": [
          "RISK_TYPE_UNSPECIFIED",
          "DIRECT",
          "INDIRECT"
        ],
        "default": "RISK_TYPE_UNSPECIFIED",
        "description": "- RISK_TYPE_UNSPECIFIED: Default value for unspecified risk type\n - DIRECT: Direct exposure to risky entity\n - INDIRECT: Indirect exposure to risky entity (through intermediaries)",
        "title": "RiskType represents the type of risk exposure"
      },
      "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"
      }
    }
  }
}
```