{ "openapi": "3.1.0", "info": { "title": "Reputa API", "version": "1", "description": "On-chain wallet risk & security intelligence (Ethereum mainnet). Read-only. Free: crisis-check, ENS resolve, health, and teaser reads. Paid per-use via x402 (USDC on Polygon): full wallet scores, Safe security check, Safe owner details (all chains), deep approval scan, and the 2-year chain history.", "contact": { "url": "https://reputa.xyz" } }, "servers": [ { "url": "https://reputa.xyz" } ], "paths": { "/api/crisis-check": { "post": { "operationId": "crisisCheck", "summary": "Crisis Behaviour Check + security report for a wallet. Free.", "description": "Reconstructs how a wallet behaved across 6 real crises (Terra, Celsius, Voyager, FTX, Multichain, Humanity) and returns a security snapshot (approvals, flagged-address contact, protocol usage, concentration). Free, no auth. Rate limit 20/min per IP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM wallet address." } } } } } }, "responses": { "200": { "description": "Analysis result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "wallet": { "type": "string" }, "verdict": { "type": "string", "enum": [ "risk_avoider", "risk_manager", "risk_seeker" ] }, "reasonCodes": { "type": "array", "items": { "type": "object" }, "description": "Per-event reaction codes." }, "events": { "type": "array", "items": { "type": "object" } }, "context": { "type": "object", "description": "Turnover classification: long_term_holder | active_trader | high_turnover_entity." }, "security": { "type": "object", "description": "smartContractRisk, approvalRisk, nftApprovalRisk, protocolUsage, concentration." }, "healthSummary": { "type": "string" }, "recommendations": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid wallet address or body." }, "429": { "description": "Rate limited (20/min per IP)." }, "503": { "description": "Upstream data source not configured." } } } }, "/api/approvals": { "post": { "operationId": "deepApprovalScan", "summary": "Deep approval scan (full allowance history). Paid per-use via x402.", "description": "Returns the wallet's full ERC-20 approval history (deeper than the free scan's recent window). Payment via x402: an unpaid request returns HTTP 402 with PaymentRequirements; the caller signs an EIP-3009 USDC authorization (exact amount, single nonce, ~3-min validity), then retries with an X-PAYMENT header. Settle-before-deliver. Network: Polygon, USDC. Price is advertised in the 402 challenge. Rate limit 5/min and 50/day per IP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64 x402 payment payload (EIP-3009). Omit on the first call to receive the 402 challenge." } ], "responses": { "200": { "description": "Full approvalRisk (delivered only after successful settlement). Includes spenderGroups (approvals grouped per recipient with a severity traffic-light and held amounts), an at-risk breakdown (atRiskCount / atRiskHigh / atRiskMedium / atRiskLow, where at-risk = unlimited AND still held), and resolved Permit2 downstream delegations (real recipient, unlimited/limited, expiry)." }, "402": { "description": "Payment required. Body contains x402 PaymentRequirements (network, asset, price, payTo)." }, "429": { "description": "Rate limited." }, "502": { "description": "Payment could not be settled on-chain." } } } }, "/api/scores": { "post": { "operationId": "walletScores", "summary": "Full wallet scores (Security, Risk, Reputation) + traits. Paid per-use via x402.", "description": "Returns Security, Risk and Reputation scores with reason codes, profile traits (HODLer, DeFi-native, governance, staker, Safe/smart-account, or an entity type such as CEX/DEX/bridge/DAO) and a staking & governance breakdown. Payment via x402 (Polygon USDC): an unpaid request returns HTTP 402 with PaymentRequirements; the caller signs an EIP-3009 USDC authorization, then retries with an X-PAYMENT header. Settle-before-deliver. Ethereum mainnet.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64 x402 payment payload (EIP-3009). Omit on the first call to receive the 402 challenge." } ], "responses": { "200": { "description": "{ scores } (delivered only after successful settlement)." }, "402": { "description": "Payment required. Body contains x402 PaymentRequirements (network, asset, price, payTo)." }, "400": { "description": "Invalid wallet address or body." }, "429": { "description": "Rate limited." }, "502": { "description": "Payment could not be settled on-chain." } } } }, "/api/safe-check": { "post": { "operationId": "safeCheck", "summary": "Safe (Gnosis Safe) security check: version, guard, modules. Paid per-use via x402.", "description": "Reads on-chain the Safe version, whether a transaction guard is set, and which modules are enabled (named, or flagged as unknown). Only meaningful for addresses that are actually a Safe. Payment via x402 (Polygon USDC), settle-before-deliver.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64 x402 payment payload (EIP-3009). Omit on the first call to receive the 402 challenge." } ], "responses": { "200": { "description": "{ safe, security } (delivered only after successful settlement)." }, "402": { "description": "Payment required. Body contains x402 PaymentRequirements." }, "400": { "description": "Invalid wallet address or body." }, "429": { "description": "Rate limited." }, "502": { "description": "Payment could not be settled on-chain." } } } }, "/api/safe-owner": { "post": { "operationId": "safeOwner", "summary": "Reverse lookup: Safes an address co-controls. Teaser free; full details paid via x402.", "description": "Without details=true, returns a FREE Ethereum-only count of Safes the address owns/signs (teaser, locked:true). With details=true, returns the full breakdown across all supported chains including the Safe addresses, paid per-use via x402 (Polygon USDC), settle-before-deliver.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "details": { "type": "boolean", "description": "false (default) = free Ethereum-only count. true = paid full breakdown across all chains." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64 x402 payment payload (EIP-3009). Only needed when details=true." } ], "responses": { "200": { "description": "Teaser (locked:true, Ethereum count) when details is not set; full breakdown after settlement when details=true." }, "402": { "description": "Payment required (only when details=true)." }, "400": { "description": "Invalid wallet address or body." }, "429": { "description": "Rate limited." }, "502": { "description": "Payment could not be settled on-chain." } } } }, "/api/chain-history": { "post": { "operationId": "chainHistory", "summary": "Historical ETH/WETH distribution across chains. 3/6/12mo free; 24mo paid via x402.", "description": "Returns the wallet's ETH/WETH distribution across networks as it was `months` ago. months must be 3, 6, 12 or 24. The 3/6/12-month reads are free; the 24-month (2-year) deep read is paid per-use via x402 (Polygon USDC), settle-before-deliver.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet", "months" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "months": { "type": "integer", "enum": [ 3, 6, 12, 24 ], "description": "Look-back window in months. 3/6/12 are free; 24 is the paid deep read." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64 x402 payment payload (EIP-3009). Only needed for months=24." } ], "responses": { "200": { "description": "{ apiVersion, wallet, months, chainDistribution }. For months=24 delivered only after successful settlement." }, "402": { "description": "Payment required (only for months=24 when x402 is enabled)." }, "400": { "description": "Invalid wallet address, body, or months not in {3,6,12,24}." }, "429": { "description": "Rate limited." }, "502": { "description": "Payment could not be settled on-chain." } } } }, "/api/full-report": { "post": { "operationId": "fullReport", "summary": "Bundled full report (scores + Safe + owner + approvals + 2-year history) in one paid call.", "description": "Runs every paid capability in a single request against a single x402 payment: wallet scores (Security/Risk/Reputation + traits + staking/governance), Safe config (version/guard/modules), which Safes the address co-controls (all chains), deep ERC-20 approval history, and the 2-year chain distribution. Bundled price (default = single-scan price x 5; override with X402_FULL_REPORT_PRICE_USD). Settle-before-deliver. Ethereum mainnet.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64 x402 payment payload (EIP-3009). Omit on the first call to receive the 402 challenge." } ], "responses": { "200": { "description": "{ scores, safe, owner, approvalRisk, chainHistory } (delivered only after successful settlement)." }, "402": { "description": "Payment required. Body contains x402 PaymentRequirements (bundled price)." }, "400": { "description": "Invalid wallet address or body." }, "429": { "description": "Rate limited." }, "502": { "description": "Payment could not be settled on-chain." } } } }, "/api/resolve": { "get": { "operationId": "resolveName", "summary": "Resolve an ENS name to an address. Free.", "description": "Resolves an ENS name (e.g. vitalik.eth) to its EVM address. Free, rate-limited.", "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "ENS name to resolve, e.g. vitalik.eth." } ], "responses": { "200": { "description": "{ address } or null when the name does not resolve." }, "400": { "description": "Missing or invalid name." }, "429": { "description": "Rate limited." } } } }, "/api/health": { "get": { "operationId": "health", "summary": "Service + paywall status. Free.", "description": "Public status endpoint (no secrets). Returns { ok, paywall: on|off, network, priceUsd, rateLimit }. Returns HTTP 503 when the x402 paywall is off (e.g. SCAN_PAYMENT_RECEIVER missing) so uptime monitors can alert.", "responses": { "200": { "description": "Healthy; paywall on." }, "503": { "description": "Paywall off (deploy misconfiguration) - all paid features would be free." } } } }, "/api/cover/v1/analyses": { "get": { "operationId": "coverAnalyses", "summary": "Catalog of DeFi cover analyses. Free.", "description": "Free catalog of all DeFi cover (insurance) analyses: Assecura score + band, covered protocol, coverage-gap counts, red flags, cheapest annual premium, analysis date. Discovery for agents.", "responses": { "200": { "description": "{ apiVersion, count, disclaimer, analyses[] }" } } } }, "/api/cover/v1/analyses/{provider}/{product}": { "get": { "operationId": "coverAnalysis", "summary": "Full DeFi cover analysis for one product. Paid (x402).", "description": "Full structured cover analysis: Assecura score across 7 categories, real-risk-fit and coverage gap map (clause by clause), claims process and payout history, capital adequacy, red flags, sources. Free teaser in the 402 body; full via x402. The receipt is shared with the web unlock.", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Provider slug, e.g. nexus-mutual." }, { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product slug, e.g. uniswap-v3 (from the catalog)." } ], "responses": { "200": { "description": "Full structured analysis (after payment or with a valid receipt)." }, "402": { "description": "Payment required: x402 PaymentRequirements plus a free teaser." }, "404": { "description": "Unknown cover analysis." } } } } }, "x-payment": { "protocol": "x402", "network": "polygon", "asset": "USDC", "flow": "HTTP 402 -> sign EIP-3009 transferWithAuthorization -> retry with X-PAYMENT header", "paid": [ "/api/scores", "/api/safe-check", "/api/approvals", "/api/safe-owner (details=true)", "/api/chain-history (months=24)", "/api/full-report (bundle)" ], "free": [ "/api/crisis-check", "/api/resolve", "/api/health", "/api/safe-owner (teaser)", "/api/chain-history (months=3,6,12)" ] }, "x-mcp": { "available": true, "tools": [ "reputa_analyze_wallet", "reputa_wallet_scores", "reputa_deep_approval_scan", "reputa_safe_check", "reputa_safe_owner", "reputa_chain_history", "reputa_full_report" ], "note": "An MCP server (mcp/) exposes these endpoints as agent tools with optional autonomous x402 payment (set REPUTA_PAYER_PRIVATE_KEY)." } }