> 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

## Crypto merchant balance

These endpoints let you top up your USD merchant balance with on-chain crypto.

They also let you withdraw your USD merchant balance back out as crypto.

All routes live under `/api/v2/merchant-balance/`.

All requests use the standard signed-request authentication flow. See [Signing requests](/server-to-server/signing-requests.md).

### Availability

These features are gated.

Fonbnk must enable them for your account.

When a feature is off, the endpoint returns `403` with one of these codes:

* `MERCHANT_BALANCE_CRYPTO_DEPOSIT_DISABLED`
* `MERCHANT_BALANCE_CRYPTO_WITHDRAW_DISABLED`

Creating a deposit or withdrawal also requires a verified merchant organization.

Otherwise, the endpoint returns `403 MERCHANT_ORG_NOT_VERIFIED`.

### Deposit lifecycle

A crypto deposit moves through these statuses:

* `deposit_awaiting` — order created. Send crypto to `depositAddress`.
* `deposit_validating` — transaction hash submitted. On-chain confirmation is pending.
* `deposit_successful` — deposit confirmed.
* `payout_pending` — USD credit is being processed.
* `payout_successful` — USD 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.

The order starts in `deposit_successful` and waits for Fonbnk admin approval.

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

If the withdrawal is rejected, or canceled 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).

### Asset selection

Call the relevant `.../options` endpoint to discover supported `(network, asset)` pairs.

Call the matching `.../limits` endpoint for the authoritative min and max values.

Unsupported pairs are rejected up front:

* `MERCHANT_BALANCE_DEPOSIT_ASSET_UNSUPPORTED`
* `MERCHANT_BALANCE_WITHDRAW_ASSET_UNSUPPORTED`


---

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