Withdrawal Endpoints¶

This section covers API endpoints related to withdrawals. Withdrawal operations allow users to send funds from their platform balance to external addresses or accounts. Depending on the cryptocurrency or fiat method, withdrawals may require additional attributes like tags, memos, or bank details, and have specific network fees and processing conditions.

Get Personal Withdrawal Methods¶

Returns withdrawal methods available to the authenticated user, considering their segments. It also reports the user's specific limits and fees for each method.

GET /withdrawal-methods

Required Permissions¶

• allow_withdraw

Rate Limit¶

30 requests per minute

Response¶

Returns list of objects:

Attributes Config Object¶

The attributes_config field contains a JSON object defining any additional attributes required for the withdrawal method. Each key in this object represents an attribute name, and its value is another object with the following fields:

Attributes Class Names¶

Crypto Address¶

Those classes are only require address that has valid format according to network of withdraw method.

• AnyAddressAttributes - only address field required, valid for any network. Used only for testing.
• CryptoAddressAttributes - only address field required. Same as AnyAddressAttributes but with validation according to network.
• CryptoAddressWithTagAttributes - requires additional tag field.
• BitcoinAddressAttributes - only address field required, valid for Bitcoin network.
• LitecoinAddressAttributes - only address field required, valid for Litecoin network.
• EthereumAddressAttributes - only address field required, valid for Ethereum network. Other EVM networks also supported.
• RippleAddressAttributes - requires additional tag field, valid for Ripple network.
• StellarAddressAttributes - requires additional tag field, valid for Stellar network
• TronAddressAttributes - only address field required, valid for Tron network
• SolanaAddressAttributes - only address field required, valid for Solana network
• TonAddressAttributes - address field is required, valid for TON network. Additional message or tag fields are optional. tag is an alias for message field.
• MoneroAddressAttributes - has additional payment_id field, valid for Monero network. Use tag to set payment_id field.

Fiat Withdrawal¶

Those classes require address field that may contain bank account number, card number or other identifier. Also additional fields may be required in beneficiary object.

• CardNumberAttributes - requires address field to contain card number.
• CardBeneficiaryAttributes - requires address field to contain card number and additional fields in beneficiary object.
• CardEDRPOUAttributes - requires address field to contain card number, additional fields in beneficiary object and edrpou field in beneficiary object.

Internal transfers¶

Those classes require only address field that should contain account identifier uid.

• UserUIDAttributes - requires address field to contain user uid.

Future classes¶

More classes may be added in the future to support additional networks and methods.

Example of Withdraw Methods Response¶

[
  {
    "code": "BTC",
    "name": "BTC Bitcoin",
    "method_type": "crypto",
    "currency": "BTC",
    "coin": "BTC",
    "network": "bitcoin",
    "min_amount": "0.00000001",
    "max_amount": null,
    "fee_percent": "0.00000000",
    "fee_percent_min": null,
    "fee_percent_max": null,
    "fee_absolute": "0.00000000",
    "attributes_config": {
      "class_name": "BitcoinAddressAttributes",
      "params": null
    },
    "is_enabled": true,
    "spend_precision": 8,
    "receive_precision": 8
  },
  {
    "code": "USDTTRC20",
    "name": "USDT Tron",
    "method_type": "crypto",
    "currency": "USDT",
    "coin": "USDTTRC20",
    "network": "tron",
    "min_amount": "0.00000001",
    "max_amount": null,
    "fee_percent": "0.00000000",
    "fee_percent_min": null,
    "fee_percent_max": null,
    "fee_absolute": "0.00000000",
    "attributes_config": {
      "class_name": "TronAddressAttributes",
      "params": null
    },
    "is_enabled": true,
    "spend_precision": 8,
    "receive_precision": 8
  },
  {
    "code": "USDTERC20",
    "name": "USDT Ethereum",
    "method_type": "crypto",
    "currency": "USDT",
    "coin": "USDTERC20",
    "network": "ethereum",
    "min_amount": "0.00000001",
    "max_amount": null,
    "fee_percent": "0.00000000",
    "fee_percent_min": null,
    "fee_percent_max": null,
    "fee_absolute": "0.00000000",
    "attributes_config": {
      "class_name": "EthereumAddressAttributes",
      "params": null
    },
    "is_enabled": true,
    "spend_precision": 8,
    "receive_precision": 8
  }
]

Create Withdrawal¶

Initiates a withdrawal request.

POST /withdraw

Required Permissions¶

• allow_withdraw

Rate Limit¶

600 requests per minute

Request Parameters¶

Beneficiary object (for fiat withdrawals)¶

Here are the fields for the beneficiary object used in fiat withdrawals:

Also note that in case of fiat withdrawal if card used card number should be passed in address field and other beneficiary fields should be passed in beneficiary object.

On other hand if for example SEPA method used address field should contain IBAN and other beneficiary fields should be passed in beneficiary object.

Example Request for Crypto Withdrawal¶

{
  "currency": "BTC",
  "method": "BTC",
  "amount": "0.05000000",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "callback_url": "https://example.com/callbacks/withdrawals",
  "custom_id": "my-withdrawal-123",
  "receive_mode": true
}

Example Request for Fiat Withdrawal¶

