API integration flows

This section provides guidance on VASP-to-VASP and self-hosted wallet integration flows. Please note that these are example flows provided for reference—you may adapt them as needed to align with your specific business processes and regulatory requirements.

VASP-to-VASP Withdrawal (with intermediary)
VASP-to-VASP Withdrawal (with intermediary and pre-populate customers information)

VASP-to-VASP Withdrawal

This flow outlines the process for initiating a Travel Rule crypto asset transfer from Virtual Asset Service Provider (VASP) A to VASP B. It includes the key steps required to collect and transmit originator and beneficiary information in line with applicable regulatory expectations.

Step 1: The user initiates a withdrawal request .
Step 2: In accordance with the Travel Rule, VASP A must share its customer information with VASP B—similar to the information-sharing process used in traditional banking. This includes details about both the originator and the beneficiary. To fulfill this requirement, VASP A uses the Create Transfer endpoint to initiate a Travel Rule transfer. VASP A has two options when populating the transfer request:
- Include full details of the originator and beneficiary directly within the Create Transfer request body, or
- Reference previously created records using the following parameters (See Steps 3 to 4):
  - originator_account_reference_id
  - beneficiary_account_reference_id

Steps 3 to 4 – How to Create Accounts

Step 3: Create Originator Account — Use the /api/v2/directory/accounts endpoint to create a customer account representing the originator (sender). Include the required Travel Rule information such as name, wallet address, and residential or business address. Use the reference_id returned from this request as the originator_account_reference_id in the Create Transfer query.

Step 4: Create a Beneficiary Account — Repeat the account creation process using the /api/v2/directory/accounts endpoint to create an account for the beneficiary (receiver). At a minimum, provide the beneficiary’s name and wallet address. Use the reference_id from this request as the beneficiary_account_reference_id in the Create Transfer query.

Step 5: VASP A initiates the Travel Rule transfer via Ospree platform.
Step 6: Beneficiary VASP B validates the transfer details.
Step 7: Beneficiary VASP B responds to the transfer inquiry with either an approval or rejection.
Step 8: Ospree notifies VASP A of VASP B’s decision via a webhook.
Step 9: If the transfer is approved by Beneficiary VASP B, Originating VASP A executes the crypto asset transaction to the beneficiary address.
Step 10: Originating VASP A updates the transfer record with the transaction hash.

VASP-to-VASP Deposit

This flow outlines the steps involved when a VASP receives a crypto asset transfer initiated by another VASP. It includes how incoming transactions are detected, evaluated against compliance thresholds, and verified in accordance with Travel Rule requirements.

Step 1: VASP B initiates a Travel Rule transfer request to VASP A.
Step 2: When an incoming transfer is detected, Ospree’s webhook sends a notification to VASP A.
Step 3: VASP A inspects the transfer details and compares the transaction amount against a pre-set threshold rule based on local regulations.
- (1) If the transaction exceeds the threshold: Verify whether Travel Rule data from the counterparty entity is included before processing the transfer.
  - If Travel Rule data is missing or does not match VASP A’s records, flag or block the incoming deposit.
  - If Travel Rule data is complete, proceed to the next standard compliance verification step, as defined in internal policies.
- (2) If the transaction is within the allowed limit: The transfer proceeds without additional Travel Rule-related checks and moves to the next standard compliance verification step, as defined in internal policies.
Step 4: VASP A approves or reject the transfer.
Step 5: Ospree notifies VASP B of VASP A’s decision.
Step 6: If the transfer is approved by VASP A (the beneficiary), VASP B (the originator) executes the crypto asset transaction to the beneficiary address.

Self-Hosted Wallet Withdrawal

This flow outlines the process for managing crypto asset withdrawals to self-hosted wallets owned by VASP A’s customers. It includes steps for collecting user attestations and gathering relevant information to support internal compliance processes, including Travel Rule data collection when applicable.

Step 1: The user initiates a withdrawal request and enters a wallet address, indicating that it is self-hosted.
Step 2: If the wallet address has not been previously verified, VASP A requests a Verify Address Ownership link from Ospree.
Step 3: Ospree returns a secure, shareable link for the user to verify ownership of the specified address.
Step 4: VASP A sends the verification link to the user and requests an ownership attestation.
Step 5: The user signs the attestation to prove ownership.
Step 6: Once verified, the wallet address is labeled as self-hosted in the Ospree system, and a webhook notification is triggered to confirm successful address verification.
Step 7: VASP A sends the crypto funds to the self-hosted address.

VASP to Self-hosted

// Sample request

{
  "amount": 4.5, // Amount in the native asset (e.g., BTC)
  "dti": "4H95J0R2X", // DTI code representing Bitcoin
  "protocol": "flow", // Travel rule protocol used for the message transmission
  "reference_id": "transfer-0232434", // Unique reference ID for this transfer
  "originator_address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6", // Wallet hosted by Originator VASP A
  "originator_address_is_self_hosted": false, // Indicates the sender wallet is hosted by the VASP
  "beneficiary_address": "bc1qa5wkgaew2dkv56kfvj49j0av5nml45x9ek9hz6", // Recipient wallet, self-hosted by the customer
  "beneficiary_address_is_self_hosted": true, // Indicates the beneficiary address is self-hosted
  "originator_account_reference_id": "random-ref-id-108", // Reference ID of the customer account (sender)
  "beneficiary_account_reference_id": "random-ref-id-108" // Same customer account acting as recipient
}

Step 8: VASP A uses the Create Transfer endpoint to create a Travel Rule transfer record for compliance and audit purposes.

Self-Hosted Wallet Deposit

