---
title: "Wallet, key cap and admission"
method: GET
path: "/tokens/balance"
tags: ["Wallet"]
---

# Wallet, key cap and admission

`GET /tokens/balance`

## Request

- Base URL: `https://api.getfacade.ai/api/v1`
- URL: `https://api.getfacade.ai/api/v1/tokens/balance`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.getfacade.ai/oauth/authorize`, token URL `https://api.getfacade.ai/oauth/token`, scopes: `agent`)

Called with an agent key, the document carries an extra `agent` block: the `api`-scope
balance, the cap of this key, and `is_admissible` — the server's own answer to "will the
next paid call be accepted". Read that flag instead of comparing the numbers yourself.
On a human session the `agent` key is absent from `attributes` altogether, not `null`.

## Response `200`

Balance

- object
  - `data` object
    - `type` string
    - `id` string
    - `attributes` object
      - `current_balance` number: The app wallet, not the agent one
      - `is_negative` boolean: Server-authoritative debt flag; never re-derive it from the number.
      - `agent` AgentWallet
        - `scope` 'api'
        - `balance` number
        - `key` object
          - `id` string
          - `label` string, nullable
          - `spend_cap` number
          - `spent` number
          - `remaining` number
          - `is_exhausted` boolean
        - `is_admissible` boolean: Mirrors the admission middleware exactly — room on the key AND an eligible account.

## Other responses

- `401`: The key is missing, revoked or expired. Re-issuing a key is a human action.

---

[API](https://skmtc.dev/getfacade/apis/getfacade-agent-api.md) · [All operations](https://skmtc.dev/getfacade/apis/getfacade-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getfacade/apis/getfacade-agent-api/revisions/2b52eda7362c?raw)