Travel Rule Migration Guide

Caliza is rolling out crypto Travel Rule compliance to all integrators. Most of the changes are transparent, but a few require action on your side, and some of them become mandatory on a date we will communicate to you in advance.

This page is the delta: what changes compared to how your integration works today, what you need to do, and how to test it. The reference documentation for each feature is linked from every section.

Summary

1. Creating crypto recipients

What changes. Every crypto recipient must declare where the destination wallet is hosted. Today the declaration is accepted loosely; after the rollout it is validated on every POST /v1/recipients and PUT /v1/recipients/{id}.

What you need to do.

1. Look up the hosting provider with GET /v1/recipients/vasps/search?searchQuery=... and store the returned id as details.vaspId. If the provider is not in the directory, contact Caliza support before creating the recipient.
2. For self-hosted wallets, send isNonCustodialWallet: true and, for third parties, the holder's physical address.
3. Review the crypto recipients you already have: any recipient with only a vaspName, or with the legacy NON_CUSTODIAL_WALLET value, should be updated. Payouts to a recipient that cannot be addressed to a VASP are held for manual review.

Field reference and examples: Create Recipients.

2. Payouts to self-hosted wallets

What changes. A payout to a self-hosted wallet requires a valid wallet ownership proof for the destination address. Once enforced for your account, POST /v1/simulations, POST /v2/simulations and POST /v1/transactions targeting a self-hosted recipient without a proof fail with HTTP 422 and error code travel-rule.ownership_proof_required.

What you need to do.

1. Collect a proof for every self-hosted wallet recipient you pay out to. Three methods are available; pick the one that fits how your customers hold their wallets:
   • Signature with the SafeConnect components — the wallet holder connects a browser wallet and signs in your frontend. POST /v1/travel-rule/proofs/delegate-token, then POST /v1/travel-rule/proofs.
   • Manual signature — for wallets that cannot use SafeConnect (keystore or seed-phrase holders, custody consoles, TRON wallets). POST /v1/travel-rule/proofs/manual-attestation returns the text to sign; the wallet holder signs it with their own tooling and you submit the signature to POST /v1/travel-rule/proofs. This is also the method for wallets owned by a third party: relay the attestation text, get the signature back.
   • Microtransfer (Satoshi test) — POST /v1/travel-rule/proofs/microtransfer returns an exact amount and destination; the wallet holder sends it from the wallet being proven and the proof verifies automatically when it arrives.
2. Before initiating a payout, check GET /v1/travel-rule/proofs?recipientId={id}: VERIFIED means you can proceed; 404 means no proof exists yet.
3. Handle the 422 travel-rule.ownership_proof_required response on simulations and transactions as a signal to start proof collection.
4. Plan for re-collection: proofs expire (currently one year after verification), and updating a recipient's wallet address or Travel Rule details invalidates its proofs.

Full walkthrough of each method: Self-Hosted Wallets.

3. Payouts to VASP-hosted wallets

What changes. Before the crypto leaves custody, Caliza sends the Travel Rule message to the counterparty VASP and waits for its authorization. For most transfers this is immediate. When the counterparty takes time to authorize, the payout pauses: the transaction keeps its current status (typically PROCESSING), no webhook is emitted for the pause, and it resumes automatically once the counterparty responds. If the counterparty rejects the message, the payout goes to manual compliance review.

What you need to do. Nothing in code. Make sure your monitoring tolerates crypto payouts staying in PROCESSING longer than today, and that the recipient's Travel Rule data (name, vaspId) is accurate, since incomplete or mismatched information is the usual reason for a rejection.

Details: Crypto Travel Rule — Payouts.

4. Crypto deposits

What changes. Crypto deposits at or above the per-currency threshold are held until their Travel Rule requirements are resolved: the funds arrive on-chain but are not credited to the beneficiary's balance, and PAYMENT_IN_COMPLETED only fires once the deposit is released.

• Deposit from a VASP: credited once the sender's VASP transmits the Travel Rule message and it is accepted (the beneficiary name in the message must match the beneficiary on the account). If the message arrives before the funds, nothing is held.
• Deposit from a self-hosted wallet: no VASP will send a message. After a waiting period the origin address goes through automated screening; a clean result releases the deposit, anything else goes to manual review.
• Deposits below the threshold are credited immediately, as today.

What you need to do. Nothing in code. Give your depositors the beneficiary's Travel Rule deposit information along with the wallet address, so their exchange can address the message to Caliza:

curl 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{beneficiaryId}}/travel-rule/deposit-info' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Details: Crypto Travel Rule — Deposits.

5. Recipient review

What changes. Every crypto recipient is created with reviewStatus: PENDING_REVIEW and screened right away; a clean screening approves it automatically, usually within seconds. With the Travel Rule rollout the screening also checks the declared hosting against on-chain attribution data. A contradiction — a wallet declared self-hosted that is attributed to an exchange, or declared at VASP X but attributed to VASP Y — keeps the recipient in PENDING_REVIEW until a compliance reviewer approves or rejects it. While a recipient is PENDING_REVIEW or REJECTED, simulations and transactions targeting it fail with HTTP 422 and error code recipient.under_review.

What you need to do. Nothing in code, unless you create a recipient and pay out to it in the same flow: read reviewStatus on the recipient response (or handle the 422) and retry once it is APPROVED. Double-check the hosting declaration when a recipient stays under review.

Checklist

• Crypto recipient requests send details.vaspId (from the VASP directory) or details.isNonCustodialWallet: true.
• belongsToBeneficiary is set explicitly on every crypto recipient.
• Third-party self-hosted recipients include details.recipientAddress.
• Existing crypto recipients with only a vaspName, or with the legacy NON_CUSTODIAL_WALLET value, are updated.
• Ownership proofs are collected for every self-hosted wallet recipient you pay out to, using at least one of the three methods.
• Simulations and transactions handle the 422 travel-rule.ownership_proof_required response.
• Payout monitoring tolerates crypto payouts staying in PROCESSING while the counterparty VASP authorizes.
• Depositors receive the Travel Rule deposit info together with the wallet address.
• Every flow above has been exercised in the sandbox.

Testing in sandbox

Every behavior on this page can be exercised in the sandbox: simulate the counterparty's authorization or rejection on a payout, simulate inbound Travel Rule messages on deposits, and collect proofs against Notabene's test environment. See Testing Travel Rule in Sandbox.

Related Articles