Submit a transaction for monitoring
Screens the transaction in real time against your account's monitoring
rules and policy. For crypto transactions the counterparty wallet (or the
settled on-chain transaction, when transaction_hash is provided) is
screened for sanctions, mixer, darknet, and other source-of-funds risk.
For a crypto transaction with screening enabled you must supply
counterparty.wallet_address (the external wallet screened for risk), and
for an inbound transfer also subject.wallet_address (the deposit address);
omitting them returns 422. Set blockchain_network (e.g. ethereum, tron) to
disambiguate multi-chain assets such as USDT and to drive chain-based rules,
contract_address for on-chain tokens, and transaction_at when back-dating
so time-window rules aggregate on the real transaction time.
Returns a decision: APPROVED, IN_REVIEW, DECLINED, or AWAITING_USER (the
end user must complete a verification via the returned remediation url).
Resubmitting the same client_reference returns the existing record and
is never double-charged. In sandbox, requests beyond the monthly free
quota are rejected with 429; in production each submitted transaction
records a billable usage event.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Two ways to use it
- Pre-transfer check — before you send or accept funds, submit the transaction with the counterparty wallet address (no
transaction_hash). Use the returned decision to allow, hold, or block the movement. - Post-settlement record — once a transfer has settled on-chain, submit it again (or for the first time) with the
transaction_hash. This documents the source-of-funds trail of that specific transfer for audit and compliance.
Both use this same endpoint; transaction_hash is optional and is what distinguishes the two.
matched_rules and crypto_screening shape
Each matched_rules entry contains: category, score_delta, status_target, matched.
crypto_screening uses the same shape as the Wallet Screening response body (risk_score, severity, source_of_funds, destination_of_funds, counterparty_connections, and their *_truncated flags).
Decisions
| Decision | Meaning |
|---|---|
APPROVED | No action needed. |
IN_REVIEW | Flagged for manual review. Hold the funds until it resolves; you will be notified of the final decision by webhook. |
DECLINED | Block the transaction. |
AWAITING_USER | The end user must complete an additional verification. Redirect them to remediation.url. When they finish, the decision updates and a webhook is sent. |
Decisions reflect both the rule engine and your account policy: sanctions exposure or a declined risk category blocks automatically (if enabled in your policy), a risk score or EUR amount at or above your decline threshold/cap blocks, and at or above your review threshold/cap holds for review. The platform default is review_threshold: 60, decline_threshold: 85, sanctions auto-decline on, and auto_decline_categories: ["sanctioned", "terrorist_financing", "child_exploitation"]. Configure these via Get/Update Monitoring Policy.
decision_reason explains which rule fired:
| Reason | Meaning |
|---|---|
sanctions_exposure | Sanctions hit, and sanctions auto-decline is on |
risk_category:<category> | The dominant risk category is in auto_decline_categories |
score_decline_threshold | Risk score at or above your decline threshold |
score_review_threshold | Risk score at or above your review threshold (below decline) |
amount_decline_cap | EUR amount above your decline cap |
amount_review_cap | EUR amount above your review cap (below decline cap) |
screening_unavailable | Screening was requested but failed; held for review rather than left approved |
unrecognized_provider_status | Fallback when the upstream status is unrecognized |
null means no escalation was needed (typically APPROVED).
AWAITING_USER remediation
When decision is AWAITING_USER, the response includes:
{ "remediation": { "url": "https://.../verify/...", "status": "pending" } }Redirect the end user to remediation.url. On completion the transaction moves to its final decision and a monitoring.transaction.status_changed webhook is sent.
Webhooks
If you have a webhook endpoint configured, subscribe to monitoring.transaction.status_changed. It fires whenever a transaction's decision changes after submission (for example, an IN_REVIEW transaction being resolved, or an AWAITING_USER remediation completing). The payload includes monitored_transaction_id, client_reference, previous_decision, decision, and decision_reason.
Sandbox vs. production
In sandbox, each account has a monthly free quota of submissions; requests beyond it return 429, and sandbox submissions are never billed. In production, each submitted transaction records one billable usage event — a resubmitted client_reference is never charged again.
Errors
| Code | Meaning |
|---|---|
403 | Transaction monitoring is not enabled for your account — contact support to request access |
422 | Request validation failed |
429 | Sandbox monthly quota exhausted |
502 | The upstream monitoring provider returned an error; retry later |
503 | Monitoring service temporarily unavailable or not configured; retry later |