/api/qmail/local/locker-pool/status
GETReport locker pool counts, locked values, and wallet balance. Status-only — does not contact RAIDA. To replenish see /api/qmail/raida/locker-pool/replenish. Handler: api_handle_qmail_locker_pool.
Description
The QMail client funds two kinds of payment with locker coins:
- Upload (storage) lockers — funded per send with the exact computed storage fee for each server stripe (size-based formula; often fractional, e.g.
0.03CC). There is no fixed-fee pre-funded upload pool of whole-CC lockers. Background replenish maintains a small-denomination float (0.1 CC / 0.01 CC coins, DN-1 / DN-2) so exact per-send funding rarely needs a deep break cascade. Zero-fee stripes (welfare or rate 0) use an all-zero locker on the wire and do not consume pool lockers. - Inbox-fee lockers — still maintained as a pool at the configured default inbox fee (decimal CC). Unchanged split-commit semantics: acquired for Tell, committed when Tell succeeds.
This endpoint reports how many pool rows are available, the configured fee defaults, locked value breakdowns, wallet balance, and a low_balance flag. All money fields are exact decimal CC JSON numbers.
Parameters
| Param | Type | Required | Description |
|---|---|---|---|
wallet_path | string | Yes | Wallet name (e.g. Default) or full path. Must exist. The Mail wallet cannot fund payments (HTTP 400, MAIL_WALLET_NOT_ALLOWED). |
Response
{
"command": "locker-pool",
"success": true,
"request_id": "…",
"upload_available": 0,
"inbox_fee_available": 38,
"upload_locker_fee_cc": 0.01,
"default_inbox_fee_cc": 10,
"locked_value": 12.5,
"locked_available_value": 10,
"locked_reserved_value": 2.5,
"locked_limbo_value": 0,
"locked_upload_value": 0.15,
"locked_inbox_fee_value": 12.35,
"wallet_balance": 114.5,
"combined_wallet_value": 127,
"low_balance": false
}| Field | Type | Description |
|---|---|---|
upload_available | int | Count of pool rows typed as upload that are currently available. Under per-send exact funding this is often low or zero between sends; prefer wallet balance + denomination float for readiness. |
inbox_fee_available | int | Inbox-fee lockers available in the pool (typically at default_inbox_fee_cc). |
upload_locker_fee_cc | number | Configured storage fee rate: decimal CC per MiB of per-server stripe (default 0.01). Field name is historical; this is not a fixed whole-CC charge per locker. |
default_inbox_fee_cc | number | Default inbox fee used when replenishing inbox-fee lockers (decimal CC). |
locked_value | number | Total value currently locked in the pool (decimal CC). |
locked_available_value | number | Locked value in AVAILABLE status. |
locked_reserved_value | number | Locked value in RESERVED status. |
locked_limbo_value | number | Locked value in limbo / recovery states. |
locked_upload_value | number | Value of lockers typed for upload funding. |
locked_inbox_fee_value | number | Value of lockers typed for inbox fees. |
wallet_balance | number | Bank + fracked wallet balance in decimal CC. |
combined_wallet_value | number | wallet_balance + total locked value. |
low_balance | bool | UI hint — true when float/pool replenish may starve. |
Errors
| HTTP | Message |
|---|---|
| 400 | Invalid wallet_path |
| 400 | Mail wallet cannot fund payments (reason: MAIL_WALLET_NOT_ALLOWED) |
| 404 | Wallet not found |
| 500 | Failed to get pool status |
Example
curl "http://localhost:8081/api/qmail/local/locker-pool/status?wallet_path=Default"Related
- /api/qmail/raida/locker-pool/replenish — Replenish inbox-fee pool and denomination float (DN-1 / DN-2).
- /api/qmail/local/inbox-fee — Look up a contact’s inbox fee.
- /api/qmail/local/can-send — Preflight whether the wallet can fund a send (storage estimate + inbox fee).