{
  "currency": "EUR",
  "method": "sepa",
  "amount": "1000.00",
  "address": "DE89370400440532013000",
  "beneficiary": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "iban": "DE89370400440532013000"
  },
  "callback_url": "https://example.com/callbacks/withdrawals",
  "custom_id": "my-withdrawal-456",
  "receive_mode": true
}

Response¶

{
  "code": "WDR123456",
  "custom_id": "my-withdrawal-123",
  "callback_url": "https://example.com/callbacks/withdrawals",
  "created_at": "2023-01-15T14:30:15Z",
  "updated_at": "2023-01-15T14:30:15Z",
  "closed_at": null,
  "currency": "BTC",
  "coin": "BTC",
  "method": "BTC",
  "network": "bitcoin",
  "contract": null,
  "status": "pending",
  "reason_code": null,
  "reason_message": null,
  "amount": "0.05000000",
  "fee_amount": "0.00020000",
  "paid_amount": "0.00000000",
  "paid_fee_amount": "0.00000000",
  "txid": null,
  "attributes": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  },
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
}

Response Fields¶

Beneficiary Object (for fiat withdrawals)¶

All fields are optional, but some may be required depending on the withdrawal method.

List Withdrawals¶

Returns a list of withdrawals.

GET /withdraw

Required Permissions¶

• allow_withdraw

Rate Limit¶

600 requests per minute

Query Parameters¶

Response¶

The API uses simple offset-based pagination with limit and offset parameters. Offset is limited for maximum 10000, if you set more - error will be returned. The default limit is 100, and the maximum limit is 200. The response is a direct list of withdrawal objects without pagination metadata wrapper. If you need to fetch more than 200 withdrawals, you should use the start_at and end_at parameters to fetch withdrawals in smaller date ranges. List is sorted by creation date in descending order.

[
  {
    "code": "WDR123456",
    "custom_id": "my-withdrawal-123",
    "callback_url": "https://example.com/callbacks/withdrawals",
    "created_at": "2023-01-15T14:30:15Z",
    "updated_at": "2023-01-15T14:30:15Z",
    "closed_at": null,
    "currency": "BTC",
    "coin": "BTC",
    "method": "BTC",
    "network": "bitcoin",
    "contract": null,
    "status": "pending",
    "reason_code": null,
    "reason_message": null,
    "amount": "0.05000000",
    "fee_amount": "0.00020000",
    "paid_amount": "0.00000000",
    "paid_fee_amount": "0.00000000",
    "txid": null,
    "attributes": {
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
    },
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }
  // More withdrawals...
]

Response Fields¶

Same as the creation withdrawal response.

Pagination¶

The API uses simple offset-based pagination with limit and offset parameters. No additional pagination metadata is returned in the response or headers.

Withdrawal Status Values¶

Transaction hash¶

Withdrawal order may receive a transaction hash before order is success, while transaction is pending and not confirmed in blockchain. In some cases such transaction hash may be replaced, if for example transaction gas need to be bumped or transaction is replaced by another one. In such cases transaction hash will be updated in withdrawal order.

Get Withdrawal Details¶

Returns details of a specific withdrawal.

GET /withdraw/{code}

Required Permissions¶

• allow_withdraw

Rate Limit¶

600 requests per minute

Path Parameters¶

Response¶

Same as a single withdrawal object from the list endpoint.

Callback Notifications¶

If a callback_url was provided when creating the withdrawal, the system will send POST requests to this URL when the withdrawal status changes.

Important Note: You may not receive callbacks for every intermediate status change or field update if changes occur very rapidly. When operations transition through multiple states quickly, intermediate callbacks may be skipped. However, you will always receive callbacks for the final states of operations. Design your callback handling to be idempotent and not dependent on receiving every single state transition.

Currently, callbacks are not signed. The signature mechanism for callbacks is planned for a future update. You should validate callback data by making an authenticated API request to verify the withdrawal status.

Callback Payload¶

The callback payload contains the same data as the withdrawal details response, with essential fields for status updates:

{
  "code": "WDR123456",
  "custom_id": "my-withdrawal-123",
  "callback_url": "https://example.com/callbacks/withdrawals",
  "created_at": "2023-01-15T14:30:15Z",
  "updated_at": "2023-01-15T14:30:15Z",
  "closed_at": null,
  "currency": "BTC",
  "coin": "BTC",
  "method": "BTC",
  "network": "bitcoin",
  "contract": null,
  "status": "pending",
  "reason_code": null,
  "reason_message": null,
  "amount": "0.05000000",
  "fee_amount": "0.00020000",
  "paid_amount": "0.00000000",
  "paid_fee_amount": "0.00000000",
  "txid": null,
  "attributes": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  },
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
}

Securing Callbacks¶

Since callbacks are not currently signed, you should implement these security measures:

1. Whitelist IPs: Accept callbacks only from the service's IP addresses. Contact support to get the list of server IPs.
2. Verify Data: Always make an authenticated API request to /withdraw/{code} to verify the status and details of any withdrawal after receiving a callback.
3. Use HTTPS: Ensure your callback URL uses HTTPS to encrypt the data in transit.

Common Use Cases¶

• Initiating withdrawals: Send funds to external addresses
• Monitoring withdrawals: Track the status of outgoing withdrawals
• Reconciling withdrawals: Verify that withdrawals have been correctly processed