Requesting a Quote and Initiating a Payout

In the On-the-Fly Settlement model, payouts are powered by dynamic funding based on real-time quotes.

Before initiating any payout, you must first request a quote for the specific transaction you intend to fund.

Step 1: Request a Payout Quote

Endpoint

field	type	required	description
from_asset	String	Yes	The crypto asset to convert from (e.g., BTC, USDT, USDC).
to_currency	String	Yes	The destination fiat currency for the payout (e.g., NGN, KES).
source	String	Yes	The source of funds: 'onchain' for blockchain deposit or 'offchain' for wallet balance.
amount	String	Yes*	The crypto amount to convert. Required if settlement_amount is not provided.
settlement_amount	String	Yes*	The target fiat amount to receive. Required if amount is not provided.
chain	String	No	The blockchain network (e.g., BITCOIN, trc20, erc20). Required when source is 'onchain'.
payment_reason	String	Yes	Description of the payment purpose.
reference	String	Yes	Your unique reference for this quote.
country	String	Yes	Two-letter ISO country code for the destination (e.g., NG, KE).

Create Payouts Quote - Response

field	description
id	Unique identifier for the generated payout quote.
status	Current state of the quote (e.g., 'quote').
settlement_currency	Currency in which the payout will be settled.
quote_id	Reference used to identify the payout quote.
settlement_amount	Amount to be settled in the settlement currency.
exchange_rate	FX conversion rate applied for the settlement.
amount	Original crypto amount provided when creating the quote.
from_asset	The crypto asset used for the payout (e.g., USDT, BTC).
to_currency	The destination fiat currency (e.g., NGN, KES).
expiry	ISO 8601 timestamp indicating when the quote expires.
payment_eta	Estimated delivery time for the payout (e.g., '3-5 minutes').

Endpoint

field	type	required	description
customer_id	String	Yes	Unique identifier for the customer initiating the transaction.
beneficiary	Object	Yes	Bank or wallet details of the recipient. Structure varies by country — use GET /api/payouts/supported-countries/:countryCode/requirements.
reference	String	Yes	Unique reference for this payout transaction.
payment_reason	String	No	Reason or narration for the payout.
callback_url	String	No	Webhook URL to receive payout status updates for this transaction.
client_meta_data	String	No	JSON string of custom metadata for internal tracking.

Create Payout - Request

Initialize Payouts - Response

Customer must send the exact amountToPay to the paymentAddress.

Payment must happen before the expiresAt timestamp.

After payment is detected, Bitnob automatically proceeds with the fiat payout.

Bitnob triggers webhook notifications or allows status checking via:

Endpoint

status	meaning
awaiting_payment	Waiting for customer to fund the payout.
payment_received	Payment confirmed — payout processing begins.
processing	Fiat payout underway.
success	Payout completed to beneficiary.
failed	Payout failed due to delivery issue.
expired	Quote expired without payment.

Request a quote → Initiate payout → Pay → Receive updates.

Flexible funding with Bitcoin, USDT, or Lightning.

Fully event-driven, real-time settlement into bank accounts, mobile wallets, or cash pickup channels.

Built for speed, simplicity, and scalability.

This now properly matches your internal Offramps flow:

Endpoint

Payment address,

Webhooks + Status tracking.