{ "openapi": "3.1.1", "info": { "title": "Stablecoin Flow Explorer API", "version": "1.0.0", "summary": "USDC/USDT supply per chain, recent mints, burns and whale transfers, cross-chain totals.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://stablecoinflowexplorer.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "USDC/USDT supply per chain, recent mints, burns and whale transfers, cross-chain totals.", "description": "Reads USDC or USDT totalSupply on up to seven EVM chains straight from the official contracts, scans recent blocks for large transfers, issuance (mints) and redemptions (burns), and adds DefiLlama's cross-chain circulating supply with day/week/month changes. Works offline on pasted Transfer logs.\n\nMethodology:\n- Contracts: the official USDC and USDT contracts per chain (Ethereum, Base, Arbitrum, OP Mainnet, Polygon from the shared canonical-token table; Avalanche and BNB Chain checked on-chain via symbol()/decimals(); BNB Chain tokens are Binance-Peg with 18 decimals). USDT is not issued natively on Base or OP Mainnet.\n- Supply: totalSupply() and decimals() by eth_call at the latest block. Supplies on different chains can double count bridged amounts only for non-native deployments; native Circle/Tether deployments are separate issuances.\n- Transfers: eth_getLogs for Transfer(address,address,uint256) of the token over the last N blocks (small window: public nodes cap response sizes). Large = amount ≥ threshold (token units, treated as ≈ USD at the peg).\n- Mints/burns: Transfer from / to the zero address over a longer window using topic filters; for USDT on Ethereum Tether's Issue(uint256) / Redeem(uint256) events are used because that contract does not emit zero-address transfers on issuance.\n- Cross-chain circulation: DefiLlama stablecoins API (https://stablecoins.llama.fi/stablecoins), field circulating.peggedUSD with previous day/week/month and per-chain breakdown.", "tags": [ "web3" ], "x-mcp-tool": "stablecoin_flow_explorer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StablecoinFlowExplorerInput" }, "examples": { "example1": { "summary": "Large USDC flows from pasted logs (offline)", "value": { "mode": "pasted", "token": "USDC", "chain": "ethereum", "threshold": 1000000, "decimals": 6, "logs": "[{\"address\":\"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"topics\":[\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0x0000000000000000000000000000000000000000000000000000000000000000\",\"0x0000000000000000000000001111111111111111111111111111111111111111\"],\"data\":\"0x00000000000000000000000000000000000000000000000000002d79883d2000\",\"blockNumber\":\"0x1406f40\",\"logIndex\":\"0x1\",\"transactionHash\":\"0x0101010101010101010101010101010101010101010101010101010101010101\"},{\"address\":\"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"topics\":[\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0x0000000000000000000000001111111111111111111111111111111111111111\",\"0x0000000000000000000000002222222222222222222222222222222222222222\"],\"data\":\"0x00000000000000000000000000000000000000000000000000000ae9f7bcc000\",\"blockNumber\":\"0x1406f41\",\"logIndex\":\"0x2\",\"transactionHash\":\"0x0202020202020202020202020202020202020202020202020202020202020202\"},{\"address\":\"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"topics\":[\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0x0000000000000000000000003333333333333333333333333333333333333333\",\"0x0000000000000000000000004444444444444444444444444444444444444444\"],\"data\":\"0x000000000000000000000000000000000000000000000000000000009502f900\",\"blockNumber\":\"0x1406f41\",\"logIndex\":\"0x3\",\"transactionHash\":\"0x0303030303030303030303030303030303030303030303030303030303030303\"},{\"address\":\"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"topics\":[\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0x0000000000000000000000002222222222222222222222222222222222222222\",\"0x0000000000000000000000005555555555555555555555555555555555555555\"],\"data\":\"0x000000000000000000000000000000000000000000000000000002ba7def3000\",\"blockNumber\":\"0x1406f42\",\"logIndex\":\"0x4\",\"transactionHash\":\"0x0404040404040404040404040404040404040404040404040404040404040404\"},{\"address\":\"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"topics\":[\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0x0000000000000000000000006666666666666666666666666666666666666666\",\"0x0000000000000000000000007777777777777777777777777777777777777777\"],\"data\":\"0x000000000000000000000000000000000000000000000000000000e8d495cdc0\",\"blockNumber\":\"0x1406f42\",\"logIndex\":\"0x5\",\"transactionHash\":\"0x0505050505050505050505050505050505050505050505050505050505050505\"},{\"address\":\"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"topics\":[\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0x0000000000000000000000005555555555555555555555555555555555555555\",\"0x0000000000000000000000000000000000000000000000000000000000000000\"],\"data\":\"0x0000000000000000000000000000000000000000000000000000015d3ef79800\",\"blockNumber\":\"0x1406f43\",\"logIndex\":\"0x6\",\"transactionHash\":\"0x0606060606060606060606060606060606060606060606060606060606060606\"},{\"address\":\"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"topics\":[\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0x0000000000000000000000008888888888888888888888888888888888888888\",\"0x0000000000000000000000002222222222222222222222222222222222222222\"],\"data\":\"0x000000000000000000000000000000000000000000000000000003d1e3821000\",\"blockNumber\":\"0x1406f44\",\"logIndex\":\"0x7\",\"transactionHash\":\"0x0707070707070707070707070707070707070707070707070707070707070707\"},{\"address\":\"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"topics\":[\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"0x0000000000000000000000003333333333333333333333333333333333333333\",\"0x0000000000000000000000009999999999999999999999999999999999999999\"],\"data\":\"0x0000000000000000000000000000000000000000000000000000000008f0d180\",\"blockNumber\":\"0x1406f44\",\"logIndex\":\"0x8\",\"transactionHash\":\"0x0808080808080808080808080808080808080808080808080808080808080808\"}]" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StablecoinFlowExplorerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "StablecoinFlowExplorerInput": { "type": "object", "additionalProperties": false, "properties": { "mode": { "title": "Data source", "type": "string", "enum": [ "live", "pasted" ], "default": "live" }, "token": { "title": "Stablecoin", "type": "string", "enum": [ "USDC", "USDT" ], "default": "USDC" }, "supplyChains": { "title": "Chains for on-chain supply", "type": "array", "items": { "type": "string", "enum": [ "ethereum", "base", "arbitrum", "optimism", "polygon", "avalanche", "bsc" ] }, "default": [ "ethereum", "base", "arbitrum", "optimism", "polygon", "avalanche", "bsc" ] }, "chain": { "title": "Chain for transfer scan", "type": "string", "enum": [ "ethereum", "base", "arbitrum", "optimism", "polygon", "avalanche", "bsc" ], "default": "ethereum" }, "transferBlocks": { "title": "Blocks scanned for all transfers", "description": "Public nodes cap response size; busy tokens produce ~1,000+ logs per 10 Ethereum blocks.", "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "mintBurnBlocks": { "title": "Blocks scanned for mints/burns", "type": "integer", "minimum": 10, "maximum": 5000, "default": 1000 }, "threshold": { "title": "Large-transfer threshold", "type": "number", "minimum": 0, "default": 1000000, "x-unit": "tokens (≈ USD)" }, "defillama": { "title": "Include DefiLlama cross-chain circulation", "type": "boolean", "default": true }, "logs": { "title": "Pasted logs JSON", "description": "eth_getLogs result (array) or {result:[…]} / {logs:[…]}.", "type": "string", "maxLength": 2000000 }, "decimals": { "title": "Token decimals (pasted mode)", "type": "integer", "minimum": 0, "maximum": 36, "default": 6 } }, "required": [] }, "StablecoinFlowExplorerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "token", "mode", "supply", "window", "transfers", "mintBurn", "circulation" ], "properties": { "token": { "type": "string" }, "mode": { "type": "string" }, "supply": { "type": "object", "additionalProperties": false, "required": [ "chains", "total" ], "properties": { "total": { "type": "number" }, "chains": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "chain", "contract", "decimals", "totalSupply", "error" ], "properties": { "chain": { "type": "string" }, "contract": { "type": "string" }, "decimals": { "type": [ "integer", "null" ] }, "totalSupply": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] } } } } } }, "window": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "chain", "fromBlock", "toBlock", "blocks", "seconds", "mintBurnFromBlock" ], "properties": { "chain": { "type": "string" }, "fromBlock": { "type": [ "integer", "null" ] }, "toBlock": { "type": [ "integer", "null" ] }, "blocks": { "type": [ "integer", "null" ] }, "seconds": { "type": [ "integer", "null" ] }, "mintBurnFromBlock": { "type": [ "integer", "null" ] } } }, "transfers": { "type": "object", "additionalProperties": false, "required": [ "count", "volume", "threshold", "large", "topSenders", "topReceivers" ], "properties": { "count": { "type": "integer" }, "volume": { "type": "number" }, "threshold": { "type": "number" }, "large": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "txHash", "block", "logIndex", "kind", "from", "to", "raw", "amount" ], "properties": { "txHash": { "type": [ "string", "null" ] }, "block": { "type": [ "integer", "null" ] }, "logIndex": { "type": [ "integer", "null" ] }, "kind": { "type": "string", "enum": [ "mint", "burn", "transfer" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "raw": { "type": "string" }, "amount": { "type": "number" } } } }, "topSenders": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "address", "amount", "count" ], "properties": { "address": { "type": "string" }, "amount": { "type": "number" }, "count": { "type": "integer" } } } }, "topReceivers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "address", "amount", "count" ], "properties": { "address": { "type": "string" }, "amount": { "type": "number" }, "count": { "type": "integer" } } } } } }, "mintBurn": { "type": "object", "additionalProperties": false, "required": [ "mints", "burns", "minted", "burned", "netIssuance", "events" ], "properties": { "mints": { "type": "integer" }, "burns": { "type": "integer" }, "minted": { "type": "number" }, "burned": { "type": "number" }, "netIssuance": { "type": "number" }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "txHash", "block", "logIndex", "kind", "from", "to", "raw", "amount" ], "properties": { "txHash": { "type": [ "string", "null" ] }, "block": { "type": [ "integer", "null" ] }, "logIndex": { "type": [ "integer", "null" ] }, "kind": { "type": "string", "enum": [ "mint", "burn", "transfer" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "raw": { "type": "string" }, "amount": { "type": "number" } } } } } }, "circulation": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "circulating", "prevDay", "prevWeek", "prevMonth", "chains" ], "properties": { "circulating": { "type": "number" }, "prevDay": { "type": [ "number", "null" ] }, "prevWeek": { "type": [ "number", "null" ] }, "prevMonth": { "type": [ "number", "null" ] }, "chains": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "chain", "circulating", "share" ], "properties": { "chain": { "type": "string" }, "circulating": { "type": "number" }, "share": { "type": "number" } } } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }