Collecting Travel Rule Information

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.

Resolve the receiving VASP

See GET /v2/travelrule/vasps API reference.

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

Response:

{
  "items": [
    {
      "id": "0b3d9f1e-7c2a-4e8b-9f1a-2c3d4e5f6a7b",
      "name": "Coinbase, Inc."
    },
    {
      "id": "1c4e0a2f-8d3b-4f9c-8a2b-3d4e5f6a7b8c",
      "name": "Coinbase Custody Trust"
    }
  ]
}

The user picks Coinbase, Inc. from your type-ahead. You capture vasp.id = "0b3d9f1e-7c2a-4e8b-9f1a-2c3d4e5f6a7b".

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": "USA"
        }
      }
    },
    "vasp": {
      "id": "0b3d9f1e-7c2a-4e8b-9f1a-2c3d4e5f6a7b"
    },
    "transfer_purpose": "Investment"
  }
}

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

Resolve the receiving VASP

Same as the crypto withdrawal example above.

Save the destination address with Travel Rule metadata

Same as the crypto withdrawal example above.

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.

Testing the rejection flow

Before enforcement begins, above-threshold transfers don’t yet return the 403, so there’s no natural way to exercise your Pattern B retry path. To trigger the error on demand, send the X-Paxos-Test-Travel-Rule-Reject header (any non-empty value) on a transaction request:

curl -X POST 'https://api.sandbox.paxos.com/v2/transfer/crypto-withdrawals' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Paxos-Test-Travel-Rule-Reject: true' \
  -H 'Content-Type: application/json' \
  -d '{ ...withdrawal body... }'

Any request carrying the header returns 403 Travel Rule Information Required — regardless of amount or whether the destination already has Travel Rule metadata — so you can verify your catch → collect → PUT → retry handling end to end. It works on all four transaction endpoints:

Use this header only while testing in sandbox, and remove it for real transfers — it forces the rejection on the request that carries it.

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. For a self-transfer to an unhosted wallet, set custodian_type = PRIVATE and omit vasp. For a self-transfer to your own account at another VASP, set custodian_type = VASP and still provide vasp so Paxos can identify the receiving institution.

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.custom_vasp_name and vasp.custom_vasp_website 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.

Get Started

Identity

Travel Rule

Stablecoin Orchestration

Fiat Transfers

Address Verification

Stablecoin Payments

Crypto Brokerage

Webhooks

Additional Guides

Versioning

Collecting Travel Rule Information

Patterns

Pattern A: Collect up-front

Pattern B: Try-catch on transaction

Mixing patterns

Examples

Crypto Withdrawal

Orchestration

Testing the rejection flow

Additional scenarios

Self-transfers (me-to-me)

Unhosted/self-hosted wallets

VASP not in the Paxos directory

Updating Travel Rule metadata on an existing address

​Patterns

​Pattern A: Collect up-front

​Pattern B: Try-catch on transaction

​Mixing patterns

​Examples

​Crypto Withdrawal

​Orchestration

​Testing the rejection flow

​Additional scenarios

​Self-transfers (me-to-me)

​Unhosted/self-hosted wallets

​VASP not in the Paxos directory

​Updating Travel Rule metadata on an existing address

Patterns

Pattern A: Collect up-front

Pattern B: Try-catch on transaction

Mixing patterns

Examples

Crypto Withdrawal

Orchestration

Testing the rejection flow

Additional scenarios

Self-transfers (me-to-me)

Unhosted/self-hosted wallets

VASP not in the Paxos directory

Updating Travel Rule metadata on an existing address