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

# Wallet limits

> Cap what a wallet can spend and hold, enforced by the ledger whichever key moves the money.

A limit you set on a wallet is checked by PanoQore on every debit, pending debit and hold on that wallet. It holds whichever of your services or keys moves the money, so none of them can go around it. Use it for KYC tiers, per-customer spending caps, or anything else you promise your regulator or your customers.

## Set limits

Setting limits needs the `limits:write` scope. A key that moves money (`entries:write`, `holds:write`) cannot raise its own limits, so give `limits:write` only to the service that decides them, such as your compliance or onboarding service.

```bash theme={null}
curl -X PUT https://api.panoqore.com/v1/accounts/acc_01M6F1CJAPF7Q9SFKR49QYM6CJ/limits \
  -H "Authorization: Bearer $PANOQORE_API_KEY" \
  -H "Idempotency-Key: tier1-acc_01M6F1CJ" \
  -d '{
    "maxPerDebit": "5000000",
    "maxPerDay": "5000000",
    "maxPerMonth": "50000000",
    "maxBalance": "30000000"
  }'
```

Amounts are in minor units (kobo for NGN). Every field is optional, and a field you leave out is no limit: each call replaces the wallet's limits, so send `{}` to remove them all. Limits take effect at once, with no approval, and apply only to wallets.

| Limit | Refuses |
| - | - |
| `maxPerDebit` | One debit or hold larger than this. |
| `maxPerDay` | Spending past this on one business day. |
| `maxPerMonth` | Spending past this in one calendar month of business days. |
| `maxBalance` | A credit that would take the balance above this. |

## What counts as spending

* A posted debit, and a pending debit, counts on its business date.
* A hold counts when it is placed. Capturing it does not count again, and releasing it or letting it expire gives back what was not captured.
* Voiding a pending entry gives back what it had counted.
* Reversals and adjustments approved in the console never count, and are never refused by a limit, so a mistake can always be undone.

Spending is counted for every wallet, limits or not, so a limit you set at noon already sees the morning.

## Reading what is left

`GET /v1/accounts/{id}` on a wallet shows its limits and what it has used:

```json theme={null}
"limits": {
  "maxPerDay": "5000000",
  "maxBalance": "30000000",
  "spentToday": "1250000",
  "spentThisMonth": "8400000",
  "updatedBy": "key_compliance",
  "updatedAt": "2026-11-06T09:12:44Z"
}
```

## When a limit is reached

A debit, hold or posted credit that would go over a limit is refused with `LIMIT_EXCEEDED`, and nothing moves. `details` says which limit (`limit`), its value (`max`), what was already used (`used`), what is left (`remaining`) and the amount asked for.

Money that arrives from the bank cannot be refused, because it has already arrived. A credit to a [named account](https://docs.panoqore.com/guides/named-accounts.md) that would take the wallet over `maxBalance` goes to the partner's suspense account instead. The credit reports `QUARANTINED`, with the reason "The wallet's balance limit would be exceeded.", and you return it to the sender.


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