Travel Rule deposit via the REST API

This guide walks you through resolving a Travel Rule request for information (RFI) on an on-hold crypto deposit directly through the API — from detecting the on-hold status to submitting proof and allowing the transaction to proceed.

Prefer a managed UI? See Travel Rule deposit via the Travel Rule Widget — it handles the proof collection form for you.

Prerequisites

The user has completed onboarding and has the required capabilities enabled.

Walkthrough

Detect the on-hold transaction

When a crypto deposit is placed on hold due to a Travel Rule requirement, Uphold sends a core.transaction.status-changed webhook with status: on-hold and statusDetails.reason: pending-requests-for-information.

{
  "id": "<eventId>",
  "type": "core.transaction.status-changed",
  "createdAt": "2024-07-24T15:22:39Z",
  "data": {
    "transaction": {
      "id": "b97c7f64-1c34-4b6e-a8f2-3d5c4e9a1b72",
      "status": "on-hold",
      "statusDetails": {
        "reason": "pending-requests-for-information"
      }
    }
  }
}

Abbreviated — the transaction object includes additional fields.

If you are using polling instead of webhooks, check for status: on-hold and statusDetails.reason: pending-requests-for-information on the transaction object.

Notify the user

Surface the on-hold status to the user out-of-band (email or push notification) — deposits can sit on-hold indefinitely until resolved.

List transaction RFIs

Call List request for information with reference set to the transaction ID, then filter the results to keep only entries where type is “travel-rule”. From that filtered set, check whether any RFI has a status of “pending” — if so, the transaction is still awaiting resolution.

GET /core/requests-for-information?reference={transactionId}

{
  "requestsForInformation": [
    {
      "id": "3f6d0c1e-a1bf-4b25-9802-2a3ee492d3c8",
      "type": "travel-rule",
      "status": "pending",
      "expiresAt": "2024-07-24T15:22:39Z",
      "context": {
        "network": "bitcoin",
        "addresses": [
          "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
        ]
      },
      "proofOptions": {
        "selfDeclaration": {
          "schema": { "properties": { "...": "..." } }
        },
        "messageSigning": {
          "schema": { "properties": { "...": "..." } },
          "message": "I certify that the blockchain address tb1q5smjnk8zms7sqygscqlwgzuga9gz3ycclunpy9 belongs to e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a on 2024-07-24T15:00:00.000Z"
        },
        "satoshiTest": {
          "address": "r3K7jMADbWWvPe6NVyMcTkg8ytHUESafuQ",
          "asset": "XRP",
          "amount": "1.6160",
          "amountSubunits": "1616000",
          "decimals": 6,
          "reference": "953588349"
        }
      }
    }
  ]
}

If all travel-rule RFIs have a status of “ok”, the transaction may have already been moved out of on-hold status automatically. Make sure to re-fetch the transaction and check its current status before taking further action.

Resolve the Travel Rule RFI

The RFI’s proofOptions field lists which proof mechanisms can resolve it — only the mechanisms that actually apply to this deposit are present (a satoshiTest option only appears for networks where a microtransfer is a viable proof). See Proof types for what each mechanism means and when it’s used. For a type: "travel-rule" RFI on a deposit, proof is submitted as originatorProof — you’re proving who the external sender is. Submit it with Update request for information.

Self-declaration

Submit the attestation plus the compliance details described by proofOptions.selfDeclaration.schema:

PUT /core/requests-for-information/3f6d0c1e-a1bf-4b25-9802-2a3ee492d3c8
{
  "proof": {
    "originatorProof": {
      "type": "self-declaration",
      "attestation": "I hereby declare that the blockchain address bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh is under my own control and ownership."
    },
    "originator": {
      "originatorPersons": [
        { "naturalPerson": { "name": { "nameIdentifier": [{ "primaryIdentifier": "Doe", "secondaryIdentifier": "John", "nameIdentifierType": "LEGL" }] } } }
      ]
    },
    "transactionAsset": "BTC",
    "transactionAmount": "121023",
    "originatorEqualsBeneficiary": true
  }
}

