# 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