# blocklist.fyi

> Every stablecoin (USDT/USDC) freeze, on the record - across 30+ chains.
> Issuer blacklist/freeze events, at-freeze balances, multisig timelines, and
> community intelligence on frozen addresses.

## For AI agents

Use the authenticated JSON API, not HTML scraping (AI crawlers are blocked).
Base URL: https://blocklist.fyi/api/v1
Auth: send an API key as `Authorization: Bearer <key>`. A human creates one at
https://blocklist.fyi/account. Every response includes X-RateLimit-Limit / -Remaining / -Reset
headers; a 429 means slow down (honour Retry-After).
Errors are `{ "error": { "code", "message", "field"? } }` - branch on `code`.

Machine-readable spec (OpenAPI 3.1): https://blocklist.fyi/openapi.json
Human docs: https://blocklist.fyi/api-docs

## Endpoints

- GET /events - paginated freeze ledger (filters: chain, asset, status, address, from, to; cursor, limit)
- GET /events/:id - one event with its multisig timeline
- GET /addresses/:address - full freeze history for an address (across chains)
- GET /categories - valid intel category names (fetch before submitting)
- POST /intel - submit intelligence on a frozen address

Read endpoints return a `has_intel` boolean per event; the intel content
itself is not exposed via the public API.

## Submitting intel

Identify the target by `address` (resolved to its latest freeze, matched across
encodings like TRON base58 ↔ EVM hex; optionally pin a `chain`) or by exact
`event_id`. Notes are held as PENDING until a human moderator verifies them, so
include real evidence URLs. Resubmitting an identical note returns the existing
one with `duplicate: true`.

Example:

    curl -X POST https://blocklist.fyi/api/v1/intel \
      -H "Authorization: Bearer bl_live_…" \
      -H "Content-Type: application/json" \
      -d '{
        "address": "0x…",
        "entity_name": "Lazarus Group",
        "description": "Funds traced to the 2024 bridge exploit; see sources.",
        "evidence_urls": ["https://example.com/report"],
        "categories": ["exchange-hack","money-laundering"]
      }'

Fields: entity_name (4–100 chars), description (10–500 chars), evidence_urls
(1–3 http(s) URLs, required), categories (optional; unknown values dropped -
see GET /categories).