{
  "requestForInformation": {
    "id": "3f6d0c1e-a1bf-4b25-9802-2a3ee492d3c8",
    "type": "travel-rule",
    "status": "ok",
    "proof": {
      "originatorProof": {
        "type": "self-declaration",
        "attestation": "I hereby declare that the blockchain address bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh is under my own control and ownership."
      },
      "originator": {
        "originatorPersons": [{ "naturalPerson": { "name": { "...": "..." } } }]
      },
      "isNonCustodial": true,
      "transactionAsset": "BTC",
      "transactionAmount": "121023",
      "originatorEqualsBeneficiary": true
    }
  }
}

Message signing

Have the user sign proofOptions.messageSigning.message with their wallet, then submit the signature:

PUT /core/requests-for-information/3f6d0c1e-a1bf-4b25-9802-2a3ee492d3c8
{
  "proof": {
    "originatorProof": {
      "type": "message-signing",
      "scheme": "bip-322",
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "attestation": "I certify that the blockchain address bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh belongs to me.",
      "proof": "H0pu/6Zpqv/5TgPn9ZbT0pFWiLVVlToPmoRh2F5rncg..."
    }
  }
}

Uphold verifies the signature and enriches the response with did and status:

{
  "requestForInformation": {
    "id": "3f6d0c1e-a1bf-4b25-9802-2a3ee492d3c8",
    "type": "travel-rule",
    "status": "ok",
    "proof": {
      "originatorProof": {
        "type": "message-signing",
        "scheme": "bip-322",
        "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
        "attestation": "I certify that the blockchain address bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh belongs to me.",
        "proof": "H0pu/6Zpqv/5TgPn9ZbT0pFWiLVVlToPmoRh2F5rncg...",
        "did": "did:pkh:bip122:000000000019d6689c085ae165831e93:bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
        "status": "verified"
      },
      "transactionAsset": { "caip19": "bip122:000000000019d6689c085ae165831e93/slip44:0" },
      "transactionAmount": "121023",
      "originatorEqualsBeneficiary": true
    }
  }
}

Satoshi test

Nothing is submitted through this endpoint — resolution is deferred until Uphold detects and confirms the on-chain microtransfer to the address described in proofOptions.satoshiTest. Poll Get request for information or re-fetch the transaction to know when it clears. Once confirmed, the RFI resolves with a flat proof — unlike the other two types, it’s not wrapped in originatorProof:

{
  "requestForInformation": {
    "id": "3f6d0c1e-a1bf-4b25-9802-2a3ee492d3c8",
    "type": "travel-rule",
    "status": "ok",
    "proof": {
      "type": "satoshi-test",
      "proof": "57CDD07727281AFE1669508D15A4FBE14B65CD78D1B6FF49788CC964DA307CE2"
    }
  }
}

Monitoring for settlement

After the RFI is resolved, the transaction will move from on-hold to processing and then to either completed or failed. Monitor the transaction status using webhooks (recommended) or polling (fallback):

Webhook events (recommended):
- core.transaction.status-changed
  - status: processing → transaction is being processed
  - status: completed → necessary confirmations reached
  - status: failed → transaction failed
Polling (fallback): Get transaction

When the transaction reaches completed or failed, notify the user of the outcome.

Testing

To trigger a Travel Rule RFI on a deposit, use a GB user account and send 30 XRP from an unhosted (self-custodial) wallet to the user’s Uphold deposit address. Verify the following:

A core.transaction.status-changed webhook is received with status: on-hold and statusDetails.reason: pending-requests-for-information.
List requests for information returns an RFI with type: travel-rule, status: pending, and a populated proofOptions.
Update request for information with a valid proof returns 200 with status: "ok".
The transaction status updates from processing to completed within a few minutes, assuming no other blockers.

For the equivalent withdrawal guide, see Travel Rule withdrawal via the REST API.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Travel Rule deposit via the REST API

Prerequisites

Walkthrough

Detect the on-hold transaction

Notify the user

List transaction RFIs

Resolve the Travel Rule RFI

Self-declaration

Message signing

Satoshi test

Monitoring for settlement

Testing

​Prerequisites

​Walkthrough

​Detect the on-hold transaction

​Notify the user

​List transaction RFIs

​Resolve the Travel Rule RFI

​Self-declaration

​Message signing

​Satoshi test

​Monitoring for settlement

​Testing

Prerequisites

Walkthrough

Detect the on-hold transaction

Notify the user

List transaction RFIs

Resolve the Travel Rule RFI

Self-declaration

Message signing

Satoshi test

Monitoring for settlement

Testing