Transfers & Withdrawals
POST
/custody/transfer
Transfers funds between two custody accounts. Both accounts must belong to the same tenant and support the specified blockchain.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| from_account_id required | string | The ID of the source custody account |
| to_account_id required | string | The ID of the destination custody account |
| blockchain required | string | The blockchain network to use for the transfer (ETH, BSC, TRX, SOL) |
| amount required | number | The amount to transfer in USDT |
| reference optional | string | A reference or note for the transfer |
Example Request
POST /custody/transfer
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"from_account_id": "550e8400-e29b-41d4-a716-446655440000",
"to_account_id": "550e8400-e29b-41d4-a716-446655440001",
"blockchain": "ETH",
"amount": 100.50,
"reference": "Monthly allocation to trading account"
}
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| transfer_id | string | Unique identifier for the transfer |
| from_account_id | string | The ID of the source account |
| to_account_id | string | The ID of the destination account |
| blockchain | string | The blockchain network used for the transfer |
| amount | number | The amount transferred |
| status | string | Current status of the transfer (e.g., "completed", "processing") |
| created_at | string | ISO 8601 timestamp of when the transfer was created |
| completed_at | string | ISO 8601 timestamp of when the transfer was completed (if applicable) |
| reference | string | The reference or note provided for the transfer |
Example Response
{
"transfer_id": "123e4567-e89b-12d3-a456-426614174000",
"from_account_id": "550e8400-e29b-41d4-a716-446655440000",
"to_account_id": "550e8400-e29b-41d4-a716-446655440001",
"blockchain": "ETH",
"amount": 100.50,
"status": "completed",
"created_at": "2025-04-16T15:30:25.123Z",
"completed_at": "2025-04-16T15:30:30.456Z",
"reference": "Monthly allocation to trading account"
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | The request was malformed or contained invalid parameters |
| 400 | insufficient_funds | The source account does not have sufficient funds for the transfer |
| 400 | same_account | The source and destination accounts cannot be the same |
| 401 | authentication_failed | Authentication failed. Check your API key or JWT token |
| 403 | insufficient_permissions | You do not have permission to transfer funds between these accounts |
| 404 | account_not_found | One or both of the specified accounts was not found |
| 429 | rate_limit_exceeded | You have exceeded the rate limit for this endpoint |
| 500 | custody_provider_error | An error occurred with the custody provider when processing the transfer |
Notes
- Transfers between accounts are typically processed immediately as they are internal to the custody provider
- Both accounts must support the specified blockchain
- The source account must have sufficient funds for the transfer
- Account balances will be updated automatically after the transfer is completed
POST
/custody/withdraw
Withdraws funds from a custody account to an external blockchain address. This operation initiates a withdrawal that will be processed according to the tenant's security settings.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| account_id required | string | The ID of the custody account to withdraw from |
| blockchain required | string | The blockchain network to use for the withdrawal (ETH, BSC, TRX, SOL) |
| amount required | number | The amount to withdraw in USDT |
| destination_address required | string | The blockchain address to send the funds to |
| callback_url optional | string | URL to receive status updates about the withdrawal |
| custom_id optional | string | Your reference ID for the withdrawal |
| memo optional | string | Memo or tag for blockchains that support it (e.g., for XRP or XLM) |
Example Request
POST /custody/withdraw
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"blockchain": "ETH",
"amount": 50.25,
"destination_address": "0x1234567890abcdef1234567890abcdef12345678",
"callback_url": "https://your-site.com/withdrawal/callback",
"custom_id": "WITHDRAWAL-12345"
}
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| withdrawal_id | string | Unique identifier for the withdrawal |
| account_id | string | The ID of the source account |
| blockchain | string | The blockchain network used for the withdrawal |
| amount | number | The amount being withdrawn |
| destination_address | string | The destination blockchain address |
| status | string | Current status of the withdrawal (e.g., "pending", "processing") |
| created_at | string | ISO 8601 timestamp of when the withdrawal was created |
| estimated_completion_time | string | Estimated time when the withdrawal will be processed |
| custom_id | string | Your reference ID for the withdrawal (if provided) |
Example Response
{
"withdrawal_id": "123e4567-e89b-12d3-a456-426614174000",
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"blockchain": "ETH",
"amount": 50.25,
"destination_address": "0x1234567890abcdef1234567890abcdef12345678",
"status": "pending",
"created_at": "2025-04-16T15:30:25.123Z",
"estimated_completion_time": "2025-04-16T16:30:25.123Z",
"custom_id": "WITHDRAWAL-12345"
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | The request was malformed or contained invalid parameters |
| 400 | insufficient_funds | The account does not have sufficient funds for the withdrawal |
| 400 | invalid_address | The destination address is invalid for the specified blockchain |
| 400 | minimum_amount_not_met | The withdrawal amount is below the minimum allowed |
| 401 | authentication_failed | Authentication failed. Check your API key or JWT token |
| 403 | insufficient_permissions | You do not have permission to withdraw funds from this account |
| 404 | account_not_found | The specified account was not found |
| 429 | rate_limit_exceeded | You have exceeded the rate limit for this endpoint |
| 500 | custody_provider_error | An error occurred with the custody provider when processing the withdrawal |
Notes
- Withdrawals are subject to security reviews and may require approval depending on your tenant's settings
- The withdrawal process uses Cryptofuse's cold wallet system for enhanced security
- Status updates will be sent to the callback URL if provided
- Withdrawal fees are deducted from the amount being withdrawn
- Always double-check the destination address as blockchain transactions cannot be reversed