# Balance, usage, status and invoices

> Check your 7API balance, usage and model health, or create a Heleket top-up invoice using your API key.


These account endpoints use your API key and keep working at zero balance. Balance, usage and status reads are free; creating an invoice does not charge your balance.

## Balance

`GET /v1/balance`

```bash
curl https://7api.st/v1/balance -H "Authorization: Bearer $SEVENAPI_API_KEY"
```

```json
{
  "object": "balance",
  "currency": "USD",
  "balance_usd": 18.4213,
  "usage": { "windows": { "1h": { … }, "24h": { … }, "7d": { … } } },
  "model_rates": { "glm-5.3": { "price_usd_per_mtok": 0.05, "cache_read_usd_per_mtok": 0.01 } }
}
```

## Usage

`GET /v1/usage`

Rolling totals for the last hour, 24 hours and 7 days. Each window contains:

| Field | Meaning |
|---|---|
| `total_tokens` | All tokens: new input, cache writes, cached input and output |
| `input_tokens`, `output_tokens`, `cached_tokens` | The breakdown |
| `cost_usd` | Amount charged |
| `cache_savings_usd` | How much less you paid because input was cached |

A subkey sees only its own usage, and a main key's totals exclude its subkeys.

## Model status

`GET /v1/status`

Live health for every model your key can use, from the gateway's own health checks.

| Field | Meaning |
|---|---|
| `summary.up`, `degraded`, `down` | How many models are in each state |
| `models[].status` | `up`, `degraded`, `down` or `unknown` |
| `models[].availability_pct` | Recent success rate |
| `models[].avg_latency_s` | Recent average response time |

The [dashboard's Status page](https://7api.st/status) shows the same data.

## OpenAI-style billing endpoints

Some dashboards and balance widgets read OpenAI's billing endpoints. Both are available, with or without the `/v1` prefix:

- `GET /v1/dashboard/billing/credit_grants` returns `total_available`, `total_used` and `total_granted` in USD.
- `GET /v1/dashboard/billing/subscription` returns `hard_limit_usd`, which equals your balance.

## Create a Heleket invoice

`POST /v1/payments/heleket`

```bash
curl https://7api.st/v1/payments/heleket \
  -H "Authorization: Bearer $SEVENAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 5}'
```

Send `amount_usd` as a number: **5, 10, 25, 50, 100, 200, or 500**. These are the
same top-up packages and bonuses offered by the bot and website. No other body
fields are accepted. The bearer key selects the account that receives the
credit; native reseller subkeys fund their own balance. Provider-pinned and
token-capped keys cannot create wallet invoices.

The HTTP 200 response contains:

| Field | Meaning |
|---|---|
| `invoice_id` | The Heleket invoice UUID |
| `payment_url` | The HTTPS checkout URL returned by Heleket |
| `amount_usd` | The requested payment amount |
| `currency` | `USD` |
| `credit_usd` | Balance credited after payment, including the package bonus |

Repeated requests for the same account and amount reuse a pending invoice for
up to one hour. Credit is added only after the existing signed webhook and
provider confirmation verify payment. An API timeout does not mean that an
invoice was never created; retry the same request to recover it.

Invalid amounts or extra fields return `400`; invalid keys return `401`;
unsupported key types return `403`; excess requests return `429`. Provider
failures return `502` or `503`. Respect `Retry-After` when present.

## Rate limits

Read endpoints share a limit of 600 requests per minute per IP address with
`GET /v1/models`. Invoice requests allow 60 requests per minute per account,
with at most three newly created invoices per ten minutes and three pending
invoices. Reusing an existing invoice does not create another one.
