> For the complete documentation index, see [llms.txt](https://docs.ospree.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ospree.io/quick-start/quickstart.md).
# Quickstart
Let’s walk through how to process a withdrawal transfer for a new customer. Since this is customer’s first transaction, we’ll start by creating their account in the system. Next, we’ll set up the sending wallet address and link it to their account. After that, we’ll create a Beneficiary Account and add a self-hosted wallet where the funds will be sent. Finally, we’ll initiate the withdrawal Travel Rule transfer.
This guide will break down each step clearly. Let’s dive in!
### Introduction
To use Ospree’s API, you’ll need API keys, which you’ll receive in your activation email. Ospree provides two different API keys, each corresponding to one of the two available environments:
• Sandbox environment – Used for testing and development.\
• Production environment – Used for live transactions.
For now, we’ll start in the Sandbox environment to safely test and integrate the API before moving to production.
### Step 1: Create a customer account
A customer account in Ospree represents a legal entity or individual. Each account is associated with various elements, such as wallet addresses and Travel Rule transfers.
To create a customer account, use the [/api/v2/directory/accounts](/developers/accounts-directory/create-account.md) endpoint. Setting up a customer account ensures that all necessary data for future Travel Rule transfers is complete and standardized, facilitating automation and minimizing data-related errors.
{% tabs %}
{% tab title="Sample Request" %}
### Step 2: Create & link a wallet address
Once you have created a customer account, the next step is to create a wallet address and link it to the account. A single customer account may be associated with multiple wallet addresses for different digital assets, such as BTC, XRP, and ETH.
Linking accounts with wallet addresses ensures that when a Travel Rule transfer is initiated, the system can automatically retrieve the correct account details using only the wallet address. This streamlines processing, reducing the amount of data that needs to be loaded for each transaction.
To create a wallet address, use the [/api/v2/analytics/chains/{chain}/addresses/{address}](/developers/blockchain-analytics/create-address.md) endpoint. This endpoint not only links a wallet address to a customer account but also provides additional functionalities to enhance compliance. It enables risk screening using multiple blockchain analytics providers to assess potential threats, and it allows wallets to be labeled as self-hosted, distinguishing them from VASP-managed wallets. These features ensure that wallet addresses are properly categorized, assessed for risk, and ready for use in Travel Rule transfers.
{% tabs %}
{% tab title="Sample Request" %}
```json
curl -X POST 'https://sandbox.ospree.io/api/v2/analytics/chains/bitcoin/addresses/bc1q8yj0herd4r4yxszw3nkfvt53433thk0f5qst4g' \
--header 'accept: application/json'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
--data '{
"provider_name": "",
"is_self_hosted": false,
"scan_for_risk": false,
"account_ref_id": "${ACCOUNT_ID}"
}'
```
{% endtab %}
{% tab title="200" %}
### **Step 3: Create a beneficiary**
Use Ospree to create and store beneficiary account records, allowing for easy reuse in future Travel Rule transfers. Even when a customer is transferring funds to themselves—whether to another Virtual Asset Service Provider (VASP) account or a self-hosted wallet—a beneficiary record must still be created. This ensures proper compliance, transaction tracking, and seamless Travel Rule data exchange. To create a beneficiary account, use the [/api/v2/directory/accounts](/developers/accounts-directory/create-account.md) endpoint.
{% tabs %}
{% tab title="Sample Request" %}
```json
curl -X POST 'https://sandbox.ospree.io/api/v2/directory/accounts' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
--data-raw '{
"reference_id": "${ACCOUNT_ID}",
"account_type": "entity",
"account_category": "recipient",
"email": "info@blockchainfinanz.de",
"entity": {
"registration_country": "DE",
"entity_name": {
"name_type": "LEGL",
"name_legal": "Blockchain Finanz GmbH",
"name_business": "Blockchain Finanz Solutions"
},
"entity_localname": {
"name_type": "LEGL",
"name_legal": "Blockchain Finanz GmbH",
"name_business": "Blockchain Finanzlösungen"
}
},
"address": {
"address_type": "GEOG",
"address_line": "Suite 12",
"address_street_no": "27",
"address_street_name": "Friedrichstraße",
"address_building_name": "Finanz Tower",
"address_floor": "5",
"address_room": "502",
"address_postbox": "Postfach 1234",
"address_city": "Berlin",
"address_region": "Berlin",
"address_district": "Mitte",
"address_postcode": "10117",
"address_country_code": "DE"
}
}'
```
{% endtab %}
{% tab title="200" %}
```json
{
"status": "success",
"data": {
"reference_id": "${ACCOUNT_ID}",
"account_type": "entity",
"account_category": "recipient",
"email": "info@blockchainfinanz.de",
"individual": null,
"entity": {
"entity_name": {
"name_type": "LEGL",
"name_legal": "Blockchain Finanz GmbH",
"name_business": "Blockchain Finanz Solutions"
},
"entity_localname": {
"name_type": "LEGL",
"name_legal": "Blockchain Finanz GmbH",
"name_business": "Blockchain Finanzlösungen"
},
"registration_country": "DE"
},
"address": {
"address_type": "GEOG",
"address_line": "Suite 12",
"address_street_no": "27",
"address_street_name": "Friedrichstraße",
"address_building_name": "Finanz Tower",
"address_floor": "5",
"address_room": "502",
"address_department": null,
"address_subdepartment": null,
"address_postbox": "Postfach 1234",
"address_city_location": null,
"address_city": "Berlin",
"address_region": "Berlin",
"address_district": "Mitte",
"address_postcode": "10117",
"address_country_code": "DE"
},
"national_id": null,
"created": null,
"last_modified": null
},
"message": null
}
```
{% endtab %}
{% endtabs %}
### Step 4: Create & link a beneficiary wallet address
Create a beneficiary wallet address and link it to the beneficiary account. Similar to Step 2, use the [/api/v2/analytics/chains/{chain}/addresses/{address}](/developers/blockchain-analytics/create-address.md) endpoint to associate the wallet address with the beneficiary account, perform risk screening to assess potential threats, and ensure Travel Rule compliance before initiating a transfer. This endpoint also allows you to label the wallet as self-hosted, distinguishing it from VASP-managed wallets for compliance tracking. This step ensures that beneficiary wallet addresses are properly registered, risk-assessed, and ready for secure transactions.
{% tabs %}
{% tab title="Sample Request" %}
### Step 5: Execute a Travel Rule transfer
Now that we’ve covered the account creation and wallet linking process, you can proceed with executing a Travel Rule transfer. Using the [/api/v2/travelrule/transfers](/developers/travel-rule/api-endpoints/create-transfer.md) endpoint, Ospree automatically retrieves the necessary information from the associated accounts by tracing back from the linked wallet address. This ensures that originator and beneficiary details are validated in real time and that the transaction meets Travel Rule compliance requirements before processing. By leveraging pre-registered data, Ospree streamlines the transfer process, minimizing manual input and enhancing compliance efficiency.
{% tabs %}
{% tab title="Sample Request" %}
```powershell
curl -X POST 'https://sandbox.ospree.io/api/v2/travelrule/transfers'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
--data '{
"amount": 1.44,
"dti": "4H95J0R2X",
"protocol": "flow",
"reference_id": "demo-transfer-selfhosted",
"beneficiary_vasp_id": "${VASP_ID}",
"originator_address": "bc1q8yj0herd4r4yxszw3nkfvt53433thk0f5qst4g",
"beneficiary_address": "1LrxsRd7zNuxPJcL5rttnoeJFy1y4AffYY",
"originator_account_reference_id": "",
"beneficiary_account_reference_id": ""
}'
```
{% endtab %}
{% tab title="200" %}
```json
{
"status": "success",
"data": {
"transfer_id": "067cee70-d42a-7d59-8000-8c3db2f0c34c",
"amount": 1.44,
"amount_usd": 118942.19,
"dti": "4H95J0R2X",
"dti_name_short": [
"BTC",
"XBT"
],
"dti_name_long": "Bitcoin",
"protocol": "flow",
"beneficiary_vasp_id": "${${VASP_ID}}",
"originator_address": "bc1q8yj0herd4r4yxszw3nkfvt53433thk0f5qst4g",
"beneficiary_address": "1LrxsRd7zNuxPJcL5rttnoeJFy1y4AffYY",
"originator_account_reference_id": "${ACCOUNT_ID}",
"beneficiary_account_reference_id": "${ACCOUNT_ID}",
"transaction_hash": null,
"transfer_status": "Information Sent"
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
Which Protocol Should I Select? The protocol you select depends on the counterparty VASP’s Travel Rule implementation. Ospree supports multiple protocols to ensure seamless interoperability.\
\
If you’re unsure which protocol to use, you can:
• Check the Search VASP endpoint to see if protocol information is available.
• Use Ospree’s auto-detection feature in the dashboard to determine the best protocol option.
Note: Since Travel Rule adoption is still evolving, many companies do not yet have a Travel Rule solution. VASP counterparty database is continuously updated to enhance VASP interoperability. For further details, please contact our team at .
{% endhint %}
{% hint style="success" %}
What is DTI? A Digital Token Identifier (DTI) is a global identification standard for digital tokens, established by the International Organization for Standardization (ISO 24165). It provides a unique identifier for each digital asset, ensuring standardized classification and improving transparency across financial and regulatory systems. For further details see:
{% endhint %}
{% hint style="success" %}
As you might have noticed, transaction\_hash is an optional parameter. Typically, companies initiate Travel Rule transfers and once the data handshake is completed, the blockchain transaction is triggered. At this point, the transaction hash can be updated using the following endpoint: PATCH /api/v2/travelrule/transfers/{transfer\_id}\
However, in some cases, companies may choose to proceed with the blockchain transaction first. In such scenarios, they can include the transaction\_hash parameter during the initial Travel Rule transfer request to provide this information upfront.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.ospree.io/quick-start/quickstart.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.