Merchants
Create a Crypto Transfer
Transfer crypto assets instantly between two VelaFi merchant custody wallets as an internal transfer without incurring on-chain gas fees.
POST
/
v2
/
assets
/
internalTransfer
Create a Crypto Transfer
curl --request POST \
--url https://api-test.velafi.com/v2/assets/internalTransfer \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"fromMerchantId": 123,
"toMerchantId": 123,
"tokenId": "<string>",
"amount": 123,
"clientId": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/assets/internalTransfer"
payload = {
"fromMerchantId": 123,
"toMerchantId": 123,
"tokenId": "<string>",
"amount": 123,
"clientId": "<string>"
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fromMerchantId: 123,
toMerchantId: 123,
tokenId: '<string>',
amount: 123,
clientId: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/assets/internalTransfer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/assets/internalTransfer")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"fromMerchantId\": 123,\n \"toMerchantId\": 123,\n \"tokenId\": \"<string>\",\n \"amount\": 123,\n \"clientId\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"id": "<string>",
"tokenId": "<string>",
"amount": "<string>",
"clientId": "<string>",
"merchantId": "<string>",
"fromMerchantId": "<string>",
"toMerchantId": "<string>"
}
}Use this endpoint to move crypto assets internally from one merchant’s VelaFi custody wallet to another. Internal transfers settle instantly without incurring blockchain gas fees. The sender’s balance shows a negative
amount (debit) and the recipient’s balance shows a positive amount (credit). Supply a clientId to enable idempotency — duplicate requests with the same clientId return the original result rather than creating a second transfer.
All requests must include the
X-BH-TOKEN header and Content-Type: application/json.Endpoint
POST https://api.velafi.com/v2/assets/internalTransfer
Request Parameters
number
required
ID of the merchant sending the crypto.
number
required
ID of the merchant receiving the crypto.
string
required
Token symbol to transfer. Supported values:
USDT, USDC, BTC, MMXN.number
required
Amount of the token to transfer.
string
Your unique identifier for this transfer. Used for idempotency.
Response Fields
number
HTTP-style response code.
200 indicates success.string
Human-readable status message, e.g.
SUCCESS.object
Show data fields
Show data fields
string
Unique record ID for this transfer.
string
Token that was transferred.
string
Amount transferred. Negative on the sender’s record (debit), positive on the recipient’s (credit).
string
Your client-supplied identifier for this transfer.
string
ID of the merchant this record belongs to (same as
fromMerchantId).string
Sender merchant ID.
string
Recipient merchant ID.
Example
cURL
curl -X POST https://api.velafi.com/v2/assets/internalTransfer \
-H "X-BH-TOKEN: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"fromMerchantId": 246,
"toMerchantId": 61,
"tokenId": "USDT",
"amount": 10,
"clientId": "crypto-transfer-001"
}'
Response
{
"code": 200,
"msg": "SUCCESS",
"data": {
"id": "4352",
"tokenId": "USDT",
"amount": "-10",
"clientId": "crypto-transfer-001",
"merchantId": "246",
"fromMerchantId": "246",
"toMerchantId": "61"
}
}
The
amount in the response is negative because it represents the debit on the sender’s account. Use the Query Crypto Transfers endpoint to see both sides of the transfer.Was this page helpful?
⌘I
Create a Crypto Transfer
curl --request POST \
--url https://api-test.velafi.com/v2/assets/internalTransfer \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"fromMerchantId": 123,
"toMerchantId": 123,
"tokenId": "<string>",
"amount": 123,
"clientId": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/assets/internalTransfer"
payload = {
"fromMerchantId": 123,
"toMerchantId": 123,
"tokenId": "<string>",
"amount": 123,
"clientId": "<string>"
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fromMerchantId: 123,
toMerchantId: 123,
tokenId: '<string>',
amount: 123,
clientId: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/assets/internalTransfer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/assets/internalTransfer")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"fromMerchantId\": 123,\n \"toMerchantId\": 123,\n \"tokenId\": \"<string>\",\n \"amount\": 123,\n \"clientId\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"id": "<string>",
"tokenId": "<string>",
"amount": "<string>",
"clientId": "<string>",
"merchantId": "<string>",
"fromMerchantId": "<string>",
"toMerchantId": "<string>"
}
}