OTC desk integration
This guide covers everything an OTC desk needs: taking crypto from customers who sell, delivering crypto to customers who buy, pricing in USDT, keeping a USDT working balance, and reacting to webhooks. Base URL https://api.bezant.cc, header X-Bezant-Api-Key on every request, amounts are decimal strings. Full reference: /docs.
Model in one paragraph. Your customers pay into addresses Bezant issues; confirmed funds land in your balance per asset. You pay customers out of that balance with a withdrawal, or, for coins you do not hold, with an order: Bezant buys the coin on the exchange with your USDT and delivers it. Customer verification, fiat settlement and the correctness of destination addresses are yours.
Change notice · 2026-10-05
Native TRX, ETH and BNB moved to the exchange-custodied flow. They keep their asset codes but now behave like BTC: shared deposit address, exact unique amount, 60-minute expiry, credited after KuCoin's confirmations (TRX ≈ 1 min, BNB ≈ 1 min, ETH ≈ 15 min), and they can be bought-and-delivered with POST /v1/orders. USDT keeps per-payment addresses on all three networks. Use GET /v1/assets as the source of truth.
Change notice · 2026-10-06
Tron USDT network fee is now 4 USD (was 1.50) on deposits and withdrawals, matching the real TRC20 transfer cost. Expect amount_crypto on new USDT payments and the hold on USDT withdrawals to be about 2.5 USDT higher than before. Fee table: getting started.
Change notice · 2026-10-06 (2)
USDT on BNB Smart Chain and Ethereum can now be paid out from your Tron USDT balance. A customer buying USDT on those chains no longer needs a separate float there: POST /v1/transfers {"from_asset":"USDT","to_asset":"BNB-USDT","amount":"…"} moves USDT between your network balances 1:1 and instantly, with no fee; the withdrawal on that chain then follows as usual. See sections 3 and 5.
0. Before the first trade
- Save your default webhook URL (dashboard → Account) and verify signatures (section 7).
- Fund your USDT balance: create a USDT payment to yourself and pay it (section 5). Orders and USDT withdrawals are paid from this balance.
- Use an Idempotency-Key header on every POST you might retry. Same key + same merchant returns the original response, no double order.
- Store our ids (pay_…, wd_…, ord_…) next to your own deal id; every object also carries your external_id.
1. Assets and pricing
GET /v1/assets → USDT (Tron), ETH-USDT, BNB-USDT (per-payment addresses) · USDC (Solana), ETH, TRX, BNB, BTC, XRP, SOL, LTC, DOGE, GRAM (TON, memo), … (exchange-custodied, exact amount)
GET /v1/quote?asset=BTC&amount=1000¤cy=USDT
{"quote":{"asset":"BTC","currency":"USDT","amount":"1000","rate":"80356.24","rate_currency":"USD","rate_usdt":"80388.3",
"amount_crypto":"0.01243959","amount_fiat":"999.6",
"deposit":{"fee_crypto":"0.00012440","network_fee_crypto":"0","amount_to_pay_crypto":"0.01243959","net_crypto":"0.01231519","direct_mode":false},
"withdrawal":{"fee_bezant":"0.00007464","fee_network":"0.00009","total_crypto":"0.01260423"}}}
currency may be USDT (exchange spot price — what a desk normally uses), USD, or the asset code for "exactly this much crypto". Quotes are indicative; the rate is fixed when you create the payment or order. rate_usdt is present for exchange coins and USDT.
2. Customer sells crypto to you
POST /v1/payments
{"asset":"BTC","amount":"1000","currency":"USDT","external_id":"deal-101","callback_url":"https://desk.example/bezant","metadata":{"customer":"c-889"}}
201 {"status":"success","payment":{"id":"pay_47992a86e9efbcc1fadb71d5","external_id":"deal-101","asset":"BTC",
"address":"bc1qaqrheg523ag7arkecpzf6jfq7hnv0dzxs4qz07","memo":null,"expires_at":1789732580,
"currency":"USDT","amount":"1000","amount_crypto":"0.01244376","network_fee_crypto":"0","amount_crypto_net":"0.01244376",
"exchange_rate":"80356.24","status":"PENDING","paid":false,"received_crypto":"0","fee_crypto":"0","net_crypto":"0", … }}
Show the customer address, amount_crypto and memo when present (XRP-style coins — without the memo the deposit cannot be attributed). Rules that matter for a desk:
- Exchange coins (BTC, XRP, SOL, and since 2026-10-05 also ETH, TRX, BNB) use one shared address and a unique amount: the customer must send exactly amount_crypto, before expires_at (60 min). A different amount is not matched automatically; tell your customer clearly.
- On-chain assets (USDT on Tron, Ethereum, BNB Smart Chain) get a fresh address per payment; any USDT amount is credited, partial and over-payments included. Send only USDT on the network the address was issued for: native coins or USDT on another network are not detected. amount_crypto already includes the network fee the customer pays on top (network_fee_crypto); your amount is amount_crypto_net.
- Poll GET /v1/payments/{id} if you like, but rely on the webhook. Statuses: PENDING → PARTIAL → PAID | OVERPAID; paid is the boolean to act on.
Webhook when funds confirm:
{"event":"payment.updated","merchant_id":"mer_…","created_at":1789830000,
"data":{ …payment…, "status":"PAID","paid":true,"received_crypto":"0.01244376","fee_crypto":"0.00012444","net_crypto":"0.01231932",
"credited":[{"txid":"…","amount_crypto":"0.01244376","amount_fiat":"999.6","fee_crypto":"0.00012444","network_fee_crypto":"0","net_crypto":"0.01231932"}]}}
net_crypto is what was added to your balance. Settle fiat with the customer on paid:true. payment.unconfirmed arrives earlier for on-chain assets when a transaction is seen but not yet confirmed — informational only.
2b. Repeat customers: a permanent address per user
If the same verified user sells to you regularly, create one long-lasting address per user and asset (POST /v1/addresses {"asset":"USDT","customer_ref":"user-1694"}) and let them keep it. Every transfer to it is credited and reported as deposit.received with the customer_ref, no payment request needed. For USDT the address is dedicated and any amount counts. For exchange-custodied coins (USDC, BTC, …) the address is the exchange's permanent shared one: create the address once, then one payment per transfer with address_id so the unique amount identifies the user; details in getting started §5.
3. Customer buys crypto you hold
POST /v1/withdrawals (Idempotency-Key: deal-102)
{"asset":"USDT","amount":"500","address":"TXYZ…","external_id":"deal-102"}
201 {"status":"success","withdrawal":{"id":"wd_…","external_id":"deal-102","asset":"USDT","address":"TXYZ…","memo":null,"kind":"MANUAL",
"amount":"500","fee_bezant":"3.5","fee_network":"1.5","total":"505","status":"SUBMITTED","txid":null,"error":null, … }}
total (amount + fees) is held from your balance immediately. 402 = insufficient balance, nothing held. 502 with status:"FAILED" = the network rejected it, hold released. Lifecycle: SUBMITTED → COMPLETED (webhook withdrawal.completed with txid) or FAILED (withdrawal.failed, funds returned). A withdrawal spends the balance of its own network; to pay out on BNB Smart Chain or Ethereum from USDT you received on Tron, first POST /v1/transfers {"from_asset":"USDT","to_asset":"BNB-USDT","amount":"500"} (1:1, instant, no fee), then withdraw BNB-USDT. Add memo for XRP-style destinations.
4. Customer buys a coin you do not hold (buy & deliver)
You keep USDT; Bezant sources the coin. Works for every exchange coin (BTC, XRP, SOL, LTC, DOGE, ETH, TRX, BNB, …). USDT itself is withdrawn from your balance (section 3).
GET /v1/orders/quote?asset=BTC&amount=0.01
{"quote":{"asset":"BTC","amount":"0.01","min_amount":"0.00018","pay_asset":"USDT","price":"80386.4","trade_size":"0.0010911","fee_network":"0.00009",
"estimated_cost":"87.709601","fee_percent":"0.5","hold":"89.470372"}}
POST /v1/orders (Idempotency-Key: deal-103)
{"asset":"BTC","amount":"0.01","address":"bc1customer…","external_id":"deal-103"}
201 {"status":"success","order":{"id":"ord_…","external_id":"deal-103","asset":"BTC","amount":"0.01","address":"bc1customer…","memo":null,
"pay_asset":"USDT","price":"80386.4","trade_size":"0.0010911","hold":"89.470372",
"cost":"87.71","fee_bezant":"0.43855","charged":"88.14855","fee_network":"0.00009","status":"DELIVERING","txid":null,"error":null, … }}
What happens: up to hold USDT is reserved → the coin is market-bought (trade_size covers the exchange trading fee and the withdrawal fee so the customer receives exactly amount) → you are charged the real cost + fee_bezant = charged, the rest of the hold returns to your balance → the coin is withdrawn to the address.
Minimum per coin (since 2026-10-07): the exchange will not withdraw less than min_amount (on 2026-10-07: 0.8 GRAM, 14 XRP, 0.00018 BTC; these follow the exchange, so always use the live value). Smaller orders are refused with 400 at quote and at order time, before anything is bought or held, so read min_amount from the quote and enforce it in your checkout. If the exchange has suspended withdrawals of a coin, orders get 503 (retry later), again with nothing bought.
| Status | Meaning | Your action |
|---|---|---|
| BUYING | fill not yet confirmed (rare); finishes within minutes | wait for webhook |
| DELIVERING | bought and charged; exchange withdrawal in progress | wait for order.completed |
| COMPLETED | on chain, txid set | done |
| FAILED | nothing bought, hold released; error says why (402 = not enough USDT) | retry or refund your customer |
| UNDELIVERED | bought and charged but the exchange withdrawal failed; Bezant operators are alerted and retry — you are never charged twice | wait; contact Bezant if not completed in an hour |
Quote the customer from estimated_cost plus your margin, but reconcile on charged: a market buy can fill slightly above the quoted price (the hold includes 1.5 % headroom; anything beyond it is Bezant's risk, not yours).
5. Your USDT working balance
GET /v1/balances → {"balances":[{"asset":"USDT","available":"4210.5","held":"88.14"},{"asset":"BTC","available":"0.0123","held":"0"}]}
POST /v1/payments {"asset":"USDT","amount":"5000","currency":"USDT","external_id":"topup-2026-09-21","topup":true} → pay it from your own wallet (Tron, cheapest); top-ups carry no Bezant fee
POST /v1/payments {"asset":"ETH-USDT","amount":"5000","currency":"ETH-USDT","external_id":"topup-eth-1","credit_asset":"USDT"} → pay on Ethereum, credited to the USDT balance 1:1
POST /v1/payments {"asset":"BNB-USDT","amount":"5000","currency":"BNB-USDT","external_id":"topup-bnb-1","credit_asset":"USDT"} → same on BNB Smart Chain
POST /v1/transfers {"from_asset":"USDT","to_asset":"BNB-USDT","amount":"500","external_id":"mv-1"} → the outbound counterpart: USDT moved 1:1 to your BNB-USDT balance, instantly, no fee; then POST /v1/withdrawals {"asset":"BNB-USDT", …}
You can also top up from the dashboard (Overview → Top up) and set your own minimum (dashboard → Account, or PATCH /v1/me {"reserve_min_usdt":"2000"}; GET /v1/me returns reserve.available, reserve.minimum and reserve.low). held is reserved by in-flight withdrawals and orders. When available USDT drops below your minimum you receive reserve.low (webhook + e-mail) once a day until topped up; orders that cannot be covered are refused with 402, never partially executed. GET /v1/ledger?asset=USDT lists every posting for reconciliation.
6. Errors
| HTTP | When |
|---|---|
| 400 | bad input (amount, currency, missing field) — message says which |
| 401 | missing/revoked API key |
| 402 | insufficient balance for a withdrawal, order or subscription |
| 404 | unknown asset or id (also another merchant's id) |
| 409 | external_id already used for a withdrawal/order |
| 502 | chain gateway or exchange rejected the request; body still contains the object with status/error |
| 503 | rate temporarily unavailable — retry after a few seconds |
Every error body is {"status":"error","message":"…"}.
7. Webhooks
POST https://desk.example/bezant headers: X-Bezant-Timestamp, X-Bezant-Signature, Content-Type: application/json
{"event":"order.completed","merchant_id":"mer_…","created_at":1789830000,"data":{ …order… }}
Signature = HMAC-SHA256(webhook secret, "<timestamp>." + raw body), hex. Reject if it does not match or the timestamp is older than 5 minutes; respond 2xx fast; deduplicate on data.id + event (retries can repeat a delivery). Samples in Python and Node: getting started.
| Event | data | Fires when |
|---|---|---|
| payment.unconfirmed | payment + txid | transaction seen, not yet confirmed (on-chain assets) |
| payment.updated | payment + credited[] | funds confirmed and credited (act on paid) |
| withdrawal.completed | withdrawal (txid) | payout on chain |
| withdrawal.failed | withdrawal (error) | payout failed, funds returned |
| order.completed | order (txid) | coin delivered |
| order.failed | order (error) | purchase failed (hold released) or delivery failed (operators retrying) |
| reserve.low | {asset, available, minimum} | USDT balance below your minimum |
Deliveries and a resend button are in the dashboard under Webhooks.
8. Go-live checklist
- Webhook endpoint verifies signatures and answers 2xx; tested with a resend from the dashboard.
- One real sell: create a small USDT payment, pay it, receive payment.updated, see the balance.
- One real buy from balance: small USDT withdrawal, receive withdrawal.completed.
- One real order: e.g. 0.0002 BTC to your own wallet, receive order.completed, check charged against your quote.
- Idempotency keys on every POST; duplicate webhook handling; reserve.low wired to your treasury alerts.