> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zbx.boomfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/trading/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:

```bash theme={null}
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/overview)
* [Trading API Guide](/trading/api-guide)
* [Authentication](/authentication)