Skip to content
Last updated

Integration Guide

This guide explains how to integrate your VASP backend with the TRP Public API end-to-end. You will:

  • Authenticate with TRP and obtain a JWT access token
  • Generate a Travel Address for the beneficiary
  • Initiate a Travel Rule transfer
  • Handle callback notifications from TRP
  • Submit the on-chain transaction ID

Base URL

https://api.trp.example.com/v1

1. Authentication

All protected endpoints require a Bearer JWT token. You obtain it using your API key.

1.1 Generate JWT access token

Endpoint

POST /auth/token

Headers

Authorization: ApiKey <YOUR_API_KEY>
Content-Type: application/json

Response 200

{
  "accessToken": "eyJhbGciOiJFZERTQSJ9....",
  "expiresIn": 3600,
  "expiresAt": "2025-11-21T17:04:59.000Z",
  "tokenType": "Bearer"
}

Use for all authenticated requests.:

Authorization: Bearer <accessToken>

2. Generate Travel Address

Before initiating a transfer, generate a Travel Address for the beneficiary. Endpoint

POST /travel-address/generate

Required fields

  • firstName
  • lastName
  • walletAddress

Optional

  • externalId

2.1 Request example

{
  "firstName": "John",
  "lastName": "Snow",
  "walletAddress": "1q2w3e4r5t6y7u8i9o0p",
  "externalId": "user-123456"
}

2.2 Response example

{
  "travelAddress": "ta4n7WArAHPkQgg3fABMpJiys8AsypD8AqdoXfKBwjH9t5QQbG2uqW9CmQCS3M4GuwxcS6QNdWFUX6nD3tc5bajpNb3svbn87xxy9rCcYNYHN"
}

3. Initiate Travel Rule transfer

This operation sends IVMS101-compliant sender/receiver information and transfer details. Endpoint

POST /transfers/initiate

Required top-level fields

  • travelAddress
  • asset
  • amount
  • callback

Required inside originator & beneficiary (IVMSPerson)

  • firstName
  • lastName
  • walletAddress

3.1 Request example

{
  "travelAddress": "taAhdwou1adq9p68hCQN5Ud7b1amDNztt...",
  "asset": "USDT",
  "amount": "1000.50",
  "callback": "https://originator-vasp.example.com/api/callback",
  "originator": {
    "personType": "natural",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-01-15",
    "addressType": "HOME",
    "streetName": "Main Street",
    "buildingNumber": "123",
    "postCode": "10001",
    "townName": "New York",
    "country": "US",
    "nationalId": "123456789",
    "nationalIdType": "ARNU",
    "accountNumber": "ACC123456",
    "walletAddress": "0xORIGINATOR"
  },
  "beneficiary": {
    "personType": "natural",
    "firstName": "Jane",
    "lastName": "Smith",
    "dateOfBirth": "1985-05-20",
    "addressType": "HOME",
    "streetName": "Oak Avenue",
    "buildingNumber": "456",
    "postCode": "90210",
    "townName": "Los Angeles",
    "country": "US",
    "accountNumber": "ACC789012",
    "walletAddress": "0xBENEFICIARY"
  }
}

3.2 Response example

{
  "transferId": "trf_123456789",
  "status": "PENDING"
}

4. Callback to originator VASP server

TRP sends asynchronous updates about the transfer.

Your backend must accept:

POST <callback URL>

Payload schema: TransferStatusCallback

4.1 Approved example

{
  "status": "APPROVED",
  "callback": "http://localhost:3000/transfers/txId?q=019ac59a-9130-7874-9cc1-813524c9bf92",
  "transferId": "019ac59a-9130-7874-9cc1-813524c9bf92",
  "statusComment": null
}

4.2 Rejected example

{
  "status": "REJECTED",
  "callback": "http://localhost:3000/transfers/txId?q=019ac59a-9130-7874-9cc1-813524c9bf92",
  "transferId": "019ac59a-9130-7874-9cc1-813524c9bf92",
  "statusComment": "Error message"
}

4.3 What your server must do

  • Validate the callback
  • Update internal transfer status
  • Store transferId
  • Return 200 OK

5. Submit transaction ID

After broadcasting the blockchain transaction, send the on-chain hash to TRP. Endpoint

POST /transfers/txId?q=<transferId>

Request body

{
  "txId": "qwer5t6yuiuyt6r54ew3sedrfvgbhgftrdxcvgfrdcfvgfc999"
}

Response

{
  "status": "OK"
}

6. Summary

6.1 Generate Travel Address — required

  • firstName
  • lastName
  • walletAddress
  • externalId (optional)

6.2 Initiate Transfer — required

Top-level:

  • travelAddress
  • asset
  • amount
  • callback Inside originator / beneficiary:
  • firstName
  • lastName
  • walletAddress
Previous page
Next page