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-03-12T12:40:13.221Z",
  "updatedAt": "2026-03-12T12:40:13.221Z"
}

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

Successful response with withdrawal status details

orderIdstringRequired

The order ID for the withdrawal, set by the merchant.

statusstring · enumRequired

Current status of the payout.

Possible values:

methodstring · enumOptional

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

Default: directPossible values:

currencystringRequired

Type of currency used for the payout (e.g., usdt, usdc).

networkstringRequired

Blockchain network associated with the payout (e.g., eth, sepolia, polygon, amoy).

amountnumberRequired

The requested amount for the payout.

payoutIdstring · uuidRequired

Unique identifier for the payout.

walletAddressstringOptional

Recipient’s wallet address.

binanceIdstringOptional

Recipient’s Binance ID.

customerIdstringRequired

Customer's ID for security purposes.

customerIpstringRequired

The customer's IP address, recorded for compliance purposes.

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.

additionalDatastringOptional

Additional information, optional, set by the merchant.

webhookUrlstring · uriOptional

The URL to which events for this withdrawal request will be sent.

createdAtstring · date-timeRequired

Date and time when the payout was created.

updatedAtstring · date-timeRequired

Date and time of the last update to the payout information.

paidAmountnumberRequired

Amount that has been paid out.

merchantAmountnumberRequired

Amount of money that was withdrawn from the merchant's account.

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-03-12T12:40:13.221Z",
  "updatedAt": "2026-03-12T12:40:13.221Z",
  "paidAmount": 1,
  "merchantAmount": 1
}