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

# 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

<ParamField path="id" type="string" required>
  The UUID of the wallet to summarise.
</ParamField>

### 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.

<ResponseField name="balance" type="integer">
  Current available balance in **kobo**. This is the live spendable balance after all approved
  debits and top-ups have been applied.
</ResponseField>

<ResponseField name="spendLimitPerTx" type="integer">
  Per-transaction spend cap, in kobo. Included for convenience so dashboards can display the
  limit without a separate wallet-fetch call.
</ResponseField>

<ResponseField name="spendLimitPeriod" type="integer">
  Rolling-period cumulative spend cap, in kobo.
</ResponseField>

<ResponseField name="spentThisPeriod" type="integer">
  Total amount spent within the current rolling `periodWindowDays` window, in **kobo**. Compare
  against `spendLimitPeriod` to render a spend-budget progress bar.
</ResponseField>

<ResponseField name="remainingAllowance" type="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.
</ResponseField>

#### Example Response

```json theme={null}
{
  "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

<ParamField path="id" type="string" required>
  The UUID of the wallet.
</ParamField>

### Query Parameters

<ParamField query="limit" type="integer" default="20">
  Maximum number of recent transactions to return. Capped at `100`.
</ParamField>

### Response `200 OK`

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

<ResponseField name="[]" type="object[]">
  Array of the most recent transaction records.

  <Expandable title="transaction fields">
    <ResponseField name="[].amount" type="integer">
      Transaction amount in kobo.
    </ResponseField>

    <ResponseField name="[].merchant" type="string">
      Merchant identifier at the point of authorisation.
    </ResponseField>

    <ResponseField name="[].decision" type="string">
      `"approved"` or `"blocked"`.
    </ResponseField>

    <ResponseField name="[].reason" type="string | null">
      Human-readable reason for the decision outcome, or `null` when not applicable.
    </ResponseField>

    <ResponseField name="[].createdAt" type="string">
      ISO 8601 timestamp of the authorisation attempt.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example Response

```json theme={null}
[
  {
    "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"
  }
]
```

<Tip>
  **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.
</Tip>

***

## 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`. |

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