{"openapi":"3.1.0","info":{"title":"Base Token Lens","version":"1.1.0","description":"Evidence-based token risk screening on Base (8453). Risk score is not safety probability. Unknown does not mean clear."},"servers":[{"url":"https://base-token-lens-phs6048.amazonlightsail.com"}],"paths":{"/api/v1/scan":{"get":{"operationId":"scanBaseToken","summary":"Free summary of token risk signals","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"Summary; may have unknown risk band or null score","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Summary"}}}},"400":{"description":"Invalid address"},"429":{"description":"Rate limit"},"503":{"description":"Providers unavailable"}}}},"/api/v1/report":{"get":{"operationId":"getDetailedBaseTokenReport","summary":"Detailed evidence report; 0.001 USDC via x402 v2","description":"PAYMENT-REQUIRED and PAYMENT-RESPONSE are base64 JSON. Use an x402 client; arbitrary receipts are not accepted. Read /api/v1/config for current availability. Non-2xx report responses do not settle in the authorization payment flow.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Report after successful settlement","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"Invalid address"},"402":{"description":"Payment required or rejected","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"429":{"description":"Rate limit"},"503":{"description":"Payments not activated, data insufficient, or provider error"}}}},"/api/v1/config":{"get":{"operationId":"getServiceConfiguration","responses":{"200":{"description":"Payment mode, chain, exact price, recipient and builder code"}}}},"/api/v1/pretrade":{"get":{"operationId":"checkBaseTokenBeforeBuy","summary":"Free read-only pre-buy policy gate","description":"pass means only that the screening policy passed; never a safety guarantee or trade. Missing required evidence, source failure, stale data or medium privileged-control risk requires review. High/critical risks block regardless of custom thresholds.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Nonzero Base token contract address.","example":"0x4200000000000000000000000000000000000006"}},{"name":"maxRiskScore","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100,"default":19}},{"name":"minCoveragePercent","in":"query","required":false,"schema":{"type":"number","minimum":70,"maximum":100,"default":90}},{"name":"minLiquidityUsd","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":1000000000,"default":25000}},{"name":"maxBuyTaxPercent","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100,"default":5}},{"name":"maxSellTaxPercent","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100,"default":5}}],"responses":{"200":{"description":"Policy gate and free summary; includes status=ok. No trade executed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pretrade"}}}},"400":{"description":"Invalid address, policy, JSON or unknown / duplicate input key. No provider request performed."},"413":{"description":"Body exceeds 4096 bytes"},"415":{"description":"JSON content type required"},"429":{"description":"Inspection budget exceeded; respect Retry-After."},"503":{"description":"All item loads failed or all data sources unavailable. Fail closed."}}}},"/api/v1/batch":{"get":{"operationId":"checkBaseTokensBatchGet","summary":"Free summary and policy decisions for 1–5 tokens","parameters":[{"name":"addresses","in":"query","required":true,"description":"Comma-separated nonzero Base token addresses; max 5 input entries. Duplicate loads deduplicated.","schema":{"type":"string"},"example":"0x4200000000000000000000000000000000000006,0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},{"name":"maxRiskScore","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100,"default":19}},{"name":"minCoveragePercent","in":"query","required":false,"schema":{"type":"number","minimum":70,"maximum":100,"default":90}},{"name":"minLiquidityUsd","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":1000000000,"default":25000}},{"name":"maxBuyTaxPercent","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100,"default":5}},{"name":"maxSellTaxPercent","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100,"default":5}}],"responses":{"200":{"description":"Input order preserved. Check every item status and decision; HTTP 200 can contain errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"400":{"description":"Invalid address, policy, JSON or unknown / duplicate input key. No provider request performed."},"413":{"description":"Body exceeds 4096 bytes"},"415":{"description":"JSON content type required"},"429":{"description":"Inspection budget exceeded; respect Retry-After."},"503":{"description":"All item loads failed or all data sources unavailable. Fail closed."}}},"post":{"operationId":"checkBaseTokensBatch","summary":"Free batch token pre-buy screening","description":"Max 5 inputs, concurrency 2, no trading/signatures. 4096-byte JSON limit. A unique token costs one inspection from the shared instance-local rate budget. Results can expire while other items load; recheck each timestamp.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"},"example":{"addresses":["0x4200000000000000000000000000000000000006","0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],"policy":{"minLiquidityUsd":50000}}}}},"responses":{"200":{"description":"Input order preserved. Check every item status and decision; HTTP 200 can contain errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"400":{"description":"Invalid address, policy, JSON or unknown / duplicate input key. No provider request performed."},"413":{"description":"Body exceeds 4096 bytes"},"415":{"description":"JSON content type required"},"429":{"description":"Inspection budget exceeded; respect Retry-After."},"503":{"description":"All item loads failed or all data sources unavailable. Fail closed."}}}}},"components":{"schemas":{"Assessment":{"type":"object","required":["riskScore","band","coveragePercent","honeypot","simulationSuccess","isSafetyGuarantee"],"properties":{"riskScore":{"type":["integer","null"],"minimum":0,"maximum":100},"band":{"enum":["low","medium","high","critical","unknown"]},"coveragePercent":{"type":"integer","minimum":0,"maximum":100},"honeypot":{"type":["boolean","null"]},"simulationSuccess":{"type":["boolean","null"]},"isSafetyGuarantee":{"const":false}}},"Signal":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"enum":["risk","clear","unknown"]},"severity":{"enum":["low","medium","high","critical"]}}},"Summary":{"type":"object","required":["schemaVersion","modelVersion","chain","address","checkedAt","expiresAt","assessment","signals","sources","limitations"],"properties":{"schemaVersion":{"const":"1.0.0"},"modelVersion":{"type":"string"},"chain":{"type":"object","properties":{"id":{"const":8453},"name":{"const":"base"}}},"address":{"type":"string"},"token":{"type":"object"},"checkedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"assessment":{"$ref":"#/components/schemas/Assessment"},"signals":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}},"sources":{"type":"array","items":{"type":"object"}},"limitations":{"type":"array","items":{"type":"string"}}}},"Report":{"type":"object","required":["assessment","checks","sources","checkedAt","limitations"],"properties":{"assessment":{"$ref":"#/components/schemas/Assessment"},"checks":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Signal"},{"type":"object","properties":{"penalty":{"type":"integer"},"evidence":{"type":"array","items":{"type":"object"}}}}]}},"sources":{"type":"array","items":{"type":"object"}},"checkedAt":{"type":"string","format":"date-time"},"limitations":{"type":"array","items":{"type":"string"}}}},"PretradePolicy":{"type":"object","additionalProperties":false,"properties":{"maxRiskScore":{"type":"number","minimum":0,"maximum":100,"default":19},"minCoveragePercent":{"type":"number","minimum":70,"maximum":100,"default":90},"minLiquidityUsd":{"type":"number","minimum":0,"maximum":1000000000,"default":25000},"maxBuyTaxPercent":{"type":"number","minimum":0,"maximum":100,"default":5},"maxSellTaxPercent":{"type":"number","minimum":0,"maximum":100,"default":5}}},"Pretrade":{"type":"object","required":["schemaVersion","chain","address","checkedAt","expiresAt","decision","eligibleForQuote","tradeExecuted","isSafetyGuarantee","policy","reasons","summary"],"properties":{"schemaVersion":{"const":"1.0.0"},"chain":{"type":"object","properties":{"id":{"const":8453}}},"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Nonzero Base token contract address.","example":"0x4200000000000000000000000000000000000006"},"checkedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"evaluatedAt":{"type":"string","format":"date-time"},"decision":{"enum":["pass","review","block"]},"eligibleForQuote":{"type":"boolean","description":"True only for policy pass. Not safety or trade authorization. Recheck timestamps before use."},"tradeExecuted":{"const":false},"isSafetyGuarantee":{"const":false},"policy":{"$ref":"#/components/schemas/PretradePolicy"},"reasons":{"type":"array","items":{"type":"object","required":["code","level","checkId"],"properties":{"code":{"enum":["STALE_EVIDENCE","SOURCE_UNAVAILABLE","UNKNOWN_CHECK","HIGH_RISK_SIGNAL","RISK_REQUIRES_REVIEW","HONEYPOT_DETECTED","SELL_SIMULATION_UNCONFIRMED","CONFLICTING_EVIDENCE","INSUFFICIENT_EVIDENCE","RISK_SCORE_LIMIT","COVERAGE_BELOW_MINIMUM","LIQUIDITY_UNKNOWN","LIQUIDITY_BELOW_MINIMUM","TAX_UNKNOWN","TAX_ABOVE_MAXIMUM"]},"level":{"enum":["review","block"]},"checkId":{"type":["string","null"]}}}},"summary":{"$ref":"#/components/schemas/Summary"},"detailedReportPath":{"type":"string"}}},"BatchRequest":{"type":"object","additionalProperties":false,"required":["addresses"],"properties":{"addresses":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Nonzero Base token contract address.","example":"0x4200000000000000000000000000000000000006"}},"policy":{"$ref":"#/components/schemas/PretradePolicy"}}},"BatchResponse":{"type":"object","required":["schemaVersion","requestedCount","uniqueCount","complete","results"],"properties":{"schemaVersion":{"const":"1.0.0"},"chain":{"type":"object","properties":{"id":{"const":8453}}},"requestedCount":{"type":"integer","minimum":1,"maximum":5},"uniqueCount":{"type":"integer","minimum":1,"maximum":5},"complete":{"type":"boolean","description":"False if any item has status=error; unknown checks may also exist when true."},"policy":{"$ref":"#/components/schemas/PretradePolicy"},"results":{"type":"array","maxItems":5,"items":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/Pretrade"},{"type":"object","required":["status"],"properties":{"status":{"const":"ok"}}}]},{"type":"object","required":["address","status","decision","eligibleForQuote","error"],"properties":{"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Nonzero Base token contract address.","example":"0x4200000000000000000000000000000000000006"},"status":{"const":"error"},"decision":{"enum":["review","block"]},"eligibleForQuote":{"const":false},"tradeExecuted":{"const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}]}}}}}}}