> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-staging.joytokens.ai/llms.txt.

# Usage & Billing

> Credits, tiers, response metadata, and cost control

JoyToken records tokens, Credits, model, tier, and API key attribution after successful model calls.

## What to Check

| Question                     | Where to look                                                      |
| ---------------------------- | ------------------------------------------------------------------ |
| Which model setting was used | `metadata.model`                                                   |
| How many Credits were used   | `metadata.billing.credits_used`                                    |
| Input / output tokens        | `metadata.billing.input_tokens` / `metadata.billing.output_tokens` |
| Which key created usage      | JoyToken Console logs and usage                                    |
| Which tier was used          | `metadata.tier`                                                    |

## Billing Fields

`metadata` is always an **array**. A single-model response has one entry; an orchestration response has one entry per task. Sum `billing.credits_used` across all entries for the total cost.

```json
{
  "metadata": [
    {
      "model": "auto",
      "tier": "standard",
      "billing": {
        "credits_used": "0.2288",
        "input_tokens": 54,
        "output_tokens": 545
      }
    }
  ]
}
```

Streaming appends standalone metadata events before `[DONE]`: a single-model response emits one event whose value is a single-element array, while an orchestration response emits one event per task whose value is a single object.

## Usage Attribution

Use one API key per environment and workflow:

| Workflow                | Recommended key   |
| ----------------------- | ----------------- |
| Local development       | `dev-chat-api`    |
| Integration API         | `integration-api` |
| OpenClaw / Hermes / IDE | `agent-key`       |
| Background job          | `worker-summary`  |

## Cost Control

| Goal                   | Setup                                   |
| ---------------------- | --------------------------------------- |
| Avoid test overspend   | Small budget for test keys              |
| Control agent cost     | Separate key and budget for Agent / IDE |
| Lower default cost     | `model: "auto"` + `tier: "economy"`     |
| Stable experiment cost | Fixed tier or key budget                |
| Debug one request      | Send `X-Request-ID` on server requests  |

## Balance and Budget

`402 insufficient_quota` usually comes from the main wallet balance or the key budget. Check in this order:

1. Personal or organization main wallet balance.
2. Daily / weekly budget on the API key.
3. If routing returns no candidate, check tier, policy, wallet, and key budget.