Balance & history

Your xTokens balance is the internal currency for generation. Each image costs 10 xTokens by default. New accounts start at 0 — top-ups are handled by xMode staff for now (contact support).

`GET /v1/balance`

Current xTokens balance.

Returns `{ xTokens, updatedAt }`. The `updatedAt` timestamp moves only when the balance changes (debit on POST /v1/generations, credit on refund / top-up).

bash

# Request
curl https://api.xmode.ai/v1/balance \
  -H "Authorization: Bearer xm_live_<your-key>"

# 200 OK
{
  "xTokens": 950,
  "updatedAt": "2026-05-06T11:24:31.018Z"
}

`GET /v1/balance/history`

Paginated journal of every change to your balance.

Newest first. Each entry has `type` ('debit' or 'credit'), `reason` ('generation', 'refund', 'topup', 'admin_adjustment'), `amount` (always positive), `balanceAfter`, and `reference` — for generation/refund entries the reference is the `requestId`. `pageSize` defaults to 20, max 100.

bash

# Request
curl 'https://api.xmode.ai/v1/balance/history?page=1&pageSize=20' \
  -H "Authorization: Bearer xm_live_<your-key>"

# 200 OK — page-based shape (use `hasMore` for next page).
{
  "items": [
    {
      "id": "65a...",
      "type": "debit",
      "amount": 10,
      "reason": "generation",
      "reference": "req_3xN7kQ1aJpL9wDvE",
      "balanceAfter": 950,
      "createdAt": "2026-05-06T11:24:31.018Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "hasMore": false
}