> ## 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.

# Cookbook: Deposit, convert, and withdraw fiat

> Merchant onboarding, deposits, swaps, and fiat withdrawals.

Onboard merchants and use the APIs for account management, deposits, swaps, and fiat withdrawals.

## End-to-end flow

```mermaid theme={null}
flowchart TD
  A["Create an organisation POST /partners/orgs"] --> B[API creates the organisation and user]
  B --> C[Open verification_url and complete KYC]
  C --> D{KYC approved?}
  D -->|No| C
  D -->|Yes| E[API receives the KYC update and provisions fiat and crypto accounts]
  E --> F[API provides a merchant API key]
  F --> G[You can access merchant APIs]
  G --> H[View accounts and balances]
  H --> I[Create a permanent crypto deposit address]
  I --> J[Swap assets]
  J --> K[Register an external bank account as a withdrawal destination]
  K --> L[Withdraw EUR]
  L --> M[Cancel withdrawal if eligible]
```

## 1. Merchant onboarding

Create a merchant organisation:

```
POST https://mapi.zbx.boomfi.xyz/v1/partners/orgs
```

Example response:

```json theme={null}
{
  "data": {
    "org_id": "3IDieTi1aMaCafUfmlotbHyDeSP",
    "name": "Demo-1",
    "partner_id": "2pWs0DuVESI5B1fnQWj1eXe5YIC",
    "owner": {
      "user_id": "3IDieT0UeHHhX48vEk10UFzIdvy",
      "email": "ops-1@acme.example",
      "name": "Acme Ops",
      "phone": "+4915112345678"
    },
    "kyc_status": "pending",
    "verification_url": "https://in.sumsub.com/websdk/p/...",
    "created_at": "2026-08-21T09:47:14Z"
  }
}
```

The merchant must open `verification_url` and complete KYC.

Check the onboarding status using:

```
GET https://mapi.zbx.boomfi.xyz/v1/partners/orgs/{orgId}
```

Once ZBX receives the KYC approval update, the merchant's fiat and crypto accounts are provisioned automatically. You do not need to call another provisioning endpoint.

## 2. Authentication

Signed merchant requests use these headers:

```
X-API-KEY: <API_KEY>
X-Api-Nonce: <NONCE>
X-Api-Signature: <HMAC_SIGNATURE>
```

Calculate the signature using `SIGNING_SECRET`.

Use the partner credentials for `/partners/orgs`. After onboarding, use the new merchant organisation's credentials for account, deposit, swap, and withdrawal requests.

ZBX will provide test credentials separately. Credentials must not be committed to source control or shared through an unsecured channel.

Retrieve the signing secret when credentials are first configured or after the secret is rotated:

```
GET https://mapi.zbx.boomfi.xyz/v1/orgs/signing-secret
```

This request is authenticated with the organisation API key. Do not sign it: the signing secret is not available yet.

## Test environment

A test organisation can be prepared with the required fiat and crypto accounts and API credentials.

Use the provided `API_KEY` and `SIGNING_SECRET` to test the account, balance, deposit-address, swap, and withdrawal APIs.

The organisation onboarding and KYC steps are included separately to demonstrate how you onboard new merchants.

## API overview

| Request                         | Endpoint                                           | Purpose                                                                                                  |
| ------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Get Signing Secret              | `GET /orgs/signing-secret`                         | Retrieve the secret used to sign merchant API requests.                                                  |
| Create Org                      | `POST /partners/orgs`                              | Create a merchant organisation and start onboarding.                                                     |
| Get Org                         | `GET /partners/orgs/{orgId}`                       | Read the organisation and KYC status.                                                                    |
| Get Account                     | `GET /accounts/virtual`                            | Return the virtual account and its fiat and crypto subaccounts. Use the subaccount IDs in swap requests. |
| Get Balances                    | `GET /accounts/virtual/balances`                   | Return current balances for the organisation's accounts.                                                 |
| List Account Movements          | `GET /accounts/{accountId}/movement`               | Return incoming and outgoing movements for an account and its subaccounts.                               |
| Get Payment Detail              | `GET /payments/{paymentId}`                        | Read the latest payment status and next action.                                                          |
| Get Deposit Address             | `POST /accounts/virtual/payin/address`             | Create or return a permanent crypto deposit address for a customer reference and chain.                  |
| Request Quote                   | `GET /trade/quote`                                 | Request an RFQ for a crypto-to-fiat or fiat-to-crypto swap.                                              |
| Accept Quote                    | `POST /trade/quote/{quoteId}/accept`               | Accept and execute an unexpired RFQ quote.                                                               |
| Whitelist External Bank Account | `POST /accounts/external-account`                  | Register an external EUR bank beneficiary.                                                               |
| Withdraw Fiat                   | `POST /accounts/virtual/payout`                    | Withdraw EUR from the fiat account to a registered beneficiary.                                          |
| Cancel Withdraw Fiat            | `POST /accounts/virtual/payout/{paymentId}/cancel` | Request cancellation of an eligible withdrawal.                                                          |

Paths are relative to `https://mapi.zbx.boomfi.xyz/v1`.

## 3. Accounts and balances

Use these requests to inspect the merchant's account structure:

