GET /v1/wallets/:id/stats — wallet spending summary

Retrieve a real-time snapshot of a wallet’s balance, spend limits, and rolling-period usage. Pair with the transactions endpoint for a live agent dashboard.

Two lightweight read endpoints for building live agent dashboards. Poll /stats to show a real-time snapshot of the wallet’s balance and remaining spend allowance, and /transactions when you need a compact recent-activity feed alongside it.

Endpoints

Method	Path	Purpose
GET	/v1/wallets/:id/stats	Aggregated spending statistics for the wallet
GET	/v1/wallets/:id/transactions	Recent transactions, newest first

Authentication

Both endpoints require a valid Session JWT in the Authorization header.

Authorization: Bearer <session_jwt>

---

GET /v1/wallets/:id/stats

Path Parameters

id · string · required

The UUID of the wallet to summarise.

Response 200 OK

The response is a flat object containing the wallet’s current balance, configured spend limits, and how much has been spent in the current rolling period.

balance · integer

Current available balance in kobo. This is the live spendable balance after all approved debits and top-ups have been applied.

spendLimitPerTx · integer

Per-transaction spend cap, in kobo. Included for convenience so dashboards can display the limit without a separate wallet-fetch call.

spendLimitPeriod · integer

Rolling-period cumulative spend cap, in kobo.

spentThisPeriod · integer

Total amount spent within the current rolling periodWindowDays window, in kobo. Compare against spendLimitPeriod to render a spend-budget progress bar.

remainingAllowance · integer

Remaining spend capacity for the current rolling period, in kobo. Calculated as spendLimitPeriod − spentThisPeriod. Use this value to determine how much the agent can still spend before hitting its period cap.

Example Response

{
  "balance": 1000000,
  "spendLimitPerTx": 500000,
  "spendLimitPeriod": 2000000,
  "spentThisPeriod": 500000,
  "remainingAllowance": 1500000
}

---

GET /v1/wallets/:id/transactions

A trimmed-down version of the full transactions endpoint, optimised for dashboard widgets. Returns only the most recent N transactions — no deep pagination required.

Path Parameters

id · string · required

The UUID of the wallet.

Query Parameters

limit · integer · default: "20"

Maximum number of recent transactions to return. Capped at 100.

Response 200 OK

Returns an array of recent transaction records, sorted newest-first.

[] · object[]

Array of the most recent transaction records.

Show transaction fields

[].amount · integer

Transaction amount in kobo.

[].merchant · string

Merchant identifier at the point of authorisation.

[].decision · string

"approved" or "blocked".

[].reason · string | null

Human-readable reason for the decision outcome, or null when not applicable.

[].createdAt · string

ISO 8601 timestamp of the authorisation attempt.

Example Response

[
  {
    "amount": 345000,
    "merchant": "AWS",
    "decision": "approved",
    "reason": null,
    "createdAt": "2025-07-15T11:03:44Z"
  },
  {
    "amount": 750000,
    "merchant": "Rackspace",
    "decision": "blocked",
    "reason": "merchant_not_in_allowlist",
    "createdAt": "2025-07-15T10:58:17Z"
  },
  {
    "amount": 120000,
    "merchant": "Vercel",
    "decision": "approved",
    "reason": null,
    "createdAt": "2025-07-14T16:45:22Z"
  }
]

Best endpoint for a live dashboard. Poll GET /v1/wallets/:id/stats every 1–2 seconds to keep the balance and remaining allowance up to date without over-fetching. Pair it with a single call to /transactions?limit=5 on page load for the recent-activity feed, then refresh it on a slower interval (every 10–30 seconds) — transaction lists change less frequently than the balance.

---

Error Responses

Both endpoints return the same error shapes:

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid Session JWT.
404	WALLET_NOT_FOUND	No wallet exists with the supplied :id.

{
  "error": {
    "code": "WALLET_NOT_FOUND",
    "message": "No wallet found with ID wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321."
  }
}