# Wallet

> GET /v1/wallet returns the account's balance, reserved and available credits; GET /v1/wallet/transactions lists charges and top-ups.

Credits belong to your account; every key of the account sees the same wallet.

## GET /v1/wallet

```sh
curl https://api.md.tlelabs.com/v1/wallet -H "Authorization: Bearer <YOUR_API_KEY>"
```

```json
{
  "account_id": "acc_xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "balance": 9984,
  "reserved": 30,
  "available": 9954,
  "lifetime_charged": 1247,
  "key_prefix": "mdw_live_xxxx",
  "created_at": "2026-05-01T03:14:15Z"
}
```

| Field              | Meaning                                           |
| ------------------ | ------------------------------------------------- |
| `balance`          | Credits in the wallet.                            |
| `reserved`         | Credits held by conversions in progress.          |
| `available`        | `balance − reserved`: what a new request can use. |
| `lifetime_charged` | Total credits charged so far.                     |
| `key_prefix`       | Prefix of the key that made the request.          |
| `created_at`       | When the wallet was created.                      |

## GET /v1/wallet/transactions

Charges and top-ups, newest first.

```sh
curl "https://api.md.tlelabs.com/v1/wallet/transactions?limit=50" -H "Authorization: Bearer <YOUR_API_KEY>"
```

Query parameters:

- `limit`: 1–200, default 50.
- `cursor`: the `next_cursor` of the previous page. It is opaque: pass it back unchanged.

A value out of range, not an integer, or a damaged cursor gets `400 invalid_request`.

```json
{
  "transactions": [
    {
      "id": "txn_01H…",
      "type": "convert",
      "amount": -16,
      "balance_after": 9984,
      "created_at": "2026-06-16T10:23:11Z",
      "request_id": "req_01H…",
      "details": { "format": "pdf", "pages": 10, "ocr_pages": 3 }
    },
    { "id": "txn_01G…", "type": "topup", "amount": 10000, "balance_after": 10000, "created_at": "2026-05-01T03:14:15Z" }
  ],
  "next_cursor": "eyJ…"
}
```

- `type` is `convert` (negative `amount`) or `topup` (positive). `details` exists only on `convert`.
- `next_cursor` is `null` on the last page.
- Failed conversions create no transaction. Use `request_id` to check whether a request was charged (see the `503` case in [Errors](https://md.tlelabs.com/docs/errors/)).

## Adding credits

Credits are added by the operator; there is no self-serve payment. Write to <md@tlelabs.com>. The dashboard shows the same wallet and transactions under [Billing](https://md.tlelabs.com/billing).