TraceRule API
The TraceRule API gives your platform real-time Travel Rule screening powered by an AI reasoning agent. Submit a transaction, get a PASS / HOLD / BLOCK decision with a plain-language rationale in under 2 seconds.
Base URL: https://api.tracerule.com/v1
All requests use HTTPS. The API accepts and returns JSON.
This is a preview API. Endpoints and field names are stable but may be extended. We follow semver - breaking changes are versioned.
Authentication
All API requests require a Bearer token in the Authorization header. Generate API keys from the TraceRule dashboard under Settings - API Keys.
Authorization: Bearer tr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
API key prefixes
| Prefix | Environment | Description |
|---|
| tr_live_ | Production | Real screening against live TRISA network and sanctions feeds |
| tr_test_ | Sandbox | Deterministic test responses - safe for CI/CD pipelines |
Screen a transaction
Submit a transaction for AI-powered Travel Rule screening. The agent evaluates counterparty VASP status, TRISA attestation, sanctions exposure, jurisdiction risk, and transaction size to issue a decision in real time.
Request body
| Field | Type | Required | Description |
|---|
| transaction_id | string | required | Your internal transaction reference |
| amount | number | required | Transaction value in the asset's base unit |
| asset | string | required | Asset ticker, e.g. "USDT", "BTC", "ETH" |
| originator | object | required | Originating customer (IVMS101 NaturalPerson or LegalPerson) |
| beneficiary | object | required | Beneficiary customer (IVMS101 NaturalPerson or LegalPerson) |
| counterparty_vasp_did | string | optional | DID of the counterparty VASP if known. Skips VASP lookup. |
| counterparty_address | string | optional | On-chain wallet address of the beneficiary |
| direction | string | optional | "outgoing" (default) or "incoming" |
| metadata | object | optional | Arbitrary key/value pairs passed through to webhook events |
curl https://api.tracerule.com/v1/transactions/screen \
-H "Authorization: Bearer tr_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"transaction_id": "TXN-2847-AE",
"amount": 48200,
"asset": "USDT",
"originator": {
"name": "Rania Al Masri",
"account_number": "acc_9182736"
},
"beneficiary": {
"name": "Zhang Wei",
"vasp_name": "Huobi"
},
"counterparty_address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
}'
{
"id": "tr_scr_01HXYZ123",
"transaction_id": "TXN-2847-AE",
"decision": "HOLD",
"rationale": "Grey-list jurisdiction (HK) + high value ($48,200) warrants enhanced due diligence. TRISA verified but no EDD documentation on file. Recommend HOLD pending EDD pack.",
"risk_score": 67,
"flags": ["grey_list_jurisdiction", "high_value", "edd_required"],
"counterparty_vasp": {
"name": "Huobi Global",
"did": "did:trisa:huobi.global",
"trisa_verified": true,
"jurisdiction": "HK",
"fatf_status": "grey-list"
},
"sanctions_check": { "hit": false, "lists_checked": ["OFAC-SDN", "OFAC-NonSDN", "UN", "EU-EEAS", "UK-OFSI", "UAE-MoF", "CBUAE", "MAS-SG", "HK-SCSML", "AU-DFAT", "CA-SEMA", "CH-SECO", "INTERPOL", "FATF-GREY", "OpenSanctions-PEP"] },
"pep_check": { "hit": true, "matched_name": "Tariq Al-Badawi", "pep_type": "Senior Government Official", "pep_position": "Former Deputy Minister of Finance", "pep_country": "AE", "source": "OpenSanctions PEPs", "edd_required": true },
"country_risk": { "origin_iso2": "AE", "origin_risk_tier": "elevated", "origin_fatf_status": "compliant", "dest_iso2": "SA", "combined_tier": "elevated", "requires_edd": true },
"latency_ms": 1134,
"created_at": "2025-03-15T09:42:11Z"
}
Get a screening decision
Retrieve the screening result for a previously submitted transaction by its TraceRule ID.
curl https://api.tracerule.com/v1/transactions/tr_scr_01HXYZ123 \
-H "Authorization: Bearer tr_live_xxxx"
List transactions
Returns a paginated list of screening decisions, newest first. Supports filtering by decision, date range, and risk score.
Query parameters
| Param | Type | Description |
|---|
| limit | integer | Number of results per page (default 20, max 100) |
| after | string | Cursor for pagination (from previous response) |
| decision | string | Filter by decision: PASS, HOLD, or BLOCK |
| from | string | ISO 8601 start date |
| to | string | ISO 8601 end date |
Search VASP directory
Search the TraceRule VASP directory (290+ entities, 16 jurisdictions) by name, jurisdiction, or DID. Returns TRISA verification status, FATF jurisdiction rating, and supported Travel Rule protocols.
curl "https://api.tracerule.com/v1/vasps?q=Binance&jurisdiction=UAE" \
-H "Authorization: Bearer tr_live_xxxx"
{
"data": [{
"did": "did:trisa:binance.com",
"name": "Binance",
"jurisdiction": "UAE",
"fatf_status": "compliant",
"trisa_verified": true,
"protocols": ["TRISA", "TRP"],
"regulatory_status": "VASP (VARA-licensed)"
}],
"total": 1,
"next_cursor": null
}
Webhook events
TraceRule sends a POST request to your configured endpoint immediately after every screening decision. Each event includes the full decision payload and a signature for verification.
Signature verification: Each webhook includes a Tracerule-Signature header - an HMAC-SHA256 of the raw request body signed with your webhook secret.
transaction.passed
Transaction cleared all checks. Safe to process automatically.
transaction.held
Transaction flagged for manual review. Compliance officer action required before release.
transaction.blocked
Transaction blocked - sanctions hit or critical compliance failure. Do not process. STR draft auto-generated if SAR/STR feature enabled.
transaction.overridden
Compliance officer manually overrode a HOLD decision. Payload includes override reason and officer ID for audit trail.
{
"event": "transaction.held",
"timestamp": "2025-03-15T09:42:12Z",
"data": {
"id": "tr_scr_01HXYZ123",
"transaction_id": "TXN-2847-AE",
"decision": "HOLD",
"rationale": "Grey-list jurisdiction + high value warrants EDD...",
"risk_score": 67
}
}
Register a webhook endpoint
Configure a URL to receive real-time decision events. You can subscribe to specific event types or receive all events.
curl https://api.tracerule.com/v1/webhooks \
-H "Authorization: Bearer tr_live_xxxx" \
-d '{
"url": "https://your-platform.com/webhooks/tracerule",
"events": ["transaction.held", "transaction.blocked"],
"description": "Production compliance queue"
}'
Screen an entity against all watchlists
Screen an individual or legal entity against all 15 active watchlists simultaneously — OFAC SDN, OFAC Non-SDN, UN Consolidated, EU EEAS, UK OFSI, UAE MoF, CBUAE, MAS Singapore, HK SCSML, AU DFAT, CA SEMA, CH SECO, Interpol, FATF High-Risk, and OpenSanctions PEP. Returns per-list hit status, confidence score, and matched aliases.
Request body
| Field | Type | Required | Description |
|---|
| name | string | required | Full legal name of the individual or entity to screen |
| dob | string | optional | Date of birth (ISO 8601) — improves match precision for individuals |
| nationality | string | optional | ISO 3166-1 alpha-2 country code |
| lists | array | optional | Subset of list IDs to check. Omit to check all 15 lists. |
| fuzzy_threshold | number | optional | Name match confidence threshold 0–1 (default 0.85) |
curl https://api.tracerule.com/v1/sanctions/screen \
-H "Authorization: Bearer tr_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Viktor Medvedchuk",
"dob": "1954-08-07",
"nationality": "UA"
}'
{
"name": "Viktor Medvedchuk",
"screened_at": "2026-03-29T11:22:00Z",
"overall_hit": true,
"risk_level": "BLOCK",
"lists_checked": 15,
"hits": [
{ "list": "OFAC-SDN", "confidence": 0.99, "matched_alias": "MEDVEDCHUK, Viktor Volodymyrovych" },
{ "list": "EU-EEAS", "confidence": 0.99, "matched_alias": "Viktor Volodymyrovych Medvedchuk" },
{ "list": "UK-OFSI", "confidence": 0.97, "matched_alias": "Viktor Medvedchuk" }
],
"latency_ms": 28
}
PEP lookup
Search the OpenSanctions PEP database (1.4M+ entities, 190+ source lists) for a named individual. Returns PEP classification, position held, jurisdiction, and associated entities. Covers heads of state, senior officials, their family members, and close associates.
Query parameters
| Param | Type | Description |
|---|
| name | string | Name to search (partial match supported) |
| jurisdiction | string | ISO 3166-1 alpha-2 filter (e.g. RU, AE, CN) |
| include_family | boolean | Include immediate family members and associates (default true) |
| limit | integer | Results per page (default 10, max 50) |
curl "https://api.tracerule.com/v1/pep/search?name=Rotenberg&jurisdiction=RU" \
-H "Authorization: Bearer tr_live_xxxx"
{
"total": 3,
"results": [
{
"name": "Arkady Romanovich Rotenberg",
"pep_tier": 1,
"position": "Businessman — close associate of Vladimir Putin",
"jurisdiction": "RU",
"sources": ["OFAC-SDN", "EU-EEAS", "UK-OFSI", "OpenSanctions"],
"associated_entities": ["Boris Rotenberg", "Igor Rotenberg"]
}
],
"latency_ms": 19
}
List active watchlists
Returns metadata for all 15 active watchlists — entity count, last refresh timestamp, issuing authority, and jurisdiction coverage.
curl https://api.tracerule.com/v1/sanctions/lists \
-H "Authorization: Bearer tr_live_xxxx"
Error codes
TraceRule uses standard HTTP status codes. Error responses include a machine-readable code and a human-readable message.
400invalid_requestMissing or malformed fields. Check the errors array in the response.
401unauthorizedInvalid or missing API key.
402quota_exceededMonthly transaction quota reached. Upgrade your plan.
422ivms_validation_errorOriginator or beneficiary data fails IVMS101 validation. Check the fields array.
429rate_limitedToo many requests. See Retry-After header.
503screening_unavailableAI screening temporarily unavailable. Retry with exponential backoff.
Rate limits
Rate limits are applied per API key. Burst capacity allows short spikes above the sustained rate.
| Plan | Sustained | Burst | Monthly quota |
|---|
| Starter | 10 req/s | 30 req/s | 10,000 transactions |
| Professional | 100 req/s | 300 req/s | 100,000 transactions |
| Enterprise | Custom | Custom | Unlimited |
All responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.