Create Transfer

POST /api/v2/travelrule/transfers

This API endpoint is used to initiate different types of Travel Rule transfers. Including:

VASP-to-VASP Withdrawal: Transfer between two registered crypto service providers.
Self-Hosted Wallet Withdrawal: Send crypto to a user’s self-hosted wallet.
Self-Hosted Wallet Deposit: Receive crypto from a user’s self-hosted wallet.

It combines several steps into one call—saving time and reducing the effort needed to build your integration. Here’s what happens in the background:

Create the customer account (if it doesn’t exist already)
Create the beneficiary account (if it doesn’t exist already)
Add or update and verify the sending wallet address
Add or update the recipient wallet address
Start the transfer 🚀

Request Body

Name

Type

Description

Required

amount

number

The amount of the digital token being transferred.

True

amount_usd

number

The USD amount equivalent of the token being transferred.

False

dti

string

Unique identifier for the assets based on DTIF standards.

Example: 4H95J0R2X(see https://dtif.org)

Conditional

chain

string

Blockchain network name.

Example: bitcoin

Conditional

symbol

string

Symbol used to represent this digital token

Conditional

protocol

string

Specifies the Travel Rule communication protocol used

True

reference_id

string

Unique identifier for the transfer, generated by the sender.

Example: transfer20250312040414

False

beneficiary_vasp_id

string

ID of the receiving Virtual Asset Service Provider (VASP). Specifying the beneficiary_vasp_id is not required for self-hosted transfers. Example: ABCXYZ

Conditional

originator_address

string

Blockchain address of the sender.

Example: 12higDjoCCNXSA95xZMWUdPvXNmkAduhWv

True

originator_address_is_self_hosted

boolean

Indicates if the wallet address is self-hosted. Defaults to false

False

beneficiary_address

string

Blockchain address of the recipient.

Example: bc1qas2rvpejpvncd6z5hcscvw52n4wxw5th2de67v

True

beneficiary_address_is_self_hosted

boolean

Indicates if the wallet address is self-hosted. Defaults to false

False

routing_number

string

A numeric or alphanumeric code.

False

transaction_hash

string

The unique hash of the crypto transaction.

False

originator_account_reference_id

string

Sender's account ID within the originator VASP.

originator_account is required if the account does not exist yet.

Example: account5678

True

beneficiary_account_reference_id

string

Recipient's account ID within the originator VASP.

beneficiary_account is required if the account does not exist yet.

Example: account1234

True

originator_account

object

The originator account details, required if the originator_account_reference_id does not exist yet. Refer to Create Accountfor the list of available account fields.

Conditional

beneficiary_account

object

The beneficiary account details, required if the beneficiary_account_reference_id does not exist yet. Refer to Create Accountfor the list of available account fields.

Conditional

VASP-to-VASP Withdrawal Query

Customer (Individual) → Non-Customer (Individual). A customer initiates a crypto transfer to a non-customer beneficiary whose account is hosted at another VASP. The originator is an individual, and the beneficiary is also an individual.

// Includes both originator and beneficiary individual account

curl -X POST https://sandbox.ospree.io/api/v2/travelrule/transfers

-h 'Content-Type: application/json' \
-h 'Accept: application/json' \
-h 'Authorization: ••••••' \
-d '{
    "amount": 4.2,
    "dti": "4H95J0R2X",
    "protocol": "flow",
    "reference_id": "reference-transfer-01",
    "beneficiary_vasp_id": "MLESJF",
    "originator_address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
    "originator_address_is_self_hosted": false,
    "originator_account_reference_id": "random-ref-id-101",
    "beneficiary_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "beneficiary_address_is_self_hosted": false,
    "beneficiary_account_reference_id": "random-ref-id-102",
    "routing_number": "1234XYZ",    
    "transaction_hash":"80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893",
    
    "originator_account": {
        "account_type": "individual",
        "account_category": "customer",
        "customer_id": "random-cust-id-101",
        "individual": {
            "individual_name": {
                "name_type": "LEGL",
                "name_first": "Mark",
                "name_last": "Rover"
            }
        }
    },
    
    "beneficiary_account": {
        "account_type": "individual",
        "account_category": "non-customer",
        "customer_id": "random-cust-id-102",
        "individual": {
            "individual_name": {
                "name_type": "LEGL",
                "name_first": "Robert",
                "name_last": "Harding"
            }
        }
    }
}'

