# Credits & pricing

Onekey charges in credits. Every endpoint has a flat price you can see before you call it. No monthly minimums, and credits never expire.

## Price points

Endpoints cost 1 to 8 credits. Most are 1, 2 or 5.

| Price | Cost | Typical endpoints |
| --- | --- | --- |
| **Standard** | 1 credit | Simple lookups on open platforms, such as a profile or a package. |
| **Advanced** | 2, 3 or 5 credits | Lists and searches that need a paid data route, and hard-to-reach platforms. Searches on open platforms are often 1. |
| **Other** | 6 or 8 credits | A few endpoints with their own price when the work does not fit either. |

The exact price is always on the endpoint page and in the [catalog](https://onekey.dev/docs/platforms.md).

## When you are charged, and when you are not

| Situation | Cost |
| --- | --- |
| Fresh fetch that succeeds | The endpoint price. |
| Answer served from cache (fresh or stale) | **Free.** (A cached response over 100 KB costs 0.2 credit, never more than the endpoint price.) |
| Record not found (`404`) | **Free** (reserved, then refunded). |
| Source failed or timed out (`502`) | **Free** (refunded). |
| Invalid parameters (`422`) | **Free** (rejected before any charge). |
| Bad key (`401`), rate limited (`429`) | **Free**. |
| An empty list from a search that succeeded | The endpoint price. It is a real answer. |
| Each further page of a list (`cursor`) | The endpoint price per page (see [Pagination](https://onekey.dev/docs/pagination.md)). |
| A replay for an `Idempotency-Key` you already used | **Free** (see [Idempotency](https://onekey.dev/docs/idempotency.md)). |

> [!NOTE] Your balance is checked first: a call you cannot afford returns `402 INSUFFICIENT_CREDITS` and nothing is charged. A key that has reached its own [credit limit](https://onekey.dev/docs/key-limits.md) returns `402 KEY_BUDGET_EXCEEDED` instead, and your other keys keep working.

Every response tells you what it cost in `metadata.credits_charged`. Check your balance any time, free, with `GET /v1/account` (or `GET /v1/credits/balance`). After a call that charged something, the `X-Credits-Remaining` header carries the new balance (see [Rate limits & headers](https://onekey.dev/docs/rate-limits.md)).

## Your credit ledger

`GET /v1/credits/transactions` returns every movement on your account's credits, newest first, with the balance after each row. It needs an API key, costs nothing, and counts as an ordinary request for the rate limit. Credits belong to the account, so every key of the account sees the same ledger; `key_id` says which key a spend came from.

```bash
curl "https://api.onekey.dev/v1/credits/transactions?limit=3" -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "success": true,
  "data": [
    { "id": 412, "type": "settle", "credits": 0, "balance_after": 997, "description": "Unused part of a hold returned after a call", "ref": "9b1e...", "key_id": "key_abc", "created_at": "2026-10-02T09:15:01+00:00" },
    { "id": 411, "type": "reserve", "credits": -3, "balance_after": 997, "description": "Credits held while a request runs", "ref": "9b1e...", "key_id": "key_abc", "created_at": "2026-10-02T09:15:00+00:00" },
    { "id": 1, "type": "grant", "credits": 1000, "balance_after": 1000, "description": "Credits added (signup grant, pack purchase)", "ref": "signup", "key_id": null, "created_at": "2026-10-01T08:00:00+00:00" }
  ],
  "pagination": { "next_cursor": "eyJ2Ijox...", "has_more": true, "page_size": 3 }
}
```

A call is usually two rows: a **reserve** (the worst-case price is held) and then a **settle** or **refund** that hands back whatever was not kept, so the net of the pair is what the call cost. Types: `grant` (credits added), `reserve`, `topup` (a bigger hold), `settle`, `refund`, `charge`, `hit` (a charged cache hit) and `clawback` (a refunded or disputed payment). `credits` is signed: spends are negative.

| Parameter | Meaning |
| --- | --- |
| `limit` | Rows per page, 1 to 100 (default 50). |
| `cursor` | `pagination.next_cursor` from the previous page, sent back untouched with the same filters. |
| `type` | Comma list of the types above. |
| `key_id` | Only spend attributed to this key. |
| `from`, `to` | ISO 8601 bounds (`from` inclusive, `to` exclusive). |

For one row per call with its endpoint and result, use the request log in the dashboard.

## Credits never expire

What you buy stays until you use it. 1,000 free credits cover the open-platform endpoints. Hard-to-reach platforms (X, TikTok, Instagram, Reddit, and others marked on their page) need a verified email and a purchased pack. Buy more in packs on the [pricing page](https://onekey.dev/pricing).

## Cost examples

- 100 profile lookups of different people: 100 x 1 = **100 credits**.
- The same profile 100 times within its fresh window: 1 fresh fetch + 99 free cache hits = **1 credit**.
- 10 searches: 10 x 5 = **50 credits**.

## Capping what a key can spend

Give any key a credit limit in the [dashboard](https://onekey.dev/dashboard/keys). Every charge the key makes counts toward it and refunds are given back; when it is reached that key gets `402 KEY_BUDGET_EXCEEDED` and nothing else changes. See [Per-key credit limits](https://onekey.dev/docs/key-limits.md).

## Empty results

A search that succeeds but finds nothing is a real answer and costs the endpoint price; only failures and not-found records are refunded (see the table above and [Refunds](https://onekey.dev/refunds)).