> For the complete documentation index, see [llms.txt](https://docs.fonbnk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fonbnk.com/server-to-server/api-endpoints/merchant-balance.md).

# Merchant balance

Your merchant balance is a USD float you can spend on payouts and be credited into by collections. These endpoints move crypto in and out of it.

They are **not** orders in the [Flow examples](/server-to-server/integration-guide/flow-examples.md) sense — there is no end user. You are funding or draining your own balance.

All routes live under `/api/v2/merchant-balance/` and use the standard signed-request headers. See [Signing requests](/server-to-server/signing-requests.md).

### Availability

These features are gated. Fonbnk must enable them for your account, and creating a deposit or withdrawal also needs a verified merchant organization. Reads, cancels, options and limits stay open once the feature is on.

| Error | Code                                        |
| ----- | ------------------------------------------- |
| `403` | `MERCHANT_BALANCE_CRYPTO_DEPOSIT_DISABLED`  |
| `403` | `MERCHANT_BALANCE_CRYPTO_WITHDRAW_DISABLED` |
| `403` | `MERCHANT_ORG_NOT_VERIFIED`                 |

### Deposit lifecycle

1. `deposit_awaiting` — order created. Send crypto to the `address` it returns.
2. `deposit_validating` — you submitted the transaction hash. On-chain confirmation pending.
3. `deposit_successful` — deposit confirmed.
4. `payout_pending` — the USD credit is being processed.
5. `payout_successful` — your balance is credited.

You can cancel a deposit only while it is still `deposit_awaiting`.

### Withdrawal lifecycle

On create, the USD `amount` is deducted from your balance immediately and the order starts in `deposit_successful`, waiting for Fonbnk admin approval.

After approval it moves to `payout_pending`, then `payout_successful` once the crypto is sent to your `address`.

If the withdrawal is rejected, or cancelled while still awaiting approval, the order moves to `deposit_canceled` and the deducted balance is restored.

See [Order statuses](/server-to-server/order-statuses.md).

{% hint style="warning" %}
A withdrawal is not instant. It waits on a human. Do not build a flow that assumes same-minute settlement.
{% endhint %}

### Assets

The set here is much narrower than the 44 network/asset pairs the order flows accept. It is **USDT and USDC on Celo, Ethereum and BNB**, in both directions — six pairs. Everything else, POLYGON included, is rejected up front:

* `MERCHANT_BALANCE_DEPOSIT_ASSET_UNSUPPORTED`
* `MERCHANT_BALANCE_WITHDRAW_ASSET_UNSUPPORTED`

The list is two things intersected: which assets our treasury wallets hold for this purpose, and an allowlist we maintain per direction. Both change without a release, so call the relevant `.../options` endpoint and offer what it returns rather than hard-coding these six.

### Limits

Merchant-balance crypto moves are governed by their own rules, separate from order limits, so a busy day of collections cannot exhaust your treasury budget:

| Rule                              | Value               |
| --------------------------------- | ------------------- |
| Per transaction, either direction | $5 to $10,000       |
| Withdrawals per calendar month    | $10,000 per account |

Those are the current defaults for every account. The matching `.../limits` endpoint is the authoritative answer for a given pair: it starts from these rules and can come back narrower, because the asset's own minimum and precision are applied on top. Read them at runtime with [Get limits](/server-to-server/api-endpoints/get-limits.md) too — the treasury rules are the ones with `criteria.asset: "treasury"`, and their `windowResetsAt` tells you when the monthly window rolls over.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fonbnk.com/server-to-server/api-endpoints/merchant-balance.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.