VASP-to-VASP Withdrawal Query

Customer (Entity) → Non-Customer (Entity). A customer initiates a crypto transfer to a non-customer beneficiary whose account is hosted at another VASP. Both the originator and beneficiary accounts are entities.

// Includes both originator and beneficiary entity account details

curl -X POST https://sandbox.ospree.io/api/v2/travelrule/transfers

-h 'Content-Type: application/json' \
-h 'Accept: application/json' \
-h 'Authorization: ••••••' \
-d '{
    "amount": 4.2,
    "dti": "4H95J0R2X",
    "protocol": "flow",
    "reference_id": "reference-transfer-01",
    "beneficiary_vasp_id": "MLESJF",
    "originator_address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
    "originator_address_is_self_hosted": false,
    "originator_account_reference_id": "random-ref-id-101",
    "beneficiary_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "beneficiary_address_is_self_hosted": false,
    "beneficiary_account_reference_id": "random-ref-id-102",
    "routing_number": "1234XYZ",
    "transaction_hash":"80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893",
    
    "originator_account": {
        "account_type": "entity", 
        "account_category": "customer",
        "customer_id": "random-cust-id-101",
        "entity": {
            "entity_name": {
                "name_type": "LEGL",
                "name_legal": "Digital Capital",
                "name_business": "Digital Capital Pte. Ltd."
            }
        }
    },
       
    "beneficiary_account": {
        "account_type": "entity", 
        "account_category": "non-customer",
        "customer_id": "random-cust-id-102",
        "entity": {
            "entity_name": {
                "name_type": "LEGL",
                "name_legal": "Cyrpto Funds",
                "name_business": "Cyrpto Funds Inc."
            }
        }
    }
}'

VASP-to-VASP Withdrawal Query

Customer (Individual) → Customer (Entity). A customer initiates a crypto transfer to another customer whose account is hosted at a different VASP. The originator is an individual, and the beneficiary is an entity.

// Includes a originator individual and beneficiary entity account details

curl -X POST https://sandbox.ospree.io/api/v2/travelrule/transfers

-h 'Content-Type: application/json' \
-h 'Accept: application/json' \
-h 'Authorization: ••••••' \
-d '{
    "amount": 4.2,
    "dti": "4H95J0R2X",
    "protocol": "flow",
    "reference_id": "reference-transfer-01",
    "beneficiary_vasp_id": "MLESJF",
    "originator_address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
    "originator_address_is_self_hosted": false,
    "originator_account_reference_id": "random-cust-id-101",
    "beneficiary_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "beneficiary_address_is_self_hosted": false,
    "beneficiary_account_reference_id": "random-ref-id-102",
    "routing_number": "1234XYZ",
    "transaction_hash":"80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893",
    
    "originator_account": {
       "account_type": "individual",
        "account_category": "customer",
        "customer_id": "random-cust-id-101",
        "individual": {
            "individual_name": {
                "name_type": "LEGL",
                "name_first": "Mark",
                "name_last": "Rover"
            }
        }
    },
       
    "beneficiary_account": {
        "account_type": "entity", 
        "account_category": "non-customer",
        "customer_id": "random-cust-id-102",
        "entity": {
            "entity_name": {
                "name_type": "LEGL",
                "name_legal": "Cyrpto Funds",
                "name_business": "Cyrpto Funds Inc."
            }
        }
    }
}'

Self-Hosted Wallet Withdrawal (DTI)

Customer → Customer. A customer withdraws crypto funds to their own self-hosted wallet. The transfer uses originator_account_reference_id, beneficiary_account_reference_id, and dti.

// Without Account account details and DTI

curl -X POST https://sandbox.ospree.io/api/v2/travelrule/transfers

