> ## 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.

# Créditos y límites

> Planes, rate limit, cupo mensual de créditos, cuánto cuesta cada consulta y cómo ver tu saldo.

Cada consulta a la API consume créditos según su costo real: un rastreo dispara decenas de lecturas a las fuentes de
datos; una consulta puntual, una. Tu plan fija cuántas consultas por minuto podés hacer y cuántos créditos tenés por
mes.

## Planes

| Plan | Rate limit | Cupo mensual |
| - | - | - |
| `free` | 15 consultas por minuto | 5,000 créditos |
| `pro` | 120 consultas por minuto | 500,000 créditos |
| `enterprise` | 1,200 consultas por minuto | El de la organización; sin uno propio, 5,000,000 créditos |

* El plan es el de tu organización, y tus claves lo heredan.
* En `enterprise`, el cupo es de **toda la organización**: la web, las claves de sus miembros y las claves de la
  organización suman al mismo cupo y se cortan al llegar.
* El cupo se renueva el **1 de cada mes** a las 00:00 UTC.

## Lo que se cobra y lo que no

> [!TIP]
>
> Solo se cobran las respuestas exitosas (status menor a `400`).

* Una respuesta de error (`4xx` o `5xx`) queda registrada con **0 créditos**.
* Si la fuente de datos no pudo leer lo que pediste, la respuesta es `503 source_unavailable` y no se cobra.
* Un `200` que trae `degraded_sources` **sí** se cobra: la consulta se respondió y lo que faltó está declarado en la
  respuesta. Ver [Errores](https://docs.blockgence.com/es/api/errors.md).
* Las respuestas `401`, `402` y `429` se cortan antes de ejecutar la consulta.

## Cuánto cuesta cada consulta

El costo se decide por método y ruta: vale el prefijo de ruta más largo que tenga precio. Una ruta sin precio propio
cuesta 1 crédito.

| Créditos | Endpoints |
| - | - |
| 70 | `GET /v1/deliverable/{case_token}` (30 si el post-mortem ya estaba armado) |
| 60 | `POST /v1/triage` |
| 40 | `POST /v1/copilot`, `POST /v1/audit/{audit_id}/copilot`, `POST /v1/incident` (más cada paso completado), `POST /v1/tracker`, `POST /v1/tracker/{tracker_id}/recompute`, `GET /v1/postmortem/{case_token}` (0 si ya estaba armado en las últimas 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`, todo `/v1/chains…`, `/v1/methodology…`, `/v1/cases…`, `/v1/guard…`, `/v1/audit…` (salvo el copiloto) y `/v1/icon/…`, `GET /v1/incident/{job_id}`, `GET /v1/tracker` y `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}` son abiertos: no piden clave ni cobran. Sirven para
verificar la firma de un documento sin depender de una cuenta.

## Ver tu saldo

Cada respuesta autenticada trae estos headers:

| Header | Qué dice |
| - | - |
| `X-Credits-Cost` | Lo que costó esta consulta: el precio del endpoint si salió bien, `0` si no. |
| `X-Credits-Limit` | El cupo mensual que rige: el del plan o, en `enterprise`, el de la organización. |
| `X-Credits-Remaining` | Lo que te queda después de esta consulta. Es un piso: si otra consulta tuya en curso termina en error, no se cobra y el saldo real sube. |
| `X-Credits-Reset` | Cuándo se renueva el cupo (epoch, UTC). |

Para el detalle por endpoint, `GET /v1/account` (sin costo):

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

```json Respuesta theme={null}
{
  "name": "mcp:servidor de reportes",
  "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` es el saldo con la misma cuenta que los headers: `reserved` son los créditos que tienen tomados tus
  consultas en curso. En `enterprise`, `shared` es `true` cuando el saldo es el de la organización.
* `limits.request_source_calls` es el tope de lecturas a las fuentes por consulta (ver abajo).
* `failed` cuenta las consultas que terminaron en error, registradas con 0 créditos.

## Cuando llegás a un límite

| Status | Qué pasó | Qué hacer |
| - | - | - |
| `429 Too Many Requests` | Superaste el rate limit de tu plan. | Esperá los segundos que dice el header `Retry-After`. |
| `402 Payment Required` | Se agotó el cupo mensual. Cuenta lo consumido más lo que tus consultas en curso tienen reservado, así varias en paralelo no se pasan del cupo. | Esperá a la renovación o pedí más cupo. |

> [!NOTE]
>
> Además, cada consulta tiene un tope de lecturas a las fuentes de datos (por defecto, 4,000; la organización puede
> tener otro). Si un rastreo llega al tope, las lecturas que faltan no se hacen: la consulta raíz responde `503` o el
> paso queda en `degraded_sources`, con `reason: "budget_exhausted"`. Nunca es un resultado vacío.


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