Transaction Monitoring (KYT / KYA) API

The Transaction Monitoring API provides a single unified endpoint for crypto risk screening:

KYA — Know Your Address: risk-score a wallet/address and (optionally) return its exposure, entities, and activity summary.
KYT — Know Your Transaction: risk-score a transaction hash and (optionally) return its entities, flags, amounts, and inputs/outputs.

Both are served by the same endpoint — you choose which one with the type field.

Base URL

https://api2.cycurid.com

Authentication

POST /v2/public/transaction-monitoring uses Basic Authentication with your merchant credentials:

Username: {{merchantApiKey}}
Password: {{merchantSecret}}

Authorization: Basic base64(merchantApiKey:merchantSecret)

Endpoint

POST `/v2/public/transaction-monitoring`

Screen a single address or transaction.

Content-Type

application/json

Request Parameters

Field	Type	Required	Description
`type`	string	Yes	What to screen: `"address"` (KYA) or `"transaction"` (KYT).
`query`	string	Yes	The wallet address or transaction hash to screen. 1–255 characters; only `A–Z a–z 0–9 : _ -` are allowed (covers bech32, CashAddr, and standard hash/address formats).
`currency`	string	Yes	The chain's ISO currency code, e.g. `"btc"`, `"eth"`, `"sol"`. Validated server-side; an unsupported value returns the list of supported currencies (see Supported Currencies).
`report`	string	No	Detail level: `"simple"` (default) returns just the risk score; `"detailed"` returns entities, flags, and activity/exposure data.
`label`	string	No	A free-text label stored with the query for your own reference (max 255 chars). Defaults to `"API Query"`.

simple vs. detailed

Use simple for a fast risk gate (score only). Use detailed when you need the supporting evidence — counterparty entities, risk flags, exposure breakdown, and (for transactions) amounts and inputs/outputs.

Usage Examples

Example 1: Address risk check (KYA, simple)

curl -X POST 'https://api2.cycurid.com/v2/public/transaction-monitoring' \
  -u '{{merchantApiKey}}:{{merchantSecret}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "address",
    "query": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "currency": "btc"
  }'

Example 2: Transaction risk check (KYT, detailed)

curl -X POST 'https://api2.cycurid.com/v2/public/transaction-monitoring' \
  -u '{{merchantApiKey}}:{{merchantSecret}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "transaction",
    "report": "detailed",
    "query": "0x9c2b19a3f4e...c1",
    "currency": "eth",
    "label": "settlement batch #42"
  }'

Response Format