-h 'Content-Type: application/json' \
-h 'Accept: application/json' \
-h 'Authorization: ••••••' \
-d '{
    "amount": 4.2,
    "dti": "4H95J0R2X",
    "protocol": "flow",
    "reference_id": "reference-transfer-01",
    "originator_address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
    "originator_address_is_self_hosted": false,
    "originator_account_reference_id": "random-ref-id-101",
    "beneficiary_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "beneficiary_address_is_self_hosted": true,
    "beneficiary_account_reference_id": "random-ref-id-102",
    "routing_number": "1234XYZ",
    "transaction_hash":"80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893"
}'

Self-Hosted Wallet Withdrawal (Chain + Symbol)

Customer → Customer. A customer withdraws crypto funds to their own self-hosted wallet. The transfer includes originator_account_reference_id, beneficiary_account_reference_id, chain, and symbol.

// Without Account (Chain + Symbol)

curl -X POST https://sandbox.ospree.io/api/v2/travelrule/transfers

-h 'Content-Type: application/json' \
-h 'Accept: application/json' \
-h 'Authorization: ••••••' \
-d '{
    "amount": 4.2,
    "chain": "bitcoin",
    "symbol": "BTC",
    "protocol": "flow",
    "reference_id": "reference-transfer-01",
    "originator_address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
    "originator_address_is_self_hosted": false,
    "originator_account_reference_id": "random-ref-id-101",
    "beneficiary_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "beneficiary_address_is_self_hosted": true,
    "beneficiary_account_reference_id": "random-ref-id-102",
    "routing_number": "1234XYZ",
    "transaction_hash":"80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893"
}'

Self-Hosted Wallet Deposit (DTI)

Customer → Customer. A customer withdraws crypto funds to their own self-hosted wallet. The transfer uses originator_account_reference_id, beneficiary_account_reference_id, and dti.

// Without Account account details and DTI

curl -X POST https://sandbox.ospree.io/api/v2/travelrule/transfers

-h 'Content-Type: application/json' \
-h 'Accept: application/json' \
-h 'Authorization: ••••••' \
-d '{
    "amount": 4.2,
    "dti": "4H95J0R2X",
    "protocol": "flow",
    "reference_id": "reference-transfer-01",
    "originator_address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
    "originator_address_is_self_hosted": true,
    "originator_account_reference_id": "random-ref-id-101",
    "beneficiary_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "beneficiary_address_is_self_hosted": false,
    "beneficiary_account_reference_id": "random-ref-id-102",
    "routing_number": "1234XYZ",
    "transaction_hash":"80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893"
}'

Self-Hosted Wallet Deposit (Chain + Symbol)

// Without Account (Chain + Symbol)

curl -X POST https://sandbox.ospree.io/api/v2/travelrule/transfers

-h 'Content-Type: application/json' \
-h 'Accept: application/json' \
-h 'Authorization: ••••••' \
-d '{
    "amount": 4.2,
    "chain": "bitcoin",
    "symbol": "BTC",
    "protocol": "flow",
    "reference_id": "reference-transfer-01",
    "originator_address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
    "originator_address_is_self_hosted": true,
    "originator_account_reference_id": "random-ref-id-101",
    "beneficiary_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "beneficiary_address_is_self_hosted": false,
    "beneficiary_account_reference_id": "random-ref-id-102",
    "routing_number": "1234XYZ",    
    "transaction_hash":"80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893"
}'

Response

Here’s an example of the response data structure:

{
    "status": "success",
    "data": {
        "transfer_id": "067fd57d-efe3-7eab-8000-04d8f072e418",
        "reference_id": "reference-transfer-01",
        "amount": 4.2,
        "amount_usd": 356406.54,
        "dti": "4H95J0R2X",
        "chain": "bitcoin",
        "symbol": "BTC",
        "protocol": "flow",
        "beneficiary_vasp_id": "MLESJF",
        "originator_address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
        "beneficiary_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
        "originator_account_reference_id": "random-ref-id-101",
        "beneficiary_account_reference_id": "random-ref-id-102",
        "routing_number": "1234XYZ",
        "transaction_hash": "80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893",
        "transfer_status": "REVIEW"
    }
}

Last updated 3 days ago