---
title: "Refill this key's wallet"
method: POST
path: "/tokens/purchase"
tags: ["Wallet"]
---

# Refill this key's wallet

`POST /tokens/purchase`

## Request

- Base URL: `https://api.getfacade.ai/api/v1`
- URL: `https://api.getfacade.ai/api/v1/tokens/purchase`
- 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`)

Available only to a key issued with purchasing enabled, and only up to what the key may
still spend (cap − spent − current balance): a purchase can never lift the key's own
spend cap. Raising the cap and enabling purchasing are human actions.

`status: charged` means the payment provider accepted the collection from a saved
payment method — not that the tokens have landed; they are credited when the payment is
confirmed, so poll `/tokens/balance`. `status: requires_human` means no saved payment
method was available: nothing was charged and `checkout_url` is for a person to open.

A human session is refused here with `AGENT_KEY_REQUIRED` — the apps have a real
checkout with card entry and 3-D Secure.

Named like every other paid call: this is the one endpoint where software starts a
charge, so a call that times out after the provider took it comes back as the same
purchase rather than a second one.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `data` object
    - `type` 'agent_token_purchase', required
    - `attributes` object, required
      - `package` string, required: Package id from /tokens/packages, e.g. "600".

## Response `202`

Purchase started

- object
  - `data` object
    - `type` 'agent_token_purchase'
    - `id` string
    - `attributes` object
      - `status` 'charged' | 'requires_human'
      - `transaction_id` string
      - `tokens` number
      - `checkout_url` string, nullable
      - `detail` string

## Other responses

- `403`: The purchase was refused before any money moved. `AGENT_PURCHASE_NOT_ALLOWED` — the key was issued without permission to buy. `AGENT_PURCHASE_EXCEEDS_CAP` — the purchase would take the key past its spend cap; `meta.headroom` says how much it may still buy. `AGENT_KEY_REQUIRED` — a human session; buy in the app instead. None is retryable: each one is unblocked by a person, not by waiting.
- `404`: The request was understood and refused. The message is the API's own text; show it unchanged. `IDEMPOTENCY_KEY_REQUIRED` — a paid call from an agent key with no `Idempotency-Key` header; nothing was queued, send it again with one. `IDEMPOTENCY_KEY_REUSED` — that header value already names a different request; a new order needs a new value.
- `429`: Rate limited on this key's own bucket, separate from the human sessions of the same account. Refusal is deliberately cheap: back off, do not retry in a tight loop.

---

[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)