{ "openapi": "3.1.0", "info": { "title": "On-chain Forensics API", "version": "2.8.1", "description": "Pay-per-call on-chain forensics: Canton Network (CC) burn/mint tracking, Linea burn-vault audit, ERC-20 burn/mint forensics for any token on Base or Ethereum mainnet (named aliases: ondo, qnt, edel, xlm, aero, degen, brett, buidl, usdy, ousg, ustb, usyc, bcspx, bcoin, bnvda, btsla, aapl, nvda, usdc, usdc_eth), wallet flow analysis for any address on Base or Ethereum mainnet, a token verdict card (activity metrics, verdict tier, shareable take) for any ERC-20, and a settle-safe pre-trade screen for AI agents trading tokenized assets. Payments via the x402 protocol: unpaid requests receive HTTP 402 with machine-readable payment requirements in the PAYMENT-REQUIRED header (USDC on Base).\n\nRelated service: Canton Swap Broker \u2014 x402-payable pay-per-call swaps on the Canton Network via the OneSwap atomic DvP DEX (quotes, escrow swaps, market data; same USDC-on-Base x402 payment). Landing + spec: https://leohoudinisanders-byte.github.io/canton-swap-broker/\n\nNEW (v2.4.1): ?endpoint=memo \u2014 $0.25 composed Due Diligence Memo: executive summary, supply forensics, wallet flows, settle-safe screen, severity-ranked red-flag table, and a deterministic bottom-line settlement recommendation (no LLM calls, same block = same memo). Pricing: $0.25 base; $0.35 when &counterparty= is provided (adds the counterparty trust screen to the memo).\n\nNEW (v2.5.0): XRPL support via chain=xrp \u2014 wallet forensics ($0.05, any r... address) and the issued-currency settle-safe screen ($0.02, issuer + currency or &token=rlusd|gatehub-usd): blackhole status, Default Ripple / No Freeze / Global Freeze / clawback flags, outstanding obligations, trustline breadth, verified gateway registry. XRPL verdict ($0.02) and due-diligence memo ($0.25/$0.35) are LIVE for XRPL issuers (chain=xrp&issuer=r...¤cy=USD): EVM-tier verdict mapping plus issuer checks (freeze/clawback/blackhole/registry) and holder/flow/book-offers/AMM activity metrics. Operated by Solene \u2014 deep research with receipts: the agent that ships working proof, not promises. All operations are also available as resource-oriented paths (/functions/forensicsToken etc.) per the Circle Agent Marketplace integration convention; X-402-Discovery: 1 requests return discovery-only 402s. Operated by Leo Sanders (leohoudinisanders@gmail.com); responses are deterministic compositions of on-chain reads with no LLM-generated content.", "x-payment": { "protocol": "x402", "price": { "default": "$0.05", "verdict": "$0.02", "settlesafe": "$0.02" }, "amountAtomic": { "default": "50000", "verdict": "20000", "settlesafe": "20000" }, "x402Version": 2, "network": "eip155:8453", "networkCaip2": "eip155:8453", "paymentHeader": "PAYMENT-SIGNATURE", "challengeHeader": "PAYMENT-REQUIRED", "responseHeader": "PAYMENT-RESPONSE", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x8EBf296c6273760ed9604C428f7EC13255E46fb9", "scheme": "exact", "facilitators": [ "https://x402.roundhouseai.io", "https://facilitator.payai.network" ] } }, "servers": [ { "url": "https://solene-fa2010da.base44.app" } ], "paths": { "/functions/forensicsApi": { "get": { "summary": "Forensics data endpoint", "description": "LEGACY generic route (kept for existing integrations): all operations via ?endpoint=. New integrations should use the dedicated per-operation routes (/functions/forensicsToken, .../forensicsVerdict, etc.), which advertise their own 402 payment metadata, input schemas and typed responses. Bare calls return the $0.02 directory tier.", "parameters": [ { "name": "endpoint", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "canton", "linea", "token", "wallet", "verdict", "settlesafe", "memo", "sweep" ] }, "description": "Dataset to fetch (verdict & settlesafe = $0.02, others $0.05) memo = $0.25 composed due-diligence memo (verdict + token + settlesafe in one, plus red-flag table and bottom line)." }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ondo", "qnt", "edel", "xlm", "aero", "degen", "brett", "buidl", "usdy", "ousg", "ustb", "usyc", "bcspx", "bcoin", "bnvda", "btsla", "aapl", "nvda", "usdc", "usdc_eth" ] }, "description": "Named token alias (token route or settlesafe route); resolves chain+contract automatically" }, { "name": "contract", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "ERC-20 contract address (endpoint=token)" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "ethereum", "xrp" ], "default": "base" }, "description": "Chain to read (endpoint=token with a raw contract; endpoint=wallet for wallet analysis)" }, { "name": "address", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "Wallet address (endpoint=wallet), ERC-20 token contract (endpoint=verdict), or token contract to screen (endpoint=settlesafe)" }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "Optional counterparty wallet to trust-screen (endpoint=settlesafe); returns trust_tier per CounterpartyScreen.trust_tier enum" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$|^[0-9A-Fa-f]{40}$" }, "description": "XRPL issued-currency code (chain=xrp settlesafe; e.g. USD, RLUSD)" }, { "name": "issuer", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^r[1-9A-HJ-NP-Za-km-z]{24,34}$" }, "description": "XRPL issuer address (chain=xrp settlesafe; equivalent to address=)" } ], "responses": { "200": { "description": "Paid response: JSON forensics dataset (payment settled via x402). Envelope {service, paid, settlement_tx, data}; data follows the endpoint-specific schema below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidResponse" } } } }, "402": { "description": "Payment Required: PAYMENT-REQUIRED header carries base64 x402 v2 PaymentRequired (USDC on Base, CAIP-2 eip155:8453, scheme exact); pay via PAYMENT-SIGNATURE header" }, "400": { "description": "Bad request: missing/invalid endpoint, address, contract, chain or token alias (see error + hint in body)" } } } }, "/functions/forensicsToken": { "get": { "summary": "ERC-20 burn/mint forensics (resource path)", "description": "Token burn/mint forensics: exact 24h net supply change plus recent mint/burn events for any ERC-20 on Base or Ethereum mainnet. EVM only (XRPL issuers are not supported on this route). REQUIRED INPUT: exactly one of token (named alias) or contract (0x contract address); chain defaults to base. Data-quality: incomplete log reads return null activity counts with activity_status PARTIAL_LOGS/UNAVAILABLE_SILENT_EMPTY_LOGS (zeros are never used to assert inactivity); supply-read failures are reported via supply_read_status and data_quality (ok, degraded_logs, ok_partial_supply, degraded_logs_partial_supply). evaluated_blocks carries the block range and window so results are reproducible.", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ondo", "qnt", "edel", "xlm", "aero", "degen", "brett", "buidl", "usdy", "ousg", "ustb", "usyc", "bcspx", "bcoin", "bnvda", "btsla", "aapl", "nvda", "usdc", "usdc_eth" ] }, "description": "Named token alias (required unless contract is given). Exactly one of token or contract must be provided." }, { "name": "contract", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "ERC-20 contract address (required unless token alias is given). Exactly one of token or contract must be provided." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "ethereum" ], "default": "base" }, "description": "EVM chain (Ethereum L2 Base or Ethereum mainnet). token endpoint supports EVM only; XRPL is not supported here." } ], "responses": { "200": { "description": "Paid response: JSON forensics dataset (payment settled via x402). Envelope {service, paid, settlement_tx, data}; data follows the endpoint-specific schema below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "402": { "description": "Payment Required: PAYMENT-REQUIRED header carries base64 x402 v2 PaymentRequired (USDC on Base, CAIP-2 eip155:8453, scheme exact); pay via PAYMENT-SIGNATURE header" }, "400": { "description": "Bad request: missing/invalid endpoint, address, contract, chain or token alias (see error + hint in body)" } }, "operationId": "tokenForensics" } }, "/functions/forensicsWallet": { "get": { "summary": "Wallet forensics (resource path)", "description": "Wallet forensics: balance, transaction count, recent ERC-20 flows, top counterparties and a machine-readable trust tier (TRUSTED_ACTIVITY / LIGHT_ACTIVITY / NO_RECENT_ACTIVITY / SUSPICIOUS / EMPTY / CONTRACT_ADDRESS / ISSUER_ACCOUNT for XRPL) on Base, Ethereum or XRPL. REQUIRED INPUT: address (0x EVM address, or r... classic XRPL address; X-addresses are rejected with a hint). chain defaults to base; chain=xrp screens an XRPL account.", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "ethereum", "xrp" ], "default": "base" }, "description": "Chain: base (default), ethereum, or xrp (XRPL account screen)." }, { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$|^r[a-zA-Z0-9]{15,40}$" }, "description": "Wallet address. REQUIRED. EVM: 0x 40-hex. XRPL: classic r-address (X-addresses rejected with a hint)." } ], "responses": { "200": { "description": "Paid response: JSON forensics dataset (payment settled via x402). Envelope {service, paid, settlement_tx, data}; data follows the endpoint-specific schema below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "402": { "description": "Payment Required: PAYMENT-REQUIRED header carries base64 x402 v2 PaymentRequired (USDC on Base, CAIP-2 eip155:8453, scheme exact); pay via PAYMENT-SIGNATURE header" }, "400": { "description": "Bad request: missing/invalid endpoint, address, contract, chain or token alias (see error + hint in body)" } }, "operationId": "walletForensics" } }, "/functions/forensicsVerdict": { "get": { "summary": "Token verdict card, $0.02 (resource path)", "description": "Token verdict card: deterministic tier (e.g. RED_HOT / ACTIVE / DORMANT / NOT_A_CONTRACT / UNKNOWN), 0-100 activity score, red flags and a plain-language take, on Base, Ethereum or XRPL. REQUIRED INPUT: address (EVM token contract, or XRPL issuer r-address with chain=xrp; currency required for XRPL issuers). Incomplete log reads return UNKNOWN tier with LOGS_UNAVAILABLE and null activity counts, never a false DORMANT; evaluated_blocks carries the reproducible block range.", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "ethereum", "xrp" ], "default": "base" }, "description": "Chain: base (default), ethereum, or xrp (issuer verdict)." }, { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$|^r[a-zA-Z0-9]{15,40}$" }, "description": "Token contract (EVM) or issuer address (XRPL). REQUIRED." }, { "name": "issuer", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^r[1-9A-HJ-NP-Za-km-z]{24,34}$" }, "description": "XRPL issuer address (chain=xrp settlesafe; equivalent to address=)" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$|^[0-9A-Fa-f]{40}$" }, "description": "XRPL only (chain=xrp): the issued currency code or hex (e.g. USD, RLUSD). Required for XRPL verdicts." } ], "responses": { "200": { "description": "Paid response: JSON forensics dataset (payment settled via x402). Envelope {service, paid, settlement_tx, data}; data follows the endpoint-specific schema below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerdictResponse" } } } }, "402": { "description": "Payment Required: PAYMENT-REQUIRED header carries base64 x402 v2 PaymentRequired (USDC on Base, CAIP-2 eip155:8453, scheme exact); pay via PAYMENT-SIGNATURE header" }, "400": { "description": "Bad request: missing/invalid endpoint, address, contract, chain or token alias (see error + hint in body)" } }, "operationId": "verdictForensics" } }, "/functions/forensicsSettlesafe": { "get": { "summary": "Settle-safe pre-trade screen, $0.02 (resource path)", "description": "Settle-safe pre-trade screen: canonical-asset check against the verified registry (KNOWN_CANONICAL / UNVERIFIED / NOT_A_CONTRACT / NOT_ERC20_READABLE / SYMBOL_MISMATCH) with optional counterparty wallet trust screen, on Base, Ethereum or XRPL. REQUIRED INPUT: for EVM, exactly one of token (alias) or address (0x contract); for XRPL (chain=xrp), issuer r-address plus currency (or token alias). counterparty is optional and adds the wallet trust screen.", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ondo", "qnt", "edel", "xlm", "aero", "degen", "brett", "buidl", "usdy", "ousg", "ustb", "usyc", "bcspx", "bcoin", "bnvda", "btsla", "aapl", "nvda", "usdc", "usdc_eth" ] }, "description": "Named token alias. Required unless address is given (alternatives)." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "ethereum", "xrp" ], "default": "base" }, "description": "Chain: base (default), ethereum, or xrp (issuer screen)." }, { "name": "address", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$|^r[a-zA-Z0-9]{15,40}$" }, "description": "Token contract address (EVM) or issuer address (XRPL). Required unless token alias is given." }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "Optional wallet address; adds the counterparty trust tier to the screen." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$|^[0-9A-Fa-f]{40}$" }, "description": "XRPL only: issued currency code (required for XRPL issuers without a token alias)." }, { "name": "issuer", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^r[1-9A-HJ-NP-Za-km-z]{24,34}$" }, "description": "XRPL issuer address (chain=xrp settlesafe; equivalent to address=)" } ], "responses": { "200": { "description": "Paid response: JSON forensics dataset (payment settled via x402). Envelope {service, paid, settlement_tx, data}; data follows the endpoint-specific schema below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettleSafeResponse" } } } }, "402": { "description": "Payment Required: PAYMENT-REQUIRED header carries base64 x402 v2 PaymentRequired (USDC on Base, CAIP-2 eip155:8453, scheme exact); pay via PAYMENT-SIGNATURE header" }, "400": { "description": "Bad request: missing/invalid endpoint, address, contract, chain or token alias (see error + hint in body)" } }, "operationId": "settleSafeForensics" } }, "/functions/forensicsMemo": { "get": { "summary": "Due diligence memo, $0.25 (resource path)", "description": "Token due-diligence memo: composes the verdict card, 24h supply forensics and the settle-safe screen into one deterministic memo with a severity-ranked red-flag table and a bottom-line recommendation (same block = same memo; no LLM calls). REQUIRED INPUT: address (EVM token contract, or XRPL issuer with chain=xrp + currency). counterparty is optional ($0.35 tier) and adds the counterparty trust screen. Each section reports its own quality via section_quality, and incomplete reads are marked unavailable/partial rather than zero.", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ondo", "qnt", "edel", "xlm", "aero", "degen", "brett", "buidl", "usdy", "ousg", "ustb", "usyc", "bcspx", "bcoin", "bnvda", "btsla", "aapl", "nvda", "usdc", "usdc_eth" ] }, "description": "Named token alias (token route or settlesafe route); resolves chain+contract automatically" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "ethereum", "xrp" ], "default": "base" }, "description": "Chain: base (default), ethereum, or xrp (issuer memo)." }, { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$|^r[a-zA-Z0-9]{15,40}$" }, "description": "Token contract (EVM) or issuer address (XRPL). REQUIRED." }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "Optional wallet address; upgrades to the $0.35 tier and adds the counterparty trust screen." }, { "name": "issuer", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^r[1-9A-HJ-NP-Za-km-z]{24,34}$" }, "description": "XRPL issuer address (chain=xrp settlesafe; equivalent to address=)" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$|^[0-9A-Fa-f]{40}$" }, "description": "XRPL issued-currency code (chain=xrp settlesafe; e.g. USD, RLUSD)" } ], "responses": { "200": { "description": "Paid response: JSON forensics dataset (payment settled via x402). Envelope {service, paid, settlement_tx, data}; data follows the endpoint-specific schema below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoResponse" } } } }, "402": { "description": "Payment Required: PAYMENT-REQUIRED header carries base64 x402 v2 PaymentRequired (USDC on Base, CAIP-2 eip155:8453, scheme exact); pay via PAYMENT-SIGNATURE header" }, "400": { "description": "Bad request: missing/invalid endpoint, address, contract, chain or token alias (see error + hint in body)" } }, "operationId": "memoForensics" } }, "/functions/forensicsCanton": { "get": { "summary": "Canton Network (CC) burn/mint snapshot (resource path)", "description": "Canton Network (CC) burn/mint snapshot: cumulative totals, twice-daily deltas, burn/mint ratios, net emission and 7d averages, cross-checked against live Noves Canton public data (cc_price, marker earnings, validator/asset counts; preapproval-fee watch). No operation parameters. Canton is a permissioned network: public metrics arrive via scheduled entity snapshots (refreshed twice daily at 07:30/19:30 CT) plus the live Noves cross-check, so emission figures are snapshot-derived rather than null-by-design gaps.", "parameters": [], "responses": { "200": { "description": "Paid response: JSON forensics dataset (payment settled via x402). Envelope {service, paid, settlement_tx, data}; data follows the endpoint-specific schema below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CantonResponse" } } } }, "402": { "description": "Payment Required: PAYMENT-REQUIRED header carries base64 x402 v2 PaymentRequired (USDC on Base, CAIP-2 eip155:8453, scheme exact); pay via PAYMENT-SIGNATURE header" }, "400": { "description": "Bad request: missing/invalid endpoint, address, contract, chain or token alias (see error + hint in body)" } }, "operationId": "cantonSnapshot" } }, "/functions/forensicsLinea": { "get": { "summary": "Linea burn-vault audit snapshot (resource path)", "description": "Linea (LINEA) burn snapshot: cumulative burn, 24h delta and scan metadata, refreshed daily by an entity workflow (snapshot cadence documented in scan_time). No operation parameters.", "parameters": [], "responses": { "200": { "description": "Paid response: JSON forensics dataset (payment settled via x402). Envelope {service, paid, settlement_tx, data}; data follows the endpoint-specific schema below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineaResponse" } } } }, "402": { "description": "Payment Required: PAYMENT-REQUIRED header carries base64 x402 v2 PaymentRequired (USDC on Base, CAIP-2 eip155:8453, scheme exact); pay via PAYMENT-SIGNATURE header" }, "400": { "description": "Bad request: missing/invalid endpoint, address, contract, chain or token alias (see error + hint in body)" } }, "operationId": "lineaSnapshot" } }, "/functions/forensicsSweep": { "get": { "summary": "Portfolio sweep, $0.25 (resource path)", "description": "Portfolio sweep: screens a wallet's holdings across the curated registry (RWA, tokenized equities, blue chips) with the same verdict engine as the verdict route - identical windows, tier thresholds and scores; there is no intentional difference in metric definitions. Incomplete log reads return UNKNOWN (never false DORMANT); each holding carries activity_status and evaluated_blocks so consumers can compare and reproduce results. A zero-holding sweep does not mean the wallet is empty (registry coverage note included in the response).", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "Wallet address (0x, EVM only). REQUIRED." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "ethereum" ], "default": "base" }, "description": "EVM chain: base (default) or ethereum. XRPL is not supported on this route." } ], "responses": { "200": { "description": "Paid response: JSON forensics dataset (payment settled via x402). Envelope {service, paid, settlement_tx, data}; data follows the endpoint-specific schema below.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SweepResponse" } } } }, "402": { "description": "Payment Required: PAYMENT-REQUIRED header carries base64 x402 v2 PaymentRequired (USDC on Base, CAIP-2 eip155:8453, scheme exact); pay via PAYMENT-SIGNATURE header" }, "400": { "description": "Bad request: missing/invalid endpoint, address, contract, chain or token alias (see error + hint in body)" } }, "operationId": "forensicsSweep" } } }, "components": { "schemas": { "PaidResponse": { "type": "object", "required": [ "service", "paid", "data" ], "properties": { "service": { "type": "string", "const": "onchain-forensics" }, "paid": { "type": "string", "description": "Amount charged for this call, e.g. $0.02" }, "settlement_tx": { "type": [ "string", "null" ], "description": "x402 settlement transaction hash when the facilitator reports one" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/SettleSafeResponse" }, { "$ref": "#/components/schemas/WalletResponse" }, { "$ref": "#/components/schemas/TokenResponse" }, { "$ref": "#/components/schemas/VerdictResponse" }, { "$ref": "#/components/schemas/CantonResponse" }, { "$ref": "#/components/schemas/LineaResponse" } ] } } }, "SettleSafeResponse": { "type": "object", "description": "Pre-trade settle-safe screen ($0.02). Answers: is this the real asset, and can this counterparty be trusted? Decisive negatives (not-a-contract, not-readable) are confirmed across independent RPCs; a degraded public-RPC network yields VERIFICATION_UNAVAILABLE instead of a false negative.", "required": [ "endpoint", "checked_at", "chain", "settle_safe", "overall_pass", "asset_status", "asset", "risk_flags", "reasons", "plain_take" ], "properties": { "endpoint": { "type": "string", "const": "settlesafe" }, "checked_at": { "type": "string", "format": "date-time" }, "chain": { "type": "string", "enum": [ "base-mainnet", "ethereum-mainnet" ] }, "settle_safe": { "type": "boolean", "description": "Asset screen result only" }, "overall_pass": { "type": "boolean", "description": "Asset screen AND (counterparty screen if provided)" }, "asset_status": { "$ref": "#/components/schemas/AssetStatus" }, "asset": { "$ref": "#/components/schemas/AssetBlock" }, "counterparty": { "oneOf": [ { "$ref": "#/components/schemas/CounterpartyScreen" }, { "type": "null" } ] }, "risk_flags": { "type": "array", "items": { "$ref": "#/components/schemas/RiskFlag" } }, "reasons": { "type": "array", "items": { "type": "string" } }, "rpc_verification": { "type": "object", "properties": { "code_agreeing_nodes": { "type": "integer", "description": "How many independent RPCs returned the same eth_getCode result" }, "code_block": { "type": "integer", "description": "Block height of the freshest node used for the code read" }, "supply_status": { "type": "string", "enum": [ "readable", "not_readable", "degraded" ], "description": "readable = well-formed result confirmed by 2 RPCs (or a single well-formed result when the rest of the public RPC pool is degraded \u2014 reads only count when the returned value is well-formed, so degraded nodes can never flip a classification); not_readable = revert confirmed on healthy nodes; degraded = public RPC network unavailable, screen inconclusive" }, "supply_probe": { "type": "array", "description": "Per-node evidence trail for the totalSupply read (v2.3.2): every RPC attempt that did NOT yield a well-formed result is logged here with its outcome, so any classification is auditable. Empty when all nodes answered well-formed on first try. Outcomes: invalid_result: (JSON-RPC success but empty/malformed result \u2014 common from degraded public nodes), error_retry / error_final (node error, retried once per node), skip_control_same_call (read failed and the control call is identical to the read, so no control is performed), control_failed (health check failed).", "items": { "type": "object", "properties": { "node": { "type": "string", "description": "RPC host that produced this outcome" }, "outcome": { "type": "string", "description": "What happened on this node's attempt" } }, "required": [ "node", "outcome" ] } } } }, "plain_take": { "type": "string", "description": "Shareable plain-language verdict" } } }, "AssetStatus": { "type": "string", "enum": [ "KNOWN_CANONICAL", "UNVERIFIED", "NOT_A_CONTRACT", "NOT_ERC20_READABLE", "SYMBOL_MISMATCH", "VERIFICATION_UNAVAILABLE" ], "description": "KNOWN_CANONICAL = contract matches the verified tokenized-asset registry and serves a readable ERC-20; UNVERIFIED = live ERC-20 but not in the registry; NOT_A_CONTRACT = EOA; NOT_ERC20_READABLE = totalSupply() revert confirmed on healthy nodes; SYMBOL_MISMATCH = on-chain symbol differs from the registry entry; VERIFICATION_UNAVAILABLE = public RPC network degraded, no verdict issued (retry)." }, "RiskFlag": { "type": "string", "enum": [ "NOT_A_CONTRACT", "NOT_ERC20_READABLE", "SYMBOL_MISMATCH", "NOT_IN_VERIFIED_REGISTRY", "COUNTERPARTY_SUSPICIOUS", "COUNTERPARTY_SCREEN_FAILED", "READ_VERIFICATION_DEGRADED" ] }, "AssetBlock": { "type": "object", "properties": { "contract": { "type": "string" }, "token_name": { "type": [ "string", "null" ] }, "token_symbol": { "type": [ "string", "null" ] }, "total_supply": { "type": [ "string", "null" ], "description": "Human-readable total supply at the token's own decimals" }, "registry_alias": { "type": [ "string", "null" ] }, "registry_canonical": { "type": "boolean" }, "is_contract": { "type": "boolean" } } }, "CounterpartyScreen": { "type": "object", "description": "Trust tier heuristic: lifetime history (nonce) + ERC-20 flows in the recent window (~100 min).", "properties": { "address": { "type": "string" }, "trust_tier": { "$ref": "#/components/schemas/TrustTier" }, "trust_pass": { "type": "boolean", "description": "True only for TRUSTED_ACTIVITY" }, "trust_reasons": { "type": "array", "items": { "type": "string" } }, "total_txs_sent": { "type": "integer", "description": "Lifetime outgoing transactions (eth_getTransactionCount)" }, "unique_counterparties": { "type": "integer" }, "is_contract": { "type": "boolean", "description": "eth_getCode non-empty (freshest of 3 nodes)" }, "eip_7702_delegated": { "type": "boolean", "description": "True when the code is exactly the EIP-7702 delegation designator \u2014 reported as DELEGATED_EOA, not CONTRACT_ADDRESS" }, "error": { "type": [ "string", "null" ], "description": "Present when the screen itself failed (risk flag COUNTERPARTY_SCREEN_FAILED)" } } }, "TrustTier": { "type": "string", "enum": [ "TRUSTED_ACTIVITY", "LIGHT_ACTIVITY", "NO_RECENT_ACTIVITY", "SUSPICIOUS", "EMPTY", "CONTRACT_ADDRESS", "DELEGATED_EOA" ], "description": "TRUSTED_ACTIVITY = >=10 lifetime txs, >=5 unique counterparties and >=8 in-window transfers; LIGHT_ACTIVITY = some history, limited activity; NO_RECENT_ACTIVITY = history but no ERC-20 movement in the window; SUSPICIOUS = funded but never sent a transaction (bait/dust pattern); EMPTY = no history at all; CONTRACT_ADDRESS = holds standalone contract code (screen with endpoint=token first); DELEGATED_EOA = EIP-7702 smart-account wallet (code is a delegation designator; screen the delegate before high-value settles)." }, "WalletResponse": { "type": "object", "description": "Wallet forensics ($0.05): balance, lifetime tx count, ERC-20 flows and top counterparties (~100 min window), plus the machine-readable trust tier.", "properties": { "endpoint": { "type": "string", "const": "wallet" }, "chain": { "type": "string", "enum": [ "base-mainnet", "ethereum-mainnet" ] }, "address": { "type": "string" }, "eth_balance": { "type": "string" }, "total_txs_sent": { "type": "integer" }, "is_contract": { "type": "boolean" }, "eip_7702_delegated": { "type": "boolean" }, "trust_tier": { "$ref": "#/components/schemas/TrustTier" }, "trust_pass": { "type": "boolean" }, "trust_reasons": { "type": "array", "items": { "type": "string" } }, "activity_window_min": { "type": "integer" }, "erc20_transfers_in": { "type": "integer" }, "erc20_transfers_out": { "type": "integer" }, "distinct_tokens": { "type": "integer" }, "unique_counterparties": { "type": "integer" }, "top_counterparties": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "transfers_in": { "type": "integer" }, "transfers_out": { "type": "integer" } } } } } }, "TokenResponse": { "type": "object", "description": "Token burn/mint forensics response (token route). Incomplete log reads withhold activity counts (null) instead of asserting zero inactivity; supply-read failures are surfaced via supply_read_status and data_quality.", "properties": { "endpoint": { "type": "string", "const": "token" }, "chain": { "type": "string" }, "contract": { "type": "string" }, "token_name": { "type": [ "string", "null" ] }, "token_symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] }, "total_supply_now": { "type": [ "string", "null" ], "description": "Raw integer string; null when the supply read failed." }, "total_supply_24h_ago": { "type": [ "string", "null" ] }, "net_supply_change_24h": { "type": [ "string", "null" ] }, "net_supply_change_pct_24h": { "type": [ "number", "null" ] }, "mints_24h": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ] }, "volume": { "type": [ "string", "null" ] } } }, "burns_24h": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ] }, "volume": { "type": [ "string", "null" ] } } }, "recent_activity_window_min": { "type": "integer" }, "transfers_recent": { "type": [ "integer", "null" ], "description": "null when the log read is incomplete - a zero here is an observed zero, never an assumed one" }, "unique_wallets_recent": { "type": [ "integer", "null" ], "description": "Null when log reads were incomplete." }, "mints_recent": { "type": [ "object", "null" ], "properties": { "count": { "type": [ "integer", "null" ] }, "volume": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ok", "partial" ] } } }, "burns_recent": { "type": [ "object", "null" ], "properties": { "count": { "type": [ "integer", "null" ] }, "volume": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ok", "partial" ] } } }, "activity_status": { "type": "string", "enum": [ "OK", "PARTIAL_LOGS", "PARTIAL_COVERAGE", "UNAVAILABLE_SILENT_EMPTY_LOGS" ], "description": "OK = complete read; PARTIAL_LOGS / PARTIAL_COVERAGE / UNAVAILABLE_SILENT_EMPTY_LOGS = counts withheld because the read was incomplete" }, "activity_note": { "type": "string", "description": "Present when activity counts were withheld due to incomplete reads." }, "logs_batches_failed": { "type": "integer" }, "supply_read_status": { "type": "string", "enum": [ "ok", "partial", "unavailable" ] }, "data_quality": { "type": "string", "description": "ok | degraded_logs | ok_partial_supply | degraded_logs_partial_supply" }, "evaluated_blocks": { "$ref": "#/components/schemas/EvaluatedBlocks" }, "error": { "type": "string" }, "logs_coverage": { "$ref": "#/components/schemas/LogsCoverage" } } }, "VerdictResponse": { "type": "object", "description": "Deterministic token verdict card. Incomplete log reads return UNKNOWN tier with LOGS_UNAVAILABLE and null counts, never a false DORMANT.", "properties": { "verdict_tier": { "type": "string", "description": "e.g. RED_HOT, ACTIVE, LIGHT_ACTIVITY, DORMANT, NOT_A_CONTRACT, NOT_AN_ISSUER, UNKNOWN" }, "activity_score_0_100": { "type": "integer" }, "window_min": { "type": "integer" }, "transfers_recent": { "type": [ "integer", "null" ], "description": "null when the log read is incomplete - a zero here is an observed zero, never an assumed one" }, "unique_wallets_recent": { "type": [ "integer", "null" ] }, "mints_recent": { "type": [ "integer", "null" ] }, "burns_recent": { "type": [ "integer", "null" ] }, "largest_transfer": { "type": [ "object", "null" ] }, "concentration_top_wallet_share": { "type": "number" }, "flags": { "type": "array", "items": { "type": "string" } }, "activity_status": { "type": "string", "enum": [ "OK", "PARTIAL_LOGS", "PARTIAL_COVERAGE", "UNAVAILABLE_SILENT_EMPTY_LOGS" ], "description": "OK = complete read; PARTIAL_LOGS / PARTIAL_COVERAGE / UNAVAILABLE_SILENT_EMPTY_LOGS = counts withheld because the read was incomplete" }, "logs_batches_failed": { "type": "integer" }, "evaluated_blocks": { "$ref": "#/components/schemas/EvaluatedBlocks" }, "take": { "type": "string" }, "logs_coverage": { "$ref": "#/components/schemas/LogsCoverage" } } }, "CantonResponse": { "type": "object", "description": "Canton Network (CC) burn/mint snapshot ($0.05). Canton is a permissioned chain: metrics are snapshotted on-chain twice daily (07:30 and 19:30 America/Chicago) and served from the latest snapshot. Delta fields are since the previous snapshot and re-derived from stored totals if a snapshot is missing them.", "properties": { "endpoint": { "type": "string", "const": "canton" }, "as_of": { "type": [ "string", "null" ], "description": "Snapshot timestamp" }, "cc_price_usd": { "type": [ "number", "null" ] }, "total_supply_cc": { "type": [ "number", "null" ] }, "total_burned_cc": { "type": [ "number", "null" ], "description": "Cumulative CC burned" }, "total_minted_cc": { "type": [ "number", "null" ], "description": "Cumulative CC minted (rewards issued)" }, "mint_delta_cc": { "type": [ "number", "null" ], "description": "CC minted since previous snapshot (0 = no minting)" }, "burn_delta_cc": { "type": [ "number", "null" ], "description": "CC burned since previous snapshot (0 = no burning)" }, "supply_delta_cc": { "type": [ "number", "null" ] }, "net_emission_cc": { "type": [ "number", "null" ], "description": "mint_delta - burn_delta since previous snapshot; negative = net deflationary" }, "net_emission_7d_avg_cc": { "type": [ "number", "null" ], "description": "Trailing-7-day daily-average net emission from snapshot history" }, "burn_mint_ratio_24h": { "type": [ "number", "null" ], "description": "burn_delta/mint_delta since previous snapshot; null only when zero CC was minted (ratio undefined)" }, "burn_mint_ratio_cumulative": { "type": [ "number", "null" ] }, "tripped": { "type": "boolean", "description": "True when a monitored threshold event fired" }, "trip_reason": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "update_frequency": { "type": "string" }, "null_semantics": { "type": "string" } } }, "LineaResponse": { "type": "object", "description": "Linea burn-vault forensics snapshot ($0.05): ground-truth audit of the Linea burn pipeline, re-scanned on-chain daily (~09:00 America/Chicago).", "properties": { "endpoint": { "type": "string", "const": "linea" }, "as_of": { "type": [ "string", "null" ], "description": "Timestamp of the latest on-chain re-scan" }, "cumulative_burned_linea": { "type": [ "number", "null" ], "description": "Cumulative LINEA removed from supply by the burn engine" }, "last_l1_burn_date": { "type": [ "string", "null" ], "description": "Date of the last final L1 burn (engine paused since 2026-03-10)" }, "last_op_block": { "type": [ "number", "null" ] }, "last_op_date": { "type": [ "string", "null" ], "description": "Date of the last L2 vault burnAndBridge operation" }, "vault_balance_eth": { "type": [ "number", "null" ], "description": "ETH held by the L2 burn vault" }, "safe_balance_eth": { "type": [ "number", "null" ], "description": "ETH held by the burn-executor Safe multisig" }, "safe_last_exec_date": { "type": [ "string", "null" ] }, "update_frequency": { "type": "string" }, "data_note": { "type": "string" } } }, "EvaluatedBlocks": { "type": "object", "description": "The exact block range evaluated, so consumers can compare and reproduce results.", "properties": { "latest_block": { "type": "integer" }, "from_block": { "type": "integer" }, "window_min": { "type": "integer" } } }, "MemoResponse": { "type": "object", "description": "Composed due-diligence memo (verdict + supply forensics + settle-safe screen + red-flag table + bottom line). Each section carries its own quality status; incomplete reads are marked unavailable/partial rather than zero.", "properties": { "header": { "type": "object", "properties": { "generated": { "type": "string" }, "asset": { "type": "string" }, "chain": { "type": "string" }, "price_tier": { "type": "string" }, "memo_version": { "type": "string" } } }, "executive_summary": { "type": "string" }, "supply_forensics": { "type": [ "object", "null" ], "description": "TokenResponse-shaped section; may be {status: unavailable}." }, "wallet_flows": { "type": [ "object", "null" ], "description": "Verdict-derived flows incl. evaluated_blocks; may be {status: unavailable}." }, "settle_safe_screen": { "type": [ "object", "null" ], "description": "SettleSafeResponse-shaped section." }, "red_flags": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "CRITICAL", "HIGH", "MEDIUM", "WARN", "INFO" ] }, "flag": { "type": "string" }, "detail": { "type": "string" } } } }, "section_quality": { "type": "object", "description": "Per-section data quality: settlesafe, verdict_logs, supply.", "properties": { "settlesafe": { "type": "string" }, "verdict_logs": { "type": "string" }, "supply": { "type": "string" } } }, "bottom_line": { "type": "object", "properties": { "recommendation": { "type": "string" }, "confidence": { "type": "string" }, "summary": { "type": "string" } } }, "counterparty_screen": { "type": [ "object", "null" ], "description": "Present on the $0.35 tier." } } }, "SweepResponse": { "type": "object", "description": "Portfolio sweep across the curated registry, using the SAME verdict engine as the verdict route (no intentional difference in metric definitions).", "properties": { "endpoint": { "type": "string", "const": "sweep" }, "wallet": { "type": "string" }, "chain": { "type": "string" }, "screen_count": { "type": "integer" }, "metric_definitions": { "type": "string", "description": "States that holdings are scored by the same verdict engine as the verdict route, and that incomplete reads yield UNKNOWN, never DORMANT." }, "holdings": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string" }, "symbol": { "type": "string" }, "contract": { "type": "string" }, "balance_display": { "type": "number" }, "verdict_tier": { "type": "string" }, "activity_score_0_100": { "type": [ "integer", "null" ] }, "activity_status": { "type": "string" }, "transfers_recent": { "type": [ "integer", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } }, "evaluated_blocks": { "$ref": "#/components/schemas/EvaluatedBlocks" }, "screen_status": { "type": "string" } } } }, "bottom_line": { "type": "object" }, "note": { "type": "string" } } }, "LogsCoverage": { "type": "object", "description": "Log-read coverage accounting (v2.8.1). Density-adaptive chunking keeps each eth_getLogs query under provider response caps; when the request budget cannot cover the nominal window the scanned span shrinks and is reported here and in evaluated_blocks, so counts stay exact for the span they describe.", "properties": { "window_blocks": { "type": "integer", "description": "nominal window the endpoint targets" }, "scanned_blocks": { "type": "integer", "description": "blocks actually scanned (0 when the read is incomplete)" }, "chunks": { "type": "integer" }, "logs_per_block": { "type": "number", "description": "density probe result used to size chunks" }, "chunk_blocks": { "type": "integer", "description": "block span per query after density sizing" }, "exact": { "type": "boolean", "description": "true only when the scan completed without loss and the counts are exact for scanned_blocks" }, "truncated": { "type": "boolean", "description": "true when any batch was lost after retries; activity counts are withheld in that case" } } } } }, "x-classification-logic": { "settlesafe": { "asset": "KNOWN_CANONICAL requires an exact match (contract+chain) against the verified tokenized-asset registry (20 aliases) AND a readable ERC-20 interface. UNVERIFIED assets pass settle_safe=true with risk flag NOT_IN_VERIFIED_REGISTRY (confirm issuer independently). Fail-closed: NOT_A_CONTRACT, NOT_ERC20_READABLE, SYMBOL_MISMATCH and VERIFICATION_UNAVAILABLE all return settle_safe=false.", "counterparty": "Same trust-tier heuristic as endpoint=wallet (see TrustTier description). SUSPICIOUS (funded, never acted) additionally raises risk flag COUNTERPARTY_SUSPICIOUS.", "verification_guarantee": "Decisive negatives are confirmed across independent public RPCs before being issued: eth_getCode is read from the freshest of 3 nodes; a totalSupply revert is only accepted when a healthy node (verified via a control USDC read on the same node) confirms it; when the public RPC network itself is degraded the endpoint returns VERIFICATION_UNAVAILABLE instead of a false negative, and the client should retry." }, "wallet": "Trust tiers are deterministic thresholds over lifetime nonce and recent-window ERC-20 flows; see the TrustTier schema description for exact thresholds.", "verdict": "Deterministic tiers over unique-wallet counts in the recent activity window; see the VerdictResponse.verdict_tier description.", "canton": "Canton is a permissioned chain: on-chain CC reads are not publicly queryable, so the endpoint serves twice-daily snapshots (07:30/19:30 America/Chicago). Delta fields compare against the previous snapshot and are re-derived from stored cumulative totals when missing. burn_mint_ratio_24h is null only when zero CC was minted in the window (ratio undefined).", "linea": "Snapshot-served from a daily on-chain re-scan (~09:00 America/Chicago). The burn engine has been paused since 2026-03-10, so cumulative figures are stable by design; vault/Safe balances re-verify at every refresh." } }