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

# Wallets

> Accounts that hold money, for your business and your customers.

A wallet holds money and has its own account number. Your business can hold its own wallets, and give each customer one.

Needs the `WALLETS` feature and `wallets:write`.

## Create a wallet

```bash A customer's wallet theme={null}
curl https://$MESH_HOST/v1/wallets \
  -H "X-Api-Key: $MESH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "0b7e…" }'
```

```bash One of your business's own theme={null}
curl https://$MESH_HOST/v1/wallets \
  -H "X-Api-Key: $MESH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Lekki branch" }'
```

```json theme={null}
{
  "id": "…",
  "account_number": "6037000022",
  "account_name": "Ada Chioma Obi",
  "name_status": "pending",
  "purpose": "customer",
  "owner_type": "customer",
  "customer_id": "0b7e…",
  "status": "active",
  "tier": "tier_1",
  "limits": { "max_single_txn_minor": 5000000, "max_balance_minor": 30000000 },
  "received_minor": 0,
  "product": "wallet",
  "created_at": "…"
}
```

* **One wallet per customer.** Another is `409` (code `46`).
* **The customer must be active and registered with the bank.** An unknown customer is `404` (code `50`); one still being registered is `409` (code `62`).
* **An open business's customer needs tier 1 or above.** Below it, `422` (code `66`): verify them first. A closed-loop business's customers have no tier minimum.
* `product` is `wallet` on every wallet, so a business with both products can tell its accounts apart.

## Balances and history

Read any account by its number:

| | |
| - | - |
| `GET /v1/accounts/{accountNumber}/balance` | The balance, and any restriction in force |
| `GET /v1/accounts/{accountNumber}/transactions` | The account's transactions, newest first, with the balance after each |
| `GET /v1/accounts/{accountNumber}/limits` | The tier's limits and any override the bank set |

A balance may carry a `restriction`. `PND` means money can come in but nothing can leave; `reason: kyc_tier_limit` means an inflow took the customer past their tier, and verifying them to a higher tier lifts it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.