Integration Playbook

Partner patterns for off-ramp, custody delivery, errors, reconciliation, and go-live.

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:

curl -X POST "https://mapi.zbx.boomfi.xyz/v1/trade/quicktrade" \
  -H "X-API-KEY: sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "account_reference": "treasury-main",
    "currency": "USDC",
    "chain_id": 1,
    "amount": "1250",
    "to_currency": "USD",
    "reference": "offramp-enduser-8842-000517"
  }'

5. 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.
6. 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
7. 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

Situation	Guidance
409 Trade not feasible	Pre-trade liquidity check failed. Wait briefly and submit a fresh trade; don’t tight-loop.
400 insufficient balance	Re-check GET /accounts/virtual/balances; a prior trade may still hold funds as pending_amount until it settles.
Rejected orders	Terminal; sold funds remain on your balance. Alert rather than auto-retrying; contact support with order_id if the cause is unclear.

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.

Related

• Trading Overview
• Trading API Guide
• Authentication