Send Payout

To test the API, make sure to include x-api-key in the header with your API key.

Create payout.

post

Creates a payout by specifying the wallet address, amount, currency, network, customer details, and an optional webhook URL for notifications. This endpoint initiates the process of transferring funds to the user's specified wallet.

Authorizations

ApiKeyAuth

x-api-keystringRequired

Body

application/json

Withdrawal creation request body.

methodstring · enumOptional

A method to make a payout (e.g., to a web3 wallet, or Binance Account).

Default: directPossible values:

binanceIdstring · min: 1Optional

Recipient's Binance Pay ID or Binance Email. If the payout method is Binance Pay, this field is required.

kucoinpayIdstring · min: 1Optional

Recipient's Kucoin Pay ID . If the payout method is Kucoin Pay, this field is required.

walletAddressstringOptional

Recipient's wallet address.

networkFeeByUserbooleanRequired

Specifies whether the network fee should be deducted from the amount being withdrawn (true) or the remaining balance (false). Choose the latter option if you need to send a specific amount.

amountnumberRequired

Amount to withdraw.

currencystring · min: 1Required

Currency for withdrawal, specified via tickers (refer to API glossary).

networkanyRequired

Blockchain network for withdrawal, specified via tickers (refer to API glossary).

customerIdstring · min: 1Required

Customer's ID for security purposes.

customerIpstring · min: 1Required

Customer's IP address for security purposes.

orderIdstring · min: 1Required

Customer's order ID.

additionalDatastringOptional

Additional information related to the payout, if needed.

webhookUrlstringOptional

Webhook address for receiving withdrawal notifications.

Responses

201

201

application/json

500

500

application/json

post

/v1/payout

HTTPcURLJavaScriptPython

POST /v1/payout HTTP/1.1
Host: api.bitnbox.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 251

{
  "method": "direct",
  "binanceId": "text",
  "kucoinpayId": "text",
  "walletAddress": "text",
  "networkFeeByUser": true,
  "amount": 1,
  "currency": "text",
  "network": null,
  "customerId": "text",
  "customerIp": "text",
  "orderId": "text",
  "additionalData": "text",
  "webhookUrl": "text"
}

{
  "orderId": "text",
  "status": "created",
  "method": "direct",
  "currency": "text",
  "network": "text",
  "amount": 1,
  "payoutId": "123e4567-e89b-12d3-a456-426614174000",
  "walletAddress": "text",
  "binanceId": "text",
  "customerId": "text",
  "customerIp": "text",
  "networkFeeByUser": true,
  "additionalData": "text",
  "webhookUrl": "https://example.com",
  "createdAt": "2026-02-03T15:29:01.402Z",
  "updatedAt": "2026-02-03T15:29:01.402Z"
}

The amount field has a restriction on the number of characters supported after the decimal point, depending on the currency. Supported number of decimal places:

USDT — up to 6 digits USDC — up to 6 digits

ETH — up to 8 digits POL — up to 8 digits TRX — up to 6 digits BNB — up to 8 digits

If the maximum number of characters is exceeded, the request will be rejected with an error.

{
    "message": "Invalid decimal precision for {currency}. Maximum {number} decimal places allowed",
    "statusCode": 422
}

get

Authorizations

ApiKeyAuth

x-api-keystringRequired

Path parameters

idstring · uuidRequired

Unique identifier of the withdrawal

Responses

200

200

application/json

500

500

application/json

get

/v1/payout/{id}/status

HTTPcURLJavaScriptPython

GET /v1/payout/{id}/status HTTP/1.1
Host: api.bitnbox.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "orderId": "text",
  "status": "created",
  "method": "direct",
  "currency": "text",
  "network": "text",
  "amount": 1,
  "payoutId": "123e4567-e89b-12d3-a456-426614174000",
  "walletAddress": "text",
  "binanceId": "text",
  "customerId": "text",
  "customerIp": "text",
  "networkFeeByUser": true,
  "additionalData": "text",
  "webhookUrl": "https://example.com",
  "createdAt": "2026-02-03T15:29:01.402Z",
  "updatedAt": "2026-02-03T15:29:01.402Z",
  "paidAmount": 1,
  "merchantAmount": 1
}