> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits and limits

> Plans, rate limit, monthly credit quota, what each query costs and how to check your balance.

Every API query uses credits according to its real cost: a trace triggers dozens of reads from the data sources; a
single lookup, one. Your plan sets how many queries per minute you can make and how many credits you have per month.

## Plans

| Plan | Rate limit | Monthly quota |
| - | - | - |
| `free` | 15 queries per minute | 5,000 credits |
| `pro` | 120 queries per minute | 500,000 credits |
| `enterprise` | 1,200 queries per minute | The organization's; without one of its own, 5,000,000 credits |

* The plan is your organization's, and your keys inherit it.
* On `enterprise`, the quota belongs to **the whole organization**: the web app, its members' keys and the organization
  keys all count against the same quota and stop when it runs out.
* The quota renews on **the 1st of every month** at 00:00 UTC.

## What is charged and what is not

> [!TIP]
>
> Only successful responses (status below `400`) are charged.

* An error response (`4xx` or `5xx`) is logged with **0 credits**.
* If the data source could not read what you asked for, the response is `503 source_unavailable` and you are not
  charged.
* A `200` that carries `degraded_sources` **is** charged: the query was answered and what was missing is declared in the
  response. See [Errors](https://docs.blockgence.com/en/api/errors.md).
* `401`, `402` and `429` responses are cut off before the query runs.

## What each query costs

The cost is decided by method and path: the longest priced path prefix wins. A path without a price of its own costs
1 credit.

| Credits | Endpoints |
| - | - |
| 70 | `GET /v1/deliverable/{case_token}` (30 if the post-mortem was already built) |
| 60 | `POST /v1/triage` |
| 40 | `POST /v1/copilot`, `POST /v1/audit/{audit_id}/copilot`, `POST /v1/incident` (plus each completed step), `POST /v1/tracker`, `POST /v1/tracker/{tracker_id}/recompute`, `GET /v1/postmortem/{case_token}` (0 if it was already built in the last 24 h), `POST /v1/returns`, `GET /v1/scam/{chain}/{addr}/victims` |
| 30 | `POST /v1/compromise`, `POST /v1/evidence`, `GET /v1/freezepack/{case_token}` |
| 25 | `POST /v1/trace`, `POST /v1/tracetx`, `POST /v1/path`, `POST /v1/report`, `POST /v1/stitch`, `GET /v1/token/{chain}/{addr}`, `GET /v1/drainer/{chain}/{addr}/victims`, `GET /v1/cluster/{chain}/{addr}` (experimental) |
| 20 | `GET /v1/signature-drains/{chain}/{addr}` |
| 15 | `POST /v1/simulate`, `GET /v1/approvals-by-spender/{chain}/{spender}`, `GET /v1/decode/{chain}/{hash}`, `GET /v1/demix/{addr}` |
| 10 | `GET /v1/approvals/{chain}/{addr}`, `GET /v1/attempts/{chain}/{addr}`, `GET /v1/contract/{chain}/{addr}`, `GET /v1/holdings/{chain}/{addr}`, `GET /v1/fingerprint/{chain}` (experimental), `POST /v1/unswap`, `POST /v1/monero/proof` |
| 5 | `GET /v1/tx/{txhash}`, `GET /v1/osint/{addr}`, `GET /v1/poisoning/{chain}/{addr}`, `GET /v1/safe-harbor/{chain}/{addr}`, `GET /v1/third-party-outflows/{chain}/{addr}`, `GET /v1/monero/tx/{txid}`, `POST /v1/travel-rule/reconcile` |
| 4 | `GET /v1/enrich/{addr}`, `GET /v1/messages/{addr}`, `POST /v1/counterparties` |
| 3 | `GET /v1/screening/{addr}`, `GET /v1/security/{addr}`, `GET /v1/delegation/{addr}`, `GET /v1/issuer-status/{chain}/{addr}`, `POST /v1/travel-rule/counterparty` |
| 2 | `POST /v1/ens`, `GET /v1/probe/{addr}` |
| 1 | `GET /v1/address/{addr}`, `GET /v1/labels/{addr}`, `POST /v1/labels`, `GET /v1/funding/{addr}`, `GET /v1/attack-vectors`, `GET /v1/laundering-pulse`, `POST /v1/evidence/report.pdf` |
| 0 | `GET /v1/account`, `GET /v1/sources`, `GET /v1/sanctions/lists`, all of `/v1/chains…`, `/v1/methodology…`, `/v1/cases…`, `/v1/guard…`, `/v1/audit…` (except the copilot) and `/v1/icon/…`, `GET /v1/incident/{job_id}`, `GET /v1/tracker` and `GET /v1/tracker/{tracker_id}`, `POST /v1/travel-rule/challenge`, `POST /v1/travel-rule/ivms101/validate` |

`GET /v1/evidence/signing-key` y `GET /v1/evidence/timestamp/{name}` are open: they need no key and cost
nothing. They let anyone verify a document's signature without an account.

## Checking your balance

Every authenticated response carries these headers:

| Header | What it says |
| - | - |
| `X-Credits-Cost` | What this query cost: the endpoint's price if it succeeded, `0` if not. |
| `X-Credits-Limit` | The monthly quota in force: the plan's or, on `enterprise`, the organization's. |
| `X-Credits-Remaining` | What you have left after this query. It is a floor: if another query of yours that is still running ends in an error, it is not charged and your real balance goes up. |
| `X-Credits-Reset` | When the quota renews (epoch, UTC). |

For a per-endpoint breakdown, use `GET /v1/account` (free):

```bash Request theme={null}
curl https://app.blockgence.com/v1/account \
  -H "Authorization: Bearer $BKG_KEY"
```

```json Response theme={null}
{
  "name": "mcp:reporting server",
  "prefix": "bkg_live_ab12",
  "tier": "pro",
  "limits": { "rate_per_min": 120, "monthly_credits": 500000, "request_source_calls": 4000 },
  "credits": { "limit": 500000, "used": 28, "reserved": 0, "remaining": 499972, "reset": 1796083200, "shared": false },
  "usage": {
    "month": { "requests": 5, "credits": 28, "failed": 1 },
    "total": { "requests": 5, "credits": 28, "failed": 1 },
    "by_endpoint": [ { "endpoint": "/v1/trace", "reqs": 1, "credits": 25 } ]
  }
}
```

* `credits` is the balance, computed the same way as the headers: `reserved` is what your running queries are holding.
  On `enterprise`, `shared` is `true` when the balance is the organization's.
* `limits.request_source_calls` is the cap on reads from the data sources per query (see below).
* `failed` counts the queries that ended in an error, logged with 0 credits.

## When you hit a limit

| Status | What happened | What to do |
| - | - | - |
| `429 Too Many Requests` | You went over your plan's rate limit. | Wait the seconds given in the `Retry-After` header. |
| `402 Payment Required` | The monthly quota is used up. It counts what you used plus what your running queries have reserved, so several in parallel cannot go over the quota. | Wait for the renewal or ask for a larger quota. |

> [!NOTE]
>
> Each query also has a cap on reads from the data sources (4,000 by default; the organization can have another one).
> If a trace reaches the cap, the remaining reads are not made: the root query returns `503` or the step lands in
> `degraded_sources`, with `reason: "budget_exhausted"`. It is never an empty result.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.