Parameters

This section explains the common parameters used in CipherOwl API requests. Each parameter defines the behavior and scope of the API call.

Chain

The chain parameter specifies the blockchain network on which the query will be performed. The value must be one of the following:

• bitcoin
• evm
• tron
• solana
• bitcoin_cash
• bitcoin_gold
• bitcoin_sv
• dash
• litecoin
• monero
• verge
• xrp
• zcash

EVM addresses are shared across all EVM-compatible networks (e.g., Ethereum, Base, Optimism, etc.). Risk is evaluated based on address behavior across all EVM networks. Therefore, use evm as the chain value when querying EVM addresses.

Address

The address parameter is the blockchain address to screen or score. It is supplied in the request path for single-address endpoints and in the request body for batch endpoints. Its format follows the target chain:

• EVM networks: 0x-prefixed 40-character hex, checksummed or lowercase (use evm as the chain).
• Bitcoin and Bitcoin-derived chains: base58 (1…, 3…) or bech32 (bc1…) formats.
• Solana: base58.
• Tron: base58check (T…).
• Other supported chains (xrp, zcash, etc.): that chain's canonical address format.

Preserve the address exactly as issued: base58 formats (Solana, Tron) are case-sensitive, so do not change their casing. EVM addresses are accepted as either checksummed or lowercase hex.

Config

The config parameter selects a preconfigured risk model — the risk categories, hop depths, and thresholds — that the API applies when screening or scoring an address. It is optional: when omitted (or sent empty), the server resolves your organization's default configuration for the requested chain and returns the resolved name.

Risk configurations are scoped to the caller's organization, determined by the API key.

Canonical configurations

CipherOwl-managed configurations are prefixed with co-. The current
catalog covers three profiles:

An unprefixed name (e.g. defi) resolves against your organization's
customized configurations — configurations your organization has
defined on top of the CipherOwl catalog. If no org-specific configuration
matches the name, the request is rejected.

Legacy names like high_risk_hops_2 or co-high_risk_ext_hops_4 continue
to work — the server transparently maps (co-)high_risk_hops_N to co-defi
and (co-)high_risk_ext_hops_N to co-institution. New integrations should
use the canonical names.

Resolved configuration in responses

Every screening / scoring response tells you which configuration was actually applied — this may differ from the request when the request omitted config and the server resolved your organization's default.

• The screening and reason endpoints return a config field in the response body.
• The report endpoints (/api/report/v1/…) return the resolved name in the cipherowl-resolved-config response header.

Chain support

Bitcoin, EVM, TRON, and Solana support the full canonical set (co-defi, co-institution, co-vasp). Other supported chains (bitcoin_cash, bitcoin_gold, bitcoin_sv, dash, litecoin, monero, verge, xrp, zcash) support only a reduced set — typically co-defi and co-institution at limited hop depths. Configurations available to your organization may be further restricted by tier; contact CipherOwl if you need a configuration that isn't listed.

Hops

The hops parameter (integer, 0–8) sets the multihop tracing depth for a screening query. When provided, the server evaluates every hop from 0 up to the requested value; when omitted, the request uses the selected configuration's built-in default reach. Larger values widen indirect-exposure detection at some additional latency, so raise it only when you need deeper tracing than the configuration's default.

Track alert

The trackAlert parameter (boolean, default true) controls whether a screening request is tracked for case creation. Omitting it means true; pass trackAlert=false to opt an individual request out. When it is on and the screening finds risk, that result can be recorded as a case for follow-up. trackAlert never changes the risk verdict itself; case creation additionally depends on server-side enablement and your organization's configuration, and only happens for risk-found results.

Reference

The reference parameter is an optional, opaque label you attach to a screening request for your own attribution — for example a sub-tenant, team, or workflow identifier. It is available on the address screening endpoints (single, batch, and their multi-config variants) and on the risk-based transaction screening endpoint.

Contract

• Opaque. CipherOwl never parses, interprets, or acts on the value, and it does not affect the screening result.
• Normalization and validation. The value is trimmed and lowercased, then must be one or more dot-separated segments of [a-z0-9_] (lowercase letters, digits, underscore), up to 256 characters — for example, binance.compliance.apac. Values that fail validation are rejected with 400 INVALID_ARGUMENT.
• Empty means unreferenced. An empty or whitespace-only value is treated as absent; the request is simply unreferenced.
• Customer-supplied and reusable. You choose the value and may reuse it across as many requests as you like — it is not required to be unique, and CipherOwl never generates one for you.
• No registration. References are not registered or checked against a catalog beforehand; a mistyped value is accepted as-is (subject to the format rules above), so treat it as a free-form tag that you are responsible for.

Echoed on the response

Every screening response returns the applied reference (after normalization). When the request was unreferenced, the field is absent from the response.

Where it propagates

When you supply a reference, it is currently stamped on:

• the structured screening logs that make up the request audit trail, and
• the screening record created when trackAlert is set and the screening finds risk (the reference travels with that recorded case).

It never appears as a metrics label, and it is not used for billing or usage attribution.

Not to be confused with

• Address label tags returned by the Screen and Report APIs. Those are CipherOwl-assigned attributes of an on-chain address; reference is your own request-side label and says nothing about the address.
• XRP/XLM destination tags (and memos). Those are on-chain routing values that identify a beneficiary at a shared address; reference is never sent on-chain and has no effect on settlement.