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

# Wallet

> How your wallet is funded, how you allocate from it to your customers' accounts, and what its four figures mean.

Your wallet holds the money you've paid in to fund your customers' accounts. You move money from it to one account at a time with an allocation.

## How your wallet is funded

1. You pay the funds in, as agreed with us.
2. When the funds are confirmed as received, we credit your wallet. There's no API call for this step.
3. The credit appears in `credited_kobo` and `available_kobo` on `GET /v1/wallet`.

Each bank transfer is credited once, however often it's reported to us.

## Allocate to an account

`POST /v1/allocations` moves an amount from your wallet to one of your accounts at the broker. It needs an [`Idempotency-Key`](/idempotency).

```json Request body theme={"dark"}
{
  "account": "1000000001",
  "amount_kobo": 5000000
}
```

We check your wallet and reserve the amount in one step, so two allocations can never both spend the same money. Then we send the allocation to the broker once.

| Allocation state | Your wallet                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `booked`         | The broker booked the amount into the account's balance. It moves from reserved to allocated.                                                                             |
| `uncertain`      | We don't know whether the broker booked it. The amount stays reserved, and our operators settle it with the broker. See [Handling uncertain orders](/handling-uncertain). |
| `rejected`       | The broker rejected it, and `reject_reason` says why. The amount returns to available.                                                                                    |
| `refused`        | It never reached the broker. The amount returns to available.                                                                                                             |

If your wallet doesn't hold the amount, you get `422 wallet_too_low` and nothing is stored. One allocation can be at most ₦100,000,000, and your allocations each day are capped too. See [Limits](/limits).

## The four figures

`GET /v1/wallet` returns four figures, all read from your wallet's ledger at the same moment:

| Field            | Meaning                                                          |
| ---------------- | ---------------------------------------------------------------- |
| `credited_kobo`  | Everything credited to your wallet from your confirmed payments. |
| `allocated_kobo` | Everything booked into your accounts at the broker.              |
| `reserved_kobo`  | Allocations we've sent that aren't yet confirmed as booked.      |
| `available_kobo` | What you can allocate now.                                       |

This always holds:

`available_kobo` = `credited_kobo` minus `allocated_kobo` minus `reserved_kobo`

```json Example theme={"dark"}
{
  "object": "wallet",
  "credited_kobo": 100000000,
  "allocated_kobo": 5000000,
  "reserved_kobo": 0,
  "available_kobo": 95000000
}
```

The ledger behind these figures is append-only. Credits, reserves, bookings and returns are added as new entries, and nothing is ever changed or deleted.

## Your wallet and an account's balance

Your wallet is ours: we keep its ledger. An account's balance is the broker's: `GET /v1/accounts/{account}/balance` returns it as the broker reports it. After an allocation is booked, the amount shows in the account's balance, and trades and charges then move that balance at the broker.

The API doesn't offer withdrawals from your wallet or from an account.