Collecting Travel Rule Information

When and how to collect Travel Rule metadata from your end users.

Two integration patterns are supported. Pick based on your end users’ transfer profile.

Patterns

Pattern A: Collect up-front

Collect Travel Rule information at the moment a new destination address is saved. The address cannot be used for above-threshold transfers until valid metadata is attached.

Use this when: most of your transfers are likely to cross the $3,000 threshold, or you’d rather collect once and avoid interrupting users at transaction time. Recommended for most integrations.

Pattern B: Try-catch on transaction

Save the destination address without Travel Rule metadata. Attempt the withdrawal or orchestration. If the transaction crosses the threshold, the API returns a 403 with a typed error. Collect the metadata, PUT it onto the destination address, and retry.

Use this when: most of your transfers are under $3,000 and you want to avoid front-loading data collection. Common for retail/consumer flows.

Mixing patterns

You can use both. A common approach: Pattern A for addresses tagged as “business” (likely high-value), Pattern B for addresses tagged as “personal” (likely small transfers).

Examples

Crypto Withdrawal

Pattern A — $5,000 USDG withdrawal to a Coinbase account.

1. Resolve the receiving VASP

   See GET /v2/travelrule/vasps API reference.

   GET /v2/travelrule/vasps?search=coinb&limit=10
   

   Response:

   {
     "items": [
       {
         "id": "vasp_01HXYZABC123",
         "name": "Coinbase, Inc."
       },
       {
         "id": "vasp_01HXYZDEF456",
         "name": "Coinbase Custody Trust"
       }
     ]
   }
   

   The user picks Coinbase, Inc. from your type-ahead. You capture vasp.id = "vasp_01HXYZABC123".

2. Save the destination address with Travel Rule metadata

   See PUT /v2/transfer/crypto-destination-address API reference.

   PUT /v2/transfer/crypto-destination-address
   

   Request:

   {
     "crypto_network": "ETHEREUM",
     "address": "0xe4B0aCA9FB669817775274775b20e52118595515",
     "nickname": "alice_coinbase",
     "identity_id": "b8d9f2a1-3c4e-4f5a-9b6d-7e8f0a1b2c3d",
     "travelrule_metadata": {
       "custodian_type": "VASP",
       "beneficiary": {
         "person_details": {
           "first_name": "Alice",
           "last_name": "Smith",
           "physical_address": {
             "country": "US"
           }
         }
       },
       "vasp": {
         "id": "vasp_01HXYZABC123"
       },
       "transfer_purpose": "TRANSFER_PURPOSE_SAVINGS"
     }
   }
   
3. Create the withdrawal

   Travel Rule metadata is resolved from the saved address. See POST /v2/transfer/crypto-withdrawals API reference.

   POST /v2/transfer/crypto-withdrawals
   

   Request:

   {
     "ref_id": "unique_withdrawal_ref_001",
     "profile_id": "b7b77d82-e6a7-4ae9-9904-36231aedf985",
     "identity_id": "b8d9f2a1-3c4e-4f5a-9b6d-7e8f0a1b2c3d",
     "asset": "USDG",
     "crypto_network": "ETHEREUM",
     "amount": "5000",
     "destination_address": "0xe4B0aCA9FB669817775274775b20e52118595515"
   }
   

   The withdrawal is created. Paxos transmits the Travel Rule message to the receiving institution before broadcasting on-chain.

Orchestration

1. Resolve the receiving VASP

   Same as the crypto withdrawal example above.

2. Save the destination address with Travel Rule metadata

   Same as the crypto withdrawal example above.

3. Create the orchestration

   The orchestration references the saved address by (network, address). See POST /v2/orchestration/orchestrations API reference.

   Request:

   {
     "ref_id": "orch-usdg-eth-001",
     "identity_id": "b8d9f2a1-3c4e-4f5a-9b6d-7e8f0a1b2c3d",
     "source_asset": "USDC",
     "destination_asset": "USDG",
     "source_amount": "5000",
     "source": {
       "profile": {
         "profile_id": "7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c"
       }
     },
     "destination": {
       "crypto": {
         "network": "ETHEREUM",
         "address": "0xe4B0aCA9FB669817775274775b20e52118595515"
       }
     }
   }
   

   Travel Rule metadata is resolved from the saved destination address at execution time.

Orchestration Rules require Travel Rule metadata on the referenced destination address regardless of expected transaction size, because incoming deposits that trigger a rule are unpredictable in amount.

Additional scenarios

Self-transfers (me-to-me)

Set beneficiary.self = true and omit person_details and institution_details. The server resolves the end user’s details from their identity. No vasp object is required.

Unhosted/self-hosted wallets

Set custodian_type to PRIVATE and omit vasp. No Travel Rule message is transmitted, but the metadata is still required to record the determination.

VASP not in the Paxos directory

Provide vasp.name and vasp.website_url of the provider hosting the wallet. Paxos Compliance handles the off-directory Travel Rule obligation. Paxos continuously expands directory coverage based on customer transaction patterns.

Updating Travel Rule metadata on an existing address

Call PUT /v2/transfer/crypto-destination-address with either the id of the address or the crypto_network and address to update the travelrule_metadata object. Subsequent transactions to that address will use the updated metadata.