```
GET https://mapi.zbx.boomfi.xyz/v1/accounts/virtual
GET https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/balances
GET https://mapi.zbx.boomfi.xyz/v1/accounts/{accountId}/movement
```

* Get Account returns the virtual account and its fiat and crypto accounts.
* Get Balances returns their current balances.
* List Account Movements returns incoming and outgoing movements for the selected account and its subaccounts, including deposits, swaps, and withdrawals.

```mermaid theme={null}
flowchart TD
  V[Merchant virtual account] --> EUR[EUR account]
  V --> USDC[USDC account]
  V --> OTHER[Other provisioned crypto accounts]
```

Do not reuse example account IDs for another organisation. Obtain the correct IDs from `GET /accounts/virtual`.

## 4. Crypto deposits

Create or retrieve a permanent crypto deposit address:

```
POST https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/payin/address
```

```mermaid theme={null}
sequenceDiagram
  participant You
  participant API as API
  participant Addr as Deposit Address
  participant Custody as Custody

  You->>API: Request permanent crypto deposit address
  API-->>You: Create or return existing address
  You->>You: Send address to the customer
  Note over Custody,Addr: Customer deposits on-chain
  Custody->>Addr: Detect and confirm deposit
  Addr->>Custody: Sweep to corresponding crypto account
  API-->>You: Webhook / transaction update
  You->>You: Update account balance and movement
```

The address is permanent for the same customer reference and parent account. Repeating the request returns the existing address instead of creating a new one.

The customer sends funds to the address returned by the API. After confirmation, ZBX sweeps the received asset to the corresponding parent crypto account.

The deposit network and asset must be supported by the returned address and its parent account.

<Note>
  The complete on-chain deposit flow depends on sandbox network and test-token
  support. Confirm the supported network and token before testing.
</Note>

## 5. Asset swaps

Both directions are included:

* Crypto to fiat
* Fiat to crypto

```mermaid theme={null}
sequenceDiagram
  participant You
  participant API as API
  participant Venue as Venue

  You->>API: GET /trade/quote
  API->>Venue: Build an indicative SOR quote
  Venue-->>API: Return RFQ quote and expiry
  API-->>You: RFQ quote
  Note over You,API: Quote expires after 10 seconds
  You->>API: POST /trade/quote/quoteId/accept
  API->>Venue: Request a fresh executable quote
  Venue-->>API: Return current executable price
  API->>API: Validate against the committed amount
  API->>Venue: Confirm the swap
  Venue-->>API: Return execution result
  API-->>You: Order/payment result
```

The RFQ must be accepted within 10 seconds. If it expires before acceptance, no order is created and you must request a new RFQ. After acceptance, ZBX fetches a fresh executable quote and validates it against the committed amount. If the price is outside the allowed tolerance, ZBX automatically requests another executable quote. The order is marked as Rejected only when the swap cannot be completed after all retry attempts.

Use account IDs returned by the account API:

* `deposit_account_id`: account holding the asset being sold.
* `settlement_account_id`: account receiving the purchased asset.

## 6. Fiat withdrawal

First, whitelist the beneficiary's external bank account:

```
POST https://mapi.zbx.boomfi.xyz/v1/accounts/external-account
```

Then create the EUR withdrawal:

```
POST https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/payout
```

```mermaid theme={null}
flowchart TD
  A["Register an external bank account as the withdrawal destination POST /accounts/external-account"] --> B["Create EUR withdrawal POST /accounts/virtual/payout"]
  B --> C[Receive paymentId]
  C --> D["Get withdrawal detail GET /payments/paymentId"]
  D --> E{Travel Rule information required?}
  E -->|Yes| F[Read the Travel Rule URL from next_action]
  F --> G[Open the URL and provide the required Travel Rule information]
  G --> H[Withdrawal continues]
  E -->|No| H
  H --> I[Check payment detail until the final status is available]
```

If Travel Rule information is required, the withdrawal is placed on hold. Retrieve the withdrawal details using the returned `paymentId`:

```
GET https://mapi.zbx.boomfi.xyz/v1/payments/{paymentId}
```

The payment detail returns the Travel Rule action in this format:

```json theme={null}
{
  "next_action": "travel_rule:https://example.zbx/travel-rule/..."
}
```

Use the URL after the `travel_rule:` prefix to open the form and provide the requested information. After the information is submitted and accepted, processing can continue. Call the payment-detail endpoint again to obtain the latest status.

To cancel an eligible withdrawal:

```
POST https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/payout/{paymentId}/cancel
```

Use the payment ID returned by the withdrawal API. A withdrawal can only be cancelled while it remains in a cancellable state.

## Request values

Configure these values before you run the flow:

| Variable         | Purpose                                            |
| ---------------- | -------------------------------------------------- |
| Merchant API URL | `https://mapi.zbx.boomfi.xyz/v1`                   |
| `API_KEY`        | API key for the current organisation               |
| `SIGNING_SECRET` | Secret used to sign requests                       |
| `orgId`          | Organisation created during onboarding             |
| `accountId`      | Account returned by the account API                |
| `quoteId`        | RFQ quote returned by the quote API                |
| `paymentId`      | Payment ID returned by a payment or withdrawal API |

IDs that appear in examples are test values. Replace them with values returned by earlier requests.