BxBytix

POST/v1/payouts

Create Payout

Create a customer withdrawal to an approved payout wallet. The amount is held from your main wallet balance of that asset on that network. New payouts start as awaiting_approval until the merchant approves in the dashboard (or automatically, under your auto-approve limit). Same payout_id for a workspace returns the stored payout (idempotent create). There is no checkout URL.

Request body

payout_idstringrequired

Your payout ID. Unique per workspace. Reuse returns the stored payout and does not debit again.

amountstringrequired

USD amount as a decimal string, greater than 0.

assetstringrequired

Ticker from GET /v1/coins payout_coins[].symbol, for example USDT.

networkstringrequired

Network from payout_coins[].network: Tron, Ethereum or Binance Smart Chain (case-insensitive). The protocol (TRC-20, ERC-20, BEP-20) is also accepted.

addressstringrequired

Destination address on that network. Must be an approved payout wallet of this payer_id for this asset and network (see Create Payout Wallet).

payer_idstringrequired

Your user id. Must own the approved payout wallet. Shown on the dashboard Withdrawals list.

callback_urlstringoptional

Per-payout webhook URL, http:// or https://. If omitted, payout events go to the payout webhook URL, else the webhook URL, from Settings → Notifications.

Headers

Authorizationheaderrequired

Bearer pk_… from dashboard Settings → Developer.

Content-Typeheaderoptional

application/json on POST bodies. Not required on GET.

Response data

Wrapped as { code, msg, data }. HTTP 201 on a new payout, 200 when payout_id already exists.

idstringrequired

Bytix payout id. Stable. Use it with query if you stored it.

payout_idstringrequired

Your payout id. Unique per workspace. Repeating it on create returns this same payout.

amountstringrequired

USD amount as a decimal string.

currencystringrequired

Always USD.

assetstringrequired

Ticker sent on-chain, for example USDT.

networkstringrequired

Network display name, for example Tron.

addressstringrequired

Destination address.

crypto_amountstringoptional

Quoted crypto amount for the requested USD, as a decimal string.

fee_amountstringoptional

Fees of the withdrawal, in the payout asset.

fee_paid_bystringoptional

merchant: the fees come from your balance and the full amount is sent. customer: they are taken off what is sent.

net_amountstringoptional

Crypto sent on-chain: crypto_amount when you pay the fees, crypto_amount minus fee_amount when the customer does.

quote_ratestringoptional

USD per unit of the asset at the market price when the withdrawal was requested.

statusstringrequired

awaiting_approval, pending (approved, being sent), submitted, completed, rejected, or failed.

txidstringoptional

On-chain transaction id when completed, else null.

payer_idstringrequired

Your user id from create.

demobooleanrequired

True when the payout was created with a demo key. Simulated: nothing is sent and no balance changes.

created_atstringrequired

ISO-8601 create time.

Errors

Failures still return JSON. Read code, not only the HTTP status. Full table: Errors.

40000HTTP 400optional

Validation: missing fields, amount ≤ 0, unknown asset/network, invalid address, or the destination is not an approved payout wallet of this payer_id.

40001HTTP 409optional

Not enough of that asset on that network in your main wallet. The message includes the available amount.

40003HTTP 400optional

Above the maximum withdrawal, or the daily withdrawal limit, set for your account.

40100HTTP 401optional

Missing or invalid API key, or the workspace is not active.

50300HTTP 503optional

Your wallets are still being prepared, or the market price of that asset is briefly unavailable. Try again in a few minutes.