Travel Rule network messaging overview
Resolve the beneficiary, encrypt and deliver the message, then handle updates.
This guide covers Partner -> CryptoSwift: your network sends messages through the standardized Partner API using X-Partner-Api-Key. For the opposite direction, see the CryptoSwift-to-Partner contract.
Before you start
Exchange participant VASP directories and public keys as described in Network Integration & Prerequisites. CryptoSwift needs your originating VASP's directory record to validate its ID and attach the sender details.
Keep the Partner API key and private encryption keys on your backend. Use the correct environment's API root and credentials.
Workflow
| Step | Endpoint | Details |
|---|---|---|
| 1. Resolve the beneficiary VASP. | GET /partners/vasps or GET /partners/vasps/by-wallet | Select a verified VASP and retrieve its public key. |
| 2. Deliver the message. | POST /partners/transactions | Send transaction metadata and the encrypted IVMS101 wrapper. |
| 3. Update the record. | PATCH /partners/transactions/{id} | Attach a later transaction hash or correct supported message data. |
1. Resolve the Beneficiary VASP
Search the directory when the customer selects a VASP by name. Use wallet lookup when you have the beneficiary address, blockchain, and asset. Use the returned entity ID as beneficiaryVaspId and its publicKey for encryption.
The directory can include verified partner-network entities. Set _cryptoSwiftTenantOnly=true when you specifically need directly onboarded CryptoSwift tenants. See the lookup requests and responses.
2. Deliver Travel Rule Messages
- Build a plaintext object with an
ivms101root containing Originator and Beneficiary data. See the natural-person and legal-person examples. - Encrypt the complete wrapper using the sender's private key and beneficiary's public key. Follow the Message Encryption Protocol.
- POST the transaction metadata, the encrypted base64
ivms101string, the sender ID and public key, and the beneficiary ID. - Save the returned transaction ID and process Partner webhooks for subsequent responses.
See delivery request and response examples for the complete API contract.
Choose the timing
Post-transaction flow
Include the transaction hash when the on-chain transfer has been broadcast. Your network coordinates message timing with the transfer; this API does not broadcast funds.
Pre-transaction flow
Omit the hash while your workflow evaluates the beneficiary's response. Follow Partner webhook updates, and attach the hash if your payment proceeds. Counterparty confirmation is a message-review result, not proof of blockchain settlement.
3. Update a Travel Rule Message
Use PATCH to attach the hash or correct supported data. The destination address cannot be changed. The Partner update contract differs from the tenant Transactions API; use the documented Partner schema and identifiers.
See the update request, including the fields needed when replacing encrypted IVMS101 data.
Next steps
- Messaging API examples
- IVMS101 plaintext examples
- Message encryption
- Partner webhooks and status synchronization