openapi: 3.0.3
info:
title: CipherOwl Onchain Service SRR API API
description: CipherOwl blockchain compliance and risk assessment APIs (Screening, Risk & Reporting; Onchain; Private Data).
version: 2.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.
paths:
/api/report/v1/graph/chains/{chain}/addresses/{address}:
get:
tags:
- SRR API
summary: Get risk flow graph
description: Returns a risk-flow diagram for an address that visualizes how funds move between it and the risky entities it is exposed to. The diagram is available as Mermaid markup, an interactive HTML wrapper, or a rendered PNG image, making it suitable for embedding in reports or investigation UIs.
operationId: graph_api
parameters:
- name: chain
in: path
required: true
schema:
type: string
description: Blockchain network identifier, e.g. 'evm', 'bitcoin' or 'tron'
title: Chain
example: bitcoin
description: Blockchain network identifier, e.g. 'evm', 'bitcoin' or 'tron'
- name: address
in: path
required: true
schema:
type: string
description: Blockchain address to analyze
title: Address
example: 17mhyeBX617ABZ1ffThhUTJkHUcMvCkfd5
description: Blockchain address to analyze
- name: config
in: query
required: false
schema:
description: Selects the risk configuration (preconfigured risk model — categories, hop depths, thresholds) to apply for this address. Accepted values are moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix with `co-` to reference a CipherOwl-managed configuration. An unprefixed name resolves against your organization's customized configurations. When omitted or empty, the server resolves your organization's default configuration for the requested chain and returns the resolved name on the response. See https://readme.cipherowl.ai/reference/parameters for the current list.
title: Config
type: string
nullable: true
description: Selects the risk configuration (preconfigured risk model — categories, hop depths, thresholds) to apply for this address. Accepted values are moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix with `co-` to reference a CipherOwl-managed configuration. An unprefixed name resolves against your organization's customized configurations. When omitted or empty, the server resolves your organization's default configuration for the requested chain and returns the resolved name on the response. See https://readme.cipherowl.ai/reference/parameters for the current list.
- name: output_format
in: query
required: false
schema:
type: string
pattern: ^(mermaid|html|png)$
description: 'Output format: ''mermaid'' for diagram only, ''html'' for interactive wrapper, ''png'' for rendered image'
default: mermaid
title: Output Format
description: 'Output format: ''mermaid'' for diagram only, ''html'' for interactive wrapper, ''png'' for rendered image'
- name: interactive
in: query
required: false
schema:
type: boolean
description: Include interactive features (tooltips, click-to-copy). Ignored for PNG format.
default: true
title: Interactive
description: Include interactive features (tooltips, click-to-copy). Ignored for PNG format.
responses:
'200':
description: Risk flow diagram
content:
application/json:
schema:
properties:
graph:
title: Graph
type: string
nullable: true
error:
title: Error
type: string
nullable: true
timestamp:
format: date-time
title: Timestamp
type: string
required:
- timestamp
title: EmbeddedMermaidGraph
type: object
image/png:
schema:
type: string
format: binary
'400':
description: Bad Request
'403':
description: Unauthorized
'500':
description: Internal Server Error
/api/report/v1/risk-assessment/chains/{chain}/addresses/{address}:
get:
tags:
- SRR API
summary: Get risk assessment report
description: Generates a human-readable risk-assessment report for an address, synthesizing its screening result and risk reasons into an analyst-ready narrative with supporting evidence. Use it to produce compliance documentation without manually assembling the underlying screen, reason, and breakdown data.
operationId: risk_assessment_api
parameters:
- name: chain
in: path
required: true
schema:
type: string
description: Blockchain network identifier
title: Chain
example: bitcoin
description: Blockchain network identifier
- name: address
in: path
required: true
schema:
type: string
description: Blockchain address to analyze
title: Address
example: 17mhyeBX617ABZ1ffThhUTJkHUcMvCkfd5
description: Blockchain address to analyze
- name: config
in: query
required: false
schema:
description: Selects the risk configuration (preconfigured risk model — categories, hop depths, thresholds) to apply for this address. Accepted values are moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix with `co-` to reference a CipherOwl-managed configuration. An unprefixed name resolves against your organization's customized configurations. When omitted or empty, the server resolves your organization's default configuration for the requested chain and returns the resolved name on the response. See https://readme.cipherowl.ai/reference/parameters for the current list.
title: Config
type: string
nullable: true
description: Selects the risk configuration (preconfigured risk model — categories, hop depths, thresholds) to apply for this address. Accepted values are moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix with `co-` to reference a CipherOwl-managed configuration. An unprefixed name resolves against your organization's customized configurations. When omitted or empty, the server resolves your organization's default configuration for the requested chain and returns the resolved name on the response. See https://readme.cipherowl.ai/reference/parameters for the current list.
responses:
'200':
description: Returns detailed risk assessment for blockchain address
content:
application/json:
schema:
$ref: '#/components/schemas/EvidenceReport'
'400':
description: Bad Request
'403':
description: Unauthorized
'500':
description: Internal Server Error
/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'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: chain
description: The blockchain network (e.g., bitcoin, evm, tron)
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,
hop depths, thresholds) to apply for this address. Accepted values are
moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix
with `co-` to reference a CipherOwl-managed configuration. An
unprefixed name resolves against your organization''s customized
configurations. When omitted or empty, the server resolves
your organization''s default configuration for the requested chain and
returns the resolved name on the response. See
https://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.
Must 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
/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'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: chain
description: The blockchain network (e.g., bitcoin, evm, tron)
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,
hop depths, thresholds) to apply for this address. Accepted values are
moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix
with `co-` to reference a CipherOwl-managed configuration. An
unprefixed name resolves against your organization''s customized
configurations. When omitted or empty, the server resolves
your organization''s default configuration for the requested chain and
returns the resolved name on the response. See
https://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.
Must 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
/api/reason/v2/chains/{chain}/addresses/{address}/risk-score:
get:
summary: Get risk score
description: Computes a deterministic 0–100 risk score for an address from its exposure profile. Use it for risk tiering, threshold-based alerting, and automated decisioning where a single comparable numeric value is more convenient than the categorical reason or breakdown views.
operationId: RiskReasonService_GetAddressRiskScore
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetAddressRiskScoreResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: chain
description: The blockchain network (e.g., bitcoin, evm, tron)
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,
hop depths, thresholds) to apply for this address. Accepted values are
moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix
with `co-` to reference a CipherOwl-managed configuration. An
unprefixed name resolves against your organization''s customized
configurations. When omitted or empty, the server resolves
your organization''s default configuration for the requested chain and
returns the resolved name on the response. See
https://readme.cipherowl.ai/reference/parameters for the current list.'
in: query
required: false
schema:
type: string
- name: riskProfile
description: Risk profile name (e.g., "sanction_focused"). Uses default profile if empty.
in: query
required: false
schema:
type: string
- name: hops
description: 'Optional hop depth limit. Caps the max hops used for filtering risk results.
Must 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
/api/chain-capabilities/v1:
get:
summary: Get chain capabilities
description: 'Returns, for every supported chain, which CipherOwl capability tiers are available. The tiers are progressive: `screening` is the baseline address-screening capability; `reporting` means the full Screening, Risk & Reporting (SRR) API stack is available; `research` means the chain is also available in the OwlTrace research experience (graph exploration, transaction explorer, and related investigative tooling).'
operationId: RiskReasonService_GetChainCapabilities
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetChainCapabilitiesResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
tags:
- SRR API
parameters: []
/api/report/v1/sar/chains/{chain}/addresses/{address}:
get:
tags:
- SRR API
summary: Get SAR report
description: Generates a draft Suspicious Activity Report (SAR) narrative for an address, formatting its risk findings into the structure compliance teams need for regulatory filing. Use it as a starting point for a SAR submission rather than writing the narrative from scratch.
operationId: sar_report_api
parameters:
- name: chain
in: path
required: true
schema:
type: string
description: Blockchain network identifier, e.g. 'evm', 'bitcoin' or 'tron'
title: Chain
example: bitcoin
description: Blockchain network identifier, e.g. 'evm', 'bitcoin' or 'tron'
- name: address
in: path
required: true
schema:
type: string
description: Blockchain address to analyze
title: Address
example: 17mhyeBX617ABZ1ffThhUTJkHUcMvCkfd5
description: Blockchain address to analyze
- name: config
in: query
required: false
schema:
description: Selects the risk configuration (preconfigured risk model — categories, hop depths, thresholds) to apply for this address. Accepted values are moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix with `co-` to reference a CipherOwl-managed configuration. An unprefixed name resolves against your organization's customized configurations. When omitted or empty, the server resolves your organization's default configuration for the requested chain and returns the resolved name on the response. See https://readme.cipherowl.ai/reference/parameters for the current list.
title: Config
type: string
nullable: true
description: Selects the risk configuration (preconfigured risk model — categories, hop depths, thresholds) to apply for this address. Accepted values are moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix with `co-` to reference a CipherOwl-managed configuration. An unprefixed name resolves against your organization's customized configurations. When omitted or empty, the server resolves your organization's default configuration for the requested chain and returns the resolved name on the response. See https://readme.cipherowl.ai/reference/parameters for the current list.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EvidenceReport'
'400':
description: Bad Request
'403':
description: Unauthorized
'500':
description: Internal Server Error
/api/screen/v1/chains/{chain}/batch:
post:
summary: Batch screen
description: Screens many addresses in a single request against one risk configuration, returning an independent risk verdict for each address. Use it for bulk or periodic re-screening of large address lists (for example, a customer wallet base or a watchlist) where per-address round trips would be too slow.
operationId: ScreenService_BatchScreenAddresses
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1BatchScreenAddressesResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: chain
description: The blockchain network where the addresses exist
in: path
required: true
schema:
type: string
example: bitcoin
tags:
- SRR API
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScreenServiceBatchScreenAddressesBody'
/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'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: chain
in: path
required: true
schema:
type: string
example: bitcoin
- name: address
in: path
required: true
schema:
type: string
example: 17mhyeBX617ABZ1ffThhUTJkHUcMvCkfd5
- name: config
description: 'Selects the risk configuration (preconfigured risk model — categories,
hop depths, thresholds) to apply for this address. Accepted values are
moniker names such as `co-defi`, `co-vasp`, `co-institution`. Prefix
with `co-` to reference a CipherOwl-managed configuration. An
unprefixed name resolves against your organization''s customized
configurations. When omitted or empty, the server resolves
your organization''s default configuration for the requested chain and
returns the resolved name on the response. See
https://readme.cipherowl.ai/reference/parameters for the current list.'
in: query
required: false
schema:
type: string
- name: namespace
description: 'Optional namespace for request attribution and reporting purposes.
Format: dot-separated lowercase alphanumeric segments (e.g., "client.team", "binance.security")
Max length: 256 characters. Does not affect screening logic.
Use cases: sub-organization tracking, billing attribution, audit trails.'
in: query
required: false
schema:
type: string
- name: hops
description: 'Hop distance for multihop bloomfilter queries (0-8).
When set, uses multihop bloomfilter and checks all hops from 0 to this value.
When not set, uses legacy single-hop bloomfilter behavior.'
in: query
required: false
schema:
type: integer
format: int32
- name: trackAlert
description: 'Explicitly opt this request into Simple Case tracking. Default/omitted is false.
Event publication still requires global producer enablement, org-config
allow_simple_case=true, and a risk_found=true result.
Field is named track_alert for wire-compatibility; it means
"create a Simple Case from this screening if it triggers."'
in: query
required: false
schema:
type: boolean
tags:
- SRR API
components:
schemas:
v1ChainCapability:
type: object
properties:
chainClass:
type: string
description: The blockchain family this chain belongs to (e.g., evm, bitcoin, tron).
screening:
type: boolean
description: 'True if the Screening API supports this chain (single-address and batch
address screening).'
reporting:
type: boolean
description: 'True if the full SRR (Screening, Risk & Reporting) API stack supports
this chain.'
research:
type: boolean
description: 'True if the chain is available in the OwlTrace research UI — the most
advanced tier, covering graph exploration, the transaction explorer,
and related investigative tooling.'
title: Capability details for a single chain
v1GetAddressRiskBreakdownResponse:
type: object
properties:
chain:
type: string
title: The blockchain network
address:
type: string
title: The blockchain address
config:
type: string
description: 'Canonical name of the risk configuration that was actually applied.
May differ from the requested value when the request omitted `config`
and the server resolved the organization''s default.'
risks:
type: array
items:
type: object
$ref: '#/components/schemas/v1RiskBreakdown'
title: List of risk breakdowns
title: Response message for GetAddressRiskBreakdown
apirisk_reasonv1Path:
type: object
properties:
addresses:
type: array
items:
type: string
title: List of addresses in the path
title: Transaction path representation
v1GetChainCapabilitiesResponse:
type: object
properties:
capabilities:
type: object
additionalProperties:
$ref: '#/components/schemas/v1ChainCapability'
title: Chain capabilities mapping chain key to its capabilities
title: Response message for GetChainCapabilities
EvidenceReport:
properties:
risk_level:
$ref: '#/components/schemas/RiskLevel'
description: 'DEPRECATED: Use found_risk instead. This field will be removed in a future version.'
deprecated: true
found_risk:
type: boolean
title: Found Risk
description: Boolean indicating whether risk was found for the address
report:
title: Report
type: string
nullable: true
error:
title: Error
type: string
nullable: true
timestamp:
type: string
format: date-time
title: Timestamp
type: object
required:
- risk_level
- found_risk
- timestamp
title: EvidenceReport
v1BatchScreenAddressesResponse:
type: object
properties:
config:
type: string
description: 'Canonical name of the risk configuration that was actually applied to
every address in this batch. May differ from the requested value when
the request omitted `config` and the server resolved the
organization''s default.'
chain:
type: string
title: The blockchain network where the addresses exist
results:
type: array
items:
type: object
$ref: '#/components/schemas/v1AddressResult'
title: The screening results for each address
version:
type: string
title: The version of the screening bloom filter used
explanations:
type: object
additionalProperties:
type: string
title: LLM explanations dictionary
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
v1ChainAddress:
type: object
properties:
chain:
type: string
title: The chain name (e.g., evm, bitcoin, solana, tron)
address:
type: string
title: The address on that chain
title: Chain-address pair for cross-chain path representation
ScreenServiceBatchScreenAddressesBody:
type: object
properties:
config:
type: string
description: 'Selects the risk configuration (preconfigured risk model — categories,
hop depths, thresholds) to apply for every address in this batch.
Accepted values are moniker names such as `co-defi`, `co-vasp`,
`co-institution`. Prefix with `co-` to reference a CipherOwl-managed
configuration. An unprefixed name resolves against your organization''s
customized configurations. When omitted or empty, the server resolves
your organization''s default configuration for the requested chain and
returns the resolved name on the response. See
https://readme.cipherowl.ai/reference/parameters for the current list.'
addresses:
type: array
items:
type: string
title: The blockchain addresses to screen
namespace:
type: string
description: Optional namespace for request attribution and reporting purposes.
hops:
type: integer
format: int32
description: 'Hop distance for multihop bloomfilter queries (0-8).
When set, uses multihop bloomfilter and checks all hops from 0 to this value.
When not set, uses legacy single-hop bloomfilter behavior.'
trackAlert:
type: boolean
description: Explicitly opt this request into alert tracking. Default/omitted is false.
v1GetAddressRiskScoreResponse:
type: object
properties:
chain:
type: string
title: The blockchain network
address:
type: string
title: The blockchain address
config:
type: string
description: 'Canonical name of the risk configuration that was actually applied.
May differ from the requested value when the request omitted `config`
and the server resolved the organization''s default.'
riskProfile:
type: string
title: The risk profile used for scoring
riskScore:
type: number
format: double
title: Computed risk score (0-100, hard-capped)
riskBand:
type: string
title: 'Risk band classification: "Low Risk", "Medium Risk", "High Risk", or "Severe Risk"'
breakdown:
type: array
items:
type: object
$ref: '#/components/schemas/v1RiskScoreItem'
title: Detailed breakdown of risk contributions
timestamp:
type: string
format: date-time
title: Timestamp of the computation
title: Response message for GetAddressRiskScore
RiskLevel:
type: string
enum:
- high
- medium
- low
- nondeterministic
title: RiskLevel
description: 'DEPRECATED: Risk level classification. Use found_risk boolean instead.'
v1RiskBreakdown:
type: object
properties:
type:
$ref: '#/components/schemas/v1RiskType'
title: Risk type
category:
type: string
title: Risk category (e.g., sanctions, scam, darknet)
direction:
$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.
Range 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
v1ScreenAddressResponse:
type: object
properties:
config:
type: string
description: 'Canonical name of the risk configuration that was actually applied.
May differ from the requested value when the request omitted `config`
and the server resolved the organization''s default.'
chain:
type: string
title: The bloc
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cipherowl/refs/heads/main/openapi/cipherowl-srr-api-api-openapi.yml