{"openapi":"3.1.0","info":{"title":"blocklist.fyi API","version":"1.0.0","description":"Read stablecoin (USDT/USDC) freeze events across chains and submit community intelligence on frozen addresses. Authenticate with an API key as a bearer token. Submitted intel is held as PENDING until a moderator verifies it. Every response carries X-RateLimit-* headers."},"servers":[{"url":"https://blocklist.fyi/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/events":{"get":{"summary":"List freeze events","description":"Paginated freeze ledger, newest first by default. Use the opaque `cursor` for the next page.","parameters":[{"name":"chain","in":"query","schema":{"type":"string","enum":["ETHEREUM","TRON","SOLANA","AVALANCHE","KAIA","CELO","APTOS","TON","NEAR","KAVA","TEZOS","POLKADOT_ASSET_HUB","LIQUID","ARBITRUM","POLYGON_POS","LINEA","SONIC","UNICHAIN","WORLD_CHAIN","BASE","OP_MAINNET","ZKSYNC_ERA","SEI","HYPEREVM","INK","MORPH","PLUME","ALGORAND","STELLAR","XRPL","HEDERA","SUI","STARKNET","NOBLE","INJECTIVE","BSC","MONAD","MANTLE","XLAYER","AB_CORE"]}},{"name":"asset","in":"query","schema":{"type":"string","enum":["USDT","USDC","USD1"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["BLACKLISTED","UNBLACKLISTED","PENDING","DESTROYED"]}},{"name":"address","in":"query","description":"Partial, case-insensitive match.","schema":{"type":"string"}},{"name":"from","in":"query","description":"ISO date/datetime lower bound.","schema":{"type":"string"}},{"name":"to","in":"query","description":"ISO date/datetime upper bound.","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Rows per page; capped at your tier's row limit.","schema":{"type":"integer","default":25}},{"name":"sort","in":"query","schema":{"type":"string","enum":["date","balance"],"default":"date"}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"A page of events.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}":{"get":{"summary":"Get one event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The event, with its multisig timeline.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventDetail"}}}},"404":{"description":"No event with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/addresses/{address}":{"get":{"summary":"Freeze history for an address","description":"All freeze events for one address across every chain. An empty `events` array means it has never been frozen.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The address and its events.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}}}}},"/categories":{"get":{"summary":"List valid intel categories","description":"Fetch before submitting; unknown categories are silently dropped.","responses":{"200":{"description":"The category names.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string","enum":["scam","exchange-hack","fraud","phishing-drainer","ransomware","sanctions","darknet-market","money-laundering","theft","iran","north-korea","terrorism","russia","drugs-trafficking","cyber","court-order","kidnapping"]}}}}}}}}}},"/intel":{"post":{"summary":"Submit intelligence on a frozen address","description":"Attach a note to a freeze. Identify the target by `address` (resolved to its latest freeze, matched across encodings like TRON base58 ↔ EVM hex; optionally pin a `chain`) or by an exact `event_id`. The note is held as PENDING until a moderator verifies it. Resubmitting an identical note returns the existing one with `duplicate: true`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelSubmission"}}}},"responses":{"200":{"description":"Duplicate - the matching existing note is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelResult"}}}},"201":{"description":"Note created (PENDING review).","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelResult"}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching event or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/intel/flows":{"post":{"summary":"Report on-chain links between blacklisted addresses","description":"Report directed stablecoin transfers between `address` and other blacklisted addresses (`direction`: `in` = received from the counterparty, `out` = sent to it). Powers the 'received from / sent to other blacklisted addresses' indicator on address pages. Idempotent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","chain","flows"],"properties":{"address":{"type":"string"},"chain":{"type":"string","enum":["ETHEREUM","TRON","SOLANA","AVALANCHE","KAIA","CELO","APTOS","TON","NEAR","KAVA","TEZOS","POLKADOT_ASSET_HUB","LIQUID","ARBITRUM","POLYGON_POS","LINEA","SONIC","UNICHAIN","WORLD_CHAIN","BASE","OP_MAINNET","ZKSYNC_ERA","SEI","HYPEREVM","INK","MORPH","PLUME","ALGORAND","STELLAR","XRPL","HEDERA","SUI","STARKNET","NOBLE","INJECTIVE","BSC","MONAD","MANTLE","XLAYER","AB_CORE"]},"entity":{"type":"string","description":"Best-known attribution of `address` (optional)."},"flows":{"type":"array","items":{"type":"object","required":["counterparty","direction"],"properties":{"counterparty":{"type":"string"},"direction":{"type":"string","enum":["in","out"]},"token":{"type":"string"},"tx_hash":{"type":"string"},"counterparty_entity":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Reported.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the window resets."}},"content":{"application/json":{"schema":{"type":"object","properties":{"reported":{"type":"integer"},"added":{"type":"integer"}}}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key created at /account, e.g. `bl_live_…`."}},"schemas":{"Event":{"type":"object","description":"A freeze event. `has_intel` is true when verified intel exists; `intel_confidence` is the highest confidence among verified notes (HIGH/MEDIUM/LOW, null when none). The intel content itself is not returned by the public API.","additionalProperties":true,"properties":{"id":{"type":"string"},"address":{"type":"string"},"chain":{"type":"string","enum":["ETHEREUM","TRON","SOLANA","AVALANCHE","KAIA","CELO","APTOS","TON","NEAR","KAVA","TEZOS","POLKADOT_ASSET_HUB","LIQUID","ARBITRUM","POLYGON_POS","LINEA","SONIC","UNICHAIN","WORLD_CHAIN","BASE","OP_MAINNET","ZKSYNC_ERA","SEI","HYPEREVM","INK","MORPH","PLUME","ALGORAND","STELLAR","XRPL","HEDERA","SUI","STARKNET","NOBLE","INJECTIVE","BSC","MONAD","MANTLE","XLAYER","AB_CORE"]},"asset":{"type":"string","enum":["USDT","USDC","USD1"]},"event_type":{"type":"string","enum":["BLACKLISTED","UNBLACKLISTED","PENDING","DESTROYED"]},"tx_hash":{"type":"string"},"usdt_balance":{"type":"string","description":"At-freeze balance (string for precision)."},"block_number":{"type":["integer","null"]},"event_timestamp":{"type":"string","format":"date-time"},"has_intel":{"type":"boolean"},"intel_confidence":{"type":["string","null"],"enum":["HIGH","MEDIUM","LOW",null]}}},"EventDetail":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"multisig_steps":{"type":"array","items":{"type":"object","properties":{"step_type":{"type":"string"},"tx_hash":{"type":"string"},"signer_address":{"type":["string","null"]},"step_timestamp":{"type":"string","format":"date-time"}}}}}}]},"IntelSubmission":{"type":"object","required":["entity_name","description","evidence_urls"],"properties":{"address":{"type":"string","description":"Target address; resolved to its latest freeze. Provide this or event_id."},"chain":{"type":"string","enum":["ETHEREUM","TRON","SOLANA","AVALANCHE","KAIA","CELO","APTOS","TON","NEAR","KAVA","TEZOS","POLKADOT_ASSET_HUB","LIQUID","ARBITRUM","POLYGON_POS","LINEA","SONIC","UNICHAIN","WORLD_CHAIN","BASE","OP_MAINNET","ZKSYNC_ERA","SEI","HYPEREVM","INK","MORPH","PLUME","ALGORAND","STELLAR","XRPL","HEDERA","SUI","STARKNET","NOBLE","INJECTIVE","BSC","MONAD","MANTLE","XLAYER","AB_CORE"],"description":"Optional: pin address resolution to one chain."},"event_id":{"type":"string","description":"Exact event id; alternative to address."},"entity_name":{"type":"string","minLength":4,"maxLength":100,"description":"Who owns/controls the address."},"description":{"type":"string","minLength":10,"maxLength":500,"description":"Reason / context."},"evidence_urls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":3,"description":"1–3 http(s) source URLs."},"categories":{"type":"array","items":{"type":"string","enum":["scam","exchange-hack","fraud","phishing-drainer","ransomware","sanctions","darknet-market","money-laundering","theft","iran","north-korea","terrorism","russia","drugs-trafficking","cyber","court-order","kidnapping"]},"description":"Optional; unknown values dropped."}}},"IntelResult":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","VERIFIED","REJECTED"]},"duplicate":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine code, e.g. validation_error, event_not_found, rate_limited."},"message":{"type":"string"},"field":{"type":"string","description":"The offending field, when applicable."}},"required":["code","message"]}}}}}}