This flow outlines the process for handling incoming crypto asset deposits from a customer’s self-hosted wallet. It includes steps for collecting user attestations, verifying whether the wallet has already been labeled as self-hosted, and gathering the necessary data to support the creation of a Travel Rule transfer record, when applicable.

Step 1: The user declares a self-hosted wallet address from which they intend to send funds to VASP A.
Step 2: VASP A requests a Verify Address Ownership link from Ospree.
Step 3: Ospree returns a secure, shareable link for the user to verify ownership of the specified address.
Step 4: VASP A sends the link to the user and requests an ownership attestation.
Step 5: The user signs the attestation to verify ownership.
Step 6: Once verified, the wallet address is labeled as self-hosted in the Ospree system, and a webhook notification is triggered to confirm successful address verification.
Step 7: The user sends crypto funds from the verified self-hosted address to VASP A.

Self-hosted to VASP

// Sample request

{
  "amount": 4.5, // Amount in the native asset (e.g., BTC)
  "dti": "4H95J0R2X", // DTI code representing Bitcoin
  "protocol": "flow", // Travel rule protocol used for the message transmission
  "reference_id": "transfer-0232434", // Unique reference ID for this transfer
  "originator_address": "bc1qa5wkgaew2dkv56kfvj49j0av5nml45x9ek9hz6",  // Originator wallet, self-hosted by the customer
  "originator_address_is_self_hosted": true, // Indicates the originator address is self-hosted
  "beneficiary_address": "3M219KR5vEneNb47ewrPfWyb5jQ2DjxRP6", // Wallet hosted by Originator VASP A
  "beneficiary_address_is_self_hosted": false, // Indicates the beneficiary wallet is hosted by the VASP A
  "originator_account_reference_id": "random-ref-id-108", // Reference ID of the customer account (sender)
  "beneficiary_account_reference_id": "random-ref-id-108" // Same customer account acting as recipient
}

Step 8: VASP A recognizes the pre-verified address and uses the Create Transfer endpoint to create a Travel Rule transfer record for compliance and audit purposes.

VASP-to-VASP Withdrawal (# with intermediary)

This section outlines the flow and requirements for executing a VASP-to-VASP withdrawal that involves an intermediary party. This scenario typically occurs when a transaction passes through a third-party platform or custody service before reaching the final beneficiary VASP. Understanding this flow is essential for maintaining Travel Rule compliance, ensuring accurate data transmission, and minimizing delays in cross-jurisdictional transfers.

Note: In this flow, the intermediary refers to an infrastructure or service provider that a VASP relies on to host or facilitate the transfer of crypto assets on its behalf. This can include custody solutions, payment companies, OTC desks, asset managers, and other similar entities.

Step 1: The user initiates a withdrawal request
Step 2: The VASP A initiates a withdrawal request
Step 3: The Service Provider starts a Travel Rule using Create Transfer
Step 4: Create an account for the originator if it does not already exist.
Step 5: Create an account for the beneficiary if it does not already exist.
Step 6: Service Provider initiates the Travel Rule transfer via the Ospree platform.
Step 7: Beneficiary VASP B validates the Travel Rule transfer details.
Step 8: Beneficiary VASP B responds to the transfer inquiry with either an approval or rejection.
Step 9: Ospree notifies Service Provider of VASP B’s decision via a webhook.
Step 10: If the transfer is approved by Beneficiary VASP B, Originating Service Provider executes the crypto asset transaction to the beneficiary address.
Step 11: Originating Services Provider updates the transfer record with the transaction hash.

VASP-to-VASP Withdrawal (# with intermediary and pre-populate customers information)

This section describes how to execute a VASP-to-VASP withdrawal that involves an intermediary and utilizes pre-populated customer account information. By leveraging the originator_account_reference_id and beneficiary_account_reference_id, you can streamline the transfer process while maintaining compliance. These reference IDs serve as persistent identifiers that link users to previously created accounts, allowing the system to automatically associate future transfers with the correct parties, without resubmitting full personal details each time. This approach reduces redundancy, improves efficiency, and ensures consistency across Travel Rule transactions.

Step 1: VASP A pre-populates customer and beneficiary information using Originator Account and Beneficiary Account.
Step 2: Ospree creates an account for the originator if it does not already exist.
Step 3: Ospree creates an account for the beneficiary if it does not already exist.

Create a Originator Account— Use the /api/v2/directory/accounts endpoint to create a customer account representing the originator (sender). Include the required Travel Rule information such as name, wallet address, and residential or business address. Use the reference_id returned from this request as the originator_account_reference_id in the Create Transfer query.

Create a Beneficiary Account— Repeat the account creation process using the /api/v2/directory/accounts endpoint to create an account for the beneficiary (receiver). At a minimum, provide the beneficiary’s name and wallet address. Use the reference_id from this request as the beneficiary_account_reference_id in the Create Transfer query.

Step 4: The user initiates a withdrawal request.
Step 5: VASP A initiates a withdrawal request.
Step 6: The Service Provider starts a Travel Rule using Create Transfer by simply passing the reference IDs.
Step 7: Service Provider initiates the Travel Rule transfer via the Ospree platform.
Step 8: Beneficiary VASP B validates the Travel Rule transfer details.
Step 9: Beneficiary VASP B responds to the transfer inquiry with either an approval or rejection.
Step 10: Ospree notifies Service Provider of VASP B’s decision via a webhook.
Step 11: If the transfer is approved by Beneficiary VASP B, Originating Service Provider executes the crypto asset transaction to the beneficiary address.
Step 12: Service Provider updates the transfer record with the transaction hash.

Last updated 1 month ago