Skip to main content
This playbook assumes an external custody platform holds end-user assets, you drive the ramp UX, and ZBX handles conversion and settlement. Read Core Concepts first and hold valid API keys for this environment.

​
Off-ramp walkthrough (crypto → fiat)

  1. Register your fiat external account (once per settlement currency): POST /bankAddressBook with bank details. It starts Pending while verified; fiat off-ramp needs the account enabled before the first trade.
  2. Fund: deposit crypto from custody to your virtual account wallet for the chain (GET /accounts/virtual lists each chain sub-account and address). Credit is detected on-chain automatically; watch GET /accounts/virtual/balances before quoting.
  3. Preview price with quicktrade + dry_run: true and show the user receive amount and effective rate. Estimates move with the market: refresh every 10–30 seconds while the user is deciding.
  4. Execute once the user confirms:
  1. Persist order_id, quote_id, and your reference before showing success to the user: you need them for tracking and reconciliation. The order listing does not echo reference back.
  2. Track to completion: poll GET /trade/order:
    • every 5–10 s while status == "Open" (back off to ~30 s after a few minutes)
    • optional: GET https://mapi.zbx.boomfi.xyz/v1/trade/order?status=Open
    • terminal success: status "Closed" + settlement_status "Completed"
    • terminal failure: status "Rejected": sold funds remain on your balance
  3. Fiat leg: proceeds are delivered to your registered fiat external account for the currency. Delivery rails and cadence are configured per organisation; pay the end-user out from there via your own processes.

​
Delivering to external custody

Set settlement_address on any trade to deliver proceeds on-chain instead of crediting your ZBX balance: for example straight into a custody deposit address after a crypto → crypto conversion. The address must belong to the buy chain (to_chain_id). On-chain delivery to a wrong-but-valid address is irreversible: source custody addresses with the same care as any on-chain transfer. Track delivery like any order: Completed means the transfer to the settlement address has been sent on-chain.

​
Going the other way

The same primitives run in reverse: a fiat-funded Quick Trade with settlement_address pointing at a custody wallet delivers crypto straight into custody. Fiat-funded execution is enabled per organisation: speak to your ZBX contact during onboarding.

​
Error handling and retries

​
Timeout on execution calls

There is no idempotency key: never blind-retry a Quick Trade / Sweep Trade that timed out. First list recent orders (GET /trade/order?since=…) and match on the created_at window and expected size; the order may exist even though the response was lost.

​
Common API errors

​
Reconciliation

  • Store the order_id ↔ your reference mapping at execution time. reference is echoed in the execution response but not in the order listing.
  • GET /accounts/virtual/balances is the source of truth for available funds; pending_amount covers locked and in-flight value, so available + pending should not understate your position mid-trade.
  • Per completed order: reconcile sold amount and received amount from the order/quote fields exposed in responses. For sweeps, split comma-separated multi-leg fields into one position per entry.

​
Go-live checklist

  • Integrate and soak thoroughly before production volume.
  • API keys and signing secrets are per environment: store them like production credentials.
  • Implement the timeout-recovery path (list-then-match) before launch, not after the first lost response.
  • Poll with backoff; alert on any order Open longer than you expect (for example 30 minutes) or any Rejected order.
  • Register a fiat external account for each settlement currency and confirm they are verified and enabled.
  • Agree operational contacts and an escalation path for stuck orders before real volume.

​
Operational notes

  • reference is free-form and not uniqueness-enforced: bring your own uniqueness if you key on it.
  • Dry-run estimates are indicative; the executed trade re-quotes at execution time. In calm markets drift is usually negligible for stablecoin pairs.
  • Execution routing, venue selection, and liquidity sourcing are internal. API responses expose economics only (rate, fees, delivered amount) by design.