API ReferenceWebsite

Create Transfer

POST /api/v2/travelrule/transfers

This API endpoint simplifies the process of handling various types of travel rule transfers, including:

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 🚀

Transfer Scenarios

When initiating a Travel Rule transfer, the roles of originator and beneficiary are defined to meet regulatory requirements. These roles ensure all required data is properly collected, grouped, and transmitted in accordance with compliance standards.

In Ospree, either role can be associated with:

  • Customer: An individual or entity that has been onboarded by the VASP.

  • Non-Customer: An external party who is not onboarded but is involved in the transaction.

This flexible structure allows the platform to support a wide range of transfer scenarios, all from a single API endpoint:

  1. VASP-to-VASP Withdrawal / Customer → Non-Customer (Different VASP)

    A customer sends crypto funds to an non-customer beneficiary account hosted at another VASP.

  2. VASP-to-VASP Withdrawal / Customer → Customer (Different VASP)

    A customer sends crypto funds to their own account held at a different VASP.

  3. VASP-to-VASP Transfer / Customer → Customer (Same VASP)

    A customer transfers crypto between accounts within the same VASP.

  4. Self-Hosted Wallet Withdrawal / Customer → Customer

    A customer withdraws crypto funds to a self-hosted wallet they personally or institutionally control.

  5. Self-Hosted Wallet Deposit / Customer ← Customer

    A customer deposits crypto from their self-hosted wallet back into their VASP account.

Request Body

Name
Type
Description
Required

amount

number

The amount of the digital token being transferred.

True

dti

string

The Digital Token Identifier (DTI) based on ISO 24165.

Required if chain and symbol are not defined in the request body.

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

False

chain

string

The chain name of the digital token.

Required with symbol if dti is not defined in the request body.

Refer to Token Identifier for the complete list of supported chains.

Example: bitcoin

False

symbol

string

The symbol or ticker of the digital token.

Required with chain if dti is not defined in the request body.

Refer to Token Identifier for the complete list of supported tokens.

Example: BTC

False

protocol

string

Travel Rule protocol to be used for communication. Examples: trp, gtr, flow, trisa

True

beneficiary_vasp_id

string

6 character ID of the receiving Virtual Asset Service Provider (VASP). Example: ABCXYZ

True

originator_address

string

Blockchain address of the sender. If linked, the associated account is used; otherwise, link it via the Create Address endpoint or provide originator_account_reference_id.

Example: 12higDjoCCNXSA95xZMWUdPvXNmkAduhWv

True

originator_address_is_self_hosted

boolean

Specify if provided originator_address is "self-hosted". Defaults to false.

False

beneficiary_address

string

Blockchain address of the recipient. If linked, the associated account is used; otherwise, link it via the Create Address endpoint or provide beneficiary_account_reference_id. Example: bc1qas2rvpejpvncd6z5hcscvw52n4wxw5th2de67v

True

beneficiary_address_is_self_hosted

boolean

Specify if provided beneficiary_address is "self-hosted". Defaults to false.

False

routing_number

string

Optional memo/destination tag for the beneficiary.

False

originator_account_reference_id

string

Reference ID of the sender´s account within the originator VASP.

Example: account1234

True

beneficiary_account_reference_id

string

Reference ID of the recipient´s account within the originator VASP.

Example: account1234

True

transaction_hash

string

Blockchain transaction hash, if already available. This can be updated later via the update transfer endpoint. Example: 80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893

False

reference_id

string

Unique identifier for the transfer, generated by the sender. Example: transfer20250312040414

False

originator_account

object

Account details of the originator. If originator_account_reference_id does not exist, a new originator account will be created with data from originator_account object.

If originator_account_reference_id already exists, the originator account will be updated with data from originator_account object. Refer to the Create Account section for the expected schema. NOTE: reference_id is not required, since originator_account_reference_id is already provided.

False

beneficiary_account

object

Account details of the beneficiary.

If beneficiary_account_reference_id does not exist, a new beneficiary account will be created with data from originator_account object.

If beneficiary_account_reference_id already exists, the originator account will be updated with data from beneficiary_account object. Refer to the Create Account section for the expected schema. NOTE: reference_id is not required, since beneficiary_account_reference_id is already provided.

False

Sample Requests

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,
    "beneficiary_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "beneficiary_address_is_self_hosted": true,
    "routing_number": "1234XYZ",
    "originator_account_reference_id": "random-ref-id-101",
    "beneficiary_account_reference_id": "random-ref-id-102",
    "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."
            }
        }
    }
}'

Response

{
    "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",
        "routing_number": "1234XYZ",
        "originator_account_reference_id": "random-ref-id-101",
        "beneficiary_account_reference_id": "random-ref-id-102",
        "transaction_hash": "80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893",
        "transfer_status": "REVIEW"
    }
}

Last updated