{"openapi":"3.1.0","info":{"title":"token-risk","version":"0.1.0","description":"Machine-payable API returning deterministic structural risk reports for ERC-20 tokens on Base (chainId 8453), paid per request in USDC via the x402 protocol (v2). Keyless x402-native payment per request — no signup, no API key; pay with USDC via EIP-3009 authorization. Also offers wallet-address structural-safety reports on Base via POST /v1/wallet. The engine reports STRUCTURAL risk, not reputation — centralized-control powers (mint/pause/blacklist) are flagged regardless of issuer; score is a structural-safety score 0-100 where higher means structurally safer."},"paths":{"/health":{"get":{"operationId":"getHealth","summary":"Liveness probe (always free, never behind payment)","responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"},"version":{"type":"string"},"uptime":{"type":"integer","minimum":0}},"required":["status","service","version","uptime"]}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"This document (free)","responses":{"200":{"description":"OpenAPI 3.1 document."}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","summary":"Plain-text service description for LLM agents (free)","responses":{"200":{"description":"llms.txt plain-text document."}}}},"/samples/index.json":{"get":{"operationId":"listSamples","summary":"List free committed sample reports","description":"See a full real report before paying: GET /samples/index.json lists free committed samples (GET /samples/{name}.json).","responses":{"200":{"description":"JSON list of sample filenames and URLs.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/samples/{name}":{"get":{"operationId":"getSample","summary":"Fetch one free committed sample report","description":"See a full real report before paying: GET /samples/index.json lists free committed samples (GET /samples/{name}.json).","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+\\.json$"}}],"responses":{"200":{"description":"Raw RiskReport or WalletReport JSON from committed samples.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Sample not found. Errors use the uniform envelope { \"error\": { \"code\", \"message\", \"requestId\" } }."}}}},"/v1/scan":{"post":{"operationId":"scanToken","summary":"Structural risk scan of an ERC-20 token (paid, $0.01 USDC per request)","description":"Deterministic on-chain structural risk report for an ERC-20 token on Base. Keyless x402-native payment — no signup, no API key. Reports STRUCTURAL risk, not reputation: centralized-control powers (mint/pause/blacklist) are flagged regardless of issuer. Score 0-100, higher = structurally safer. See free real samples before paying: GET /samples/index.json Widely-held assets can carry centralized-control powers by design; context.knownAsset flags tokens on our compiled list of well-known Base assets (context only — it does not change verdict or score).","x-x402":{"x402Version":2,"scheme":"exact","network":"eip155:8453","amount":"10000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x332DbF15a8Bcca8eEB4390b380202360F4f45401","maxTimeoutSeconds":300,"priceUsdc":"$0.01"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"200":{"description":"RiskReport. Deterministic for identical inputs within the cache window; the report's `cache` field carries hit/age metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskReport"}}}},"400":{"description":"Invalid request body. Errors use the uniform envelope { \"error\": { \"code\", \"message\", \"requestId\" } }."},"402":{"description":"Payment required (x402 v2). Requirements — including the bazaar discovery extension — are advertised in the base64-encoded PAYMENT-REQUIRED response header. Retry with a matching X-PAYMENT header."},"413":{"description":"Request body over 10KiB. Errors use the uniform envelope { \"error\": { \"code\", \"message\", \"requestId\" } }."},"429":{"description":"Rate limited. Errors use the uniform envelope { \"error\": { \"code\", \"message\", \"requestId\" } }."}}}},"/v1/wallet":{"post":{"operationId":"scanWallet","summary":"Structural safety scan of a Base wallet address (paid, $0.01 USDC per request)","description":"Deterministic on-chain structural-safety report for a Base address: contract detection, verification status, proxy/owner/privileged-function analysis. Behavioral signals (age, activity, funding) not yet included. Keyless x402-native payment — no signup, no API key. Score 0-100, higher = structurally safer. See free real samples before paying: GET /samples/index.json","x-x402":{"x402Version":2,"scheme":"exact","network":"eip155:8453","amount":"10000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x332DbF15a8Bcca8eEB4390b380202360F4f45401","maxTimeoutSeconds":300,"priceUsdc":"$0.01"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletRequest"}}}},"responses":{"200":{"description":"WalletReport. Deterministic for identical inputs within the cache window; the report's `cache` field carries hit/age metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletReport"}}}},"400":{"description":"Invalid request body. Errors use the uniform envelope { \"error\": { \"code\", \"message\", \"requestId\" } }."},"402":{"description":"Payment required (x402 v2). Requirements — including the bazaar discovery extension — are advertised in the base64-encoded PAYMENT-REQUIRED response header. Retry with a matching X-PAYMENT header."},"413":{"description":"Request body over 10KiB. Errors use the uniform envelope { \"error\": { \"code\", \"message\", \"requestId\" } }."},"429":{"description":"Rate limited. Errors use the uniform envelope { \"error\": { \"code\", \"message\", \"requestId\" } }."}}}}},"components":{"schemas":{"ScanRequest":{"type":"object","properties":{"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["chainId","address"],"additionalProperties":false},"RiskReport":{"type":"object","properties":{"schemaVersion":{"type":"number","const":3},"requestId":{"type":"string"},"chainId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"address":{"type":"string","pattern":"^0x[0-9a-f]{40}$"},"verdict":{"type":"string","enum":["low_risk","medium_risk","high_risk","inconclusive"]},"score":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pass","fail","skip","error"]},"summary":{"type":"string"},"evidence":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"durationMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","status"],"additionalProperties":false}},"generatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"engine":{"type":"object","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"cache":{"type":"object","properties":{"hit":{"type":"boolean"},"ageSeconds":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["hit","ageSeconds"],"additionalProperties":false},"scoring":{"type":"object","properties":{"configVersion":{"type":"string"},"penalties":{"type":"array","items":{"type":"object","properties":{"checkId":{"type":"string"},"points":{"type":"number"},"reason":{"type":"string"}},"required":["checkId","points","reason"],"additionalProperties":false}}},"required":["configVersion","penalties"],"additionalProperties":false},"findings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"severity":{"type":"string","enum":["info","caution"]},"title":{"type":"string","minLength":1,"maxLength":120},"detail":{"type":"string","minLength":1,"maxLength":500}},"required":["id","severity","title","detail"],"additionalProperties":false}},"enrichment":{"type":"object","properties":{"model":{"type":"string"},"latencyMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["model","latencyMs"],"additionalProperties":false},"context":{"type":"object","properties":{"knownAsset":{"type":"boolean"}},"required":["knownAsset"],"additionalProperties":false}},"required":["schemaVersion","requestId","chainId","address","verdict","score","checks","generatedAt","engine","context"],"additionalProperties":false},"WalletRequest":{"type":"object","properties":{"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["address"],"additionalProperties":false},"WalletReport":{"type":"object","properties":{"schemaVersion":{"type":"number","const":1},"requestId":{"type":"string"},"chainId":{"type":"number","const":8453},"address":{"type":"string","pattern":"^0x[0-9a-f]{40}$"},"verdict":{"type":"string","enum":["low_risk","medium_risk","high_risk","inconclusive"]},"score":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pass","fail","skip","error"]},"summary":{"type":"string"},"evidence":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"durationMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","status"],"additionalProperties":false}},"generatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"engine":{"type":"object","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"cache":{"type":"object","properties":{"hit":{"type":"boolean"},"ageSeconds":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["hit","ageSeconds"],"additionalProperties":false},"scoring":{"type":"object","properties":{"configVersion":{"type":"string"},"penalties":{"type":"array","items":{"type":"object","properties":{"checkId":{"type":"string"},"points":{"type":"number"},"reason":{"type":"string"}},"required":["checkId","points","reason"],"additionalProperties":false}}},"required":["configVersion","penalties"],"additionalProperties":false},"findings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"severity":{"type":"string","enum":["info","caution"]},"title":{"type":"string","minLength":1,"maxLength":120},"detail":{"type":"string","minLength":1,"maxLength":500}},"required":["id","severity","title","detail"],"additionalProperties":false}},"enrichment":{"type":"object","properties":{"model":{"type":"string"},"latencyMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["model","latencyMs"],"additionalProperties":false}},"required":["schemaVersion","requestId","chainId","address","verdict","score","checks","generatedAt","engine"],"additionalProperties":false}}}}