A successful screen returns HTTP 200. The response always includes a score (the provider's risk score) plus the echoed type, query, currency, label, and a queryId you can use to reference this lookup.

Address — simple

{
  "queryId": "b7c1e2a4-...",
  "type": "address",
  "query": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "currency": "btc",
  "score": 12,
  "label": "API Query"
}

Address — detailed

Adds counterparty and activity data (fields present depend on the chain and what the provider has indexed):

{
  "queryId": "b7c1e2a4-...",
  "type": "address",
  "query": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "currency": "btc",
  "score": 12,
  "label": "API Query",
  "newAddress": false,
  "entities": [ { "name": "Example Exchange", "category": "exchange" } ],
  "flags": [ { "name": "sanctions_exposure", "category": "sanctions" } ],
  "cluster": "cluster-id",
  "firstSeenReceiving": "2019-03-04T00:00:00Z",
  "lastSeenSending": "2024-11-20T00:00:00Z",
  "receivedAmount": 1.2345,
  "sentAmount": 1.2000,
  "numberOfTransactions": 87,
  "balance": 0.0345,
  "isOwner": true,
  "ownerAddress": "1A1zP1eP...",
  "organizationLabelName": "Example Exchange",
  "exposures": { "...": "exposure breakdown" }
}

Field (detailed)	Description
`newAddress`	Whether the address is newly seen / unindexed.
`entities`	Known entities associated with the address.
`flags`	Risk flags with category.
`cluster`	Provider cluster identifier.
`firstSeenReceiving` / `firstSeenSending` / `lastSeenReceiving` / `lastSeenSending`	Activity timestamps.
`receivedAmount` / `sentAmount` / `balance`	Native-currency totals.
`numberOfTransactions` / `receivedTransactions` / `sentTransactions`	Transaction counts.
`isOwner` / `ownerAddress` / `organizationLabelName` / `organizationLabelId`	Ownership / labeling.
`exposures`	Detailed exposure breakdown (entity / flag / rank exposures).

Transaction — simple

{
  "queryId": "3f9a0c11-...",
  "type": "transaction",
  "query": "0x9c2b19a3f4e...c1",
  "currency": "eth",
  "score": 30,
  "label": "settlement batch #42"
}

Transaction — detailed

Adds entities, flags, amounts, and inputs/outputs:

{
  "queryId": "3f9a0c11-...",
  "type": "transaction",
  "query": "0x9c2b19a3f4e...c1",
  "currency": "eth",
  "score": 30,
  "label": "settlement batch #42",
  "entities": [ { "name": "Example Mixer", "category": "mixer" } ],
  "flags": [ { "name": "mixer_exposure", "category": "anonymity" } ],
  "low": 10,
  "median": 30,
  "average": 32,
  "high": 65,
  "timestamp": "2024-11-20T14:03:11Z",
  "amount": 2.5,
  "amountFiat": 8123.44,
  "fees": 0.0012,
  "feesFiat": 3.90,
  "inputs": [ { "address": "0x...", "amount": 2.5 } ],
  "outputs": [ { "address": "0x...", "amount": 2.4988 } ]
}

Field (detailed)	Description
`entities` / `flags`	Counterparty entities and risk flags.
`low` / `median` / `average` / `high`	Score distribution across the transaction's exposure.
`timestamp`	Transaction time.
`amount` / `amountFiat` / `fees` / `feesFiat`	Value and fees (native + fiat).
`inputs` / `outputs`	Per-address input/output breakdown.

Solana transactions

For currency: "sol", detailed transaction responses may also include solBalChange, tokenBalChange, listSigner, and tokenMetadata.

Error Responses

Status	Meaning
400	Validation failed (bad/empty `query`, invalid characters, missing `type`/`currency`) — see below.
400	Unsupported currency — the message lists the supported currencies.
401	Missing or invalid Basic Auth credentials.
404	The address or transaction was not found / not yet processed by the provider.
429	Rate limit exceeded.
502 / 503 / 504	The upstream risk provider returned an error, was unreachable, or timed out — retry shortly.

400 — Validation Error

{
  "success": false,
  "message": "Validation failed",
  "errors": ["query - query contains invalid characters"]
}

400 — Unsupported Currency

{
  "success": false,
  "message": "Unsupported currency: \"abc\". Supported currencies are: btc, eth, sol, ..."
}

404 — Not Found / Not Yet Processed

{
  "success": false,
  "message": "Not found. The address or transaction may not have been processed yet."
}

401 — Unauthorized

{
  "message": "Invalid Merchant or Secret Key"
}

503 — Provider Unavailable

{
  "success": false,
  "message": "Risk provider is temporarily unavailable. Please retry shortly."
}

Supported Currencies

Currencies are validated server-side against the supported list. Commonly supported chains include: btc, eth, ltc, bch, bsv, xrp, xlm, doge, dash, zec, etc, bsc, ada, stx, xdc, sys, and sol.

If you submit an unsupported code, the 400 response lists the exact set of currencies currently accepted for your account.

Environment Variables

When using the Postman collection, configure these variables:

Variable	Description	Example Value
`baseUrl`	API base URL	`https://api2.cycurid.com`
`merchantApiKey`	Your merchant API key	Provided in portal
`merchantSecret`	Your merchant secret	Provided in portal

Transaction Monitoring (KYT / KYA) API

Base URL​

Authentication​

Endpoint​

POST /v2/public/transaction-monitoring​

Content-Type​

Request Parameters​

Usage Examples​

Example 1: Address risk check (KYA, simple)​

Example 2: Transaction risk check (KYT, detailed)​

Response Format​

Address — simple​

Address — detailed​

Transaction — simple​

Transaction — detailed​

Error Responses​

400 — Validation Error​

400 — Unsupported Currency​

404 — Not Found / Not Yet Processed​

401 — Unauthorized​

503 — Provider Unavailable​

Supported Currencies​

Environment Variables​