{"openapi":"3.1.0","info":{"title":"Web3 Scanner — Wallet Risk & Sanctions Screening API","version":"1.0.0","description":"Paid compliance APIs for crypto off-ramp and AML/KYC workflows. Two capabilities: (1) Wallet risk scan -- screen any EVM wallet address or ENS name for on-chain risk signals (sanctions, scams, mixers, phishing) powered by Web3 Antivirus; two modes: full scan (~9s) and quick-scan (~350ms). (2) Sanctions screening -- screen any person, company, or entity name against the OpenSanctions Default dataset (1.3M+ targeted entries from OFAC SDN, EU Financial Sanctions, UN Consolidated List, and 330+ global sources). Pay $0.01 USDC per wallet scan, $0.04 USDC per sanctions check, using the x402 protocol on Base, Polygon, Arbitrum, or Solana. No API keys or accounts required.","x-guidance":"Two compliance tools available. Wallet risk: pay $0.01 USDC per call -- use /api/public/quick-scan (fast, ~350ms) or /api/public/scan (full, ~9s); key field is shouldFlag -- any non-zero toxicScore means flagged. Sanctions screening: pay $0.04 USDC per call -- use /api/public/sanctions-check; key field is sanctioned -- true means the name matched an OFAC/EU/UN or other sanctions list entry. Each endpoint has network-specific variants: no suffix = Base/Polygon/Arbitrum (CDP), /solana = Solana (CDP)."},"servers":[{"url":"https://scan.madhousewallet.com"}],"paths":{"/api/public/scan":{"get":{"operationId":"scanWalletEvm","summary":"Scan EVM wallet for on-chain risk signals","description":"Scan any EVM wallet address or ENS name for on-chain risk signals. Returns a toxic score (0-1), risk level (PASS/LOW/MIDDLE/CRITICAL), and flagged metrics powered by Web3 Antivirus. Use shouldFlag for off-ramp compliance: any score above 0 is flagged. Pay with USDC on Base (eip155:8453), Polygon (eip155:137), or Arbitrum (eip155:42161).","x-payment-info":{"pricingMode":"fixed","price":"0.01","currency":"USD","protocols":["x402"],"network":"eip155:8453"},"x-payment-networks":[{"network":"eip155:8453","label":"Base Mainnet","usdc":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},{"network":"eip155:137","label":"Polygon Mainnet","usdc":"0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"},{"network":"eip155:42161","label":"Arbitrum One","usdc":"0xaf88d065e77c8cC2239327C5EDb3A432268e5831"}],"parameters":[{"name":"address","in":"query","required":true,"description":"EVM wallet address (0x-prefixed, checksummed) or ENS name to scan.","example":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","schema":{"type":"string"}}],"responses":{"200":{"description":"Wallet scan result","content":{"application/json":{"schema":{"type":"object","required":["address","toxicScore","riskLevel","shouldFlag","flaggedMetrics"],"properties":{"address":{"type":"string","description":"The queried wallet address (checksummed or ENS-resolved)."},"toxicScore":{"type":"number","description":"Normalized risk score from 0 (clean) to 1 (critical). NOTE: the API may return scores as integers 0-100 for confirmed bad actors; always normalize with score > 1 ? score / 100 : score."},"riskLevel":{"type":"string","enum":["PASS","LOW","MIDDLE","CRITICAL"],"description":"PASS = score 0; LOW = 0-0.40; MIDDLE = 0.41-0.80; CRITICAL >= 0.81."},"shouldFlag":{"type":"boolean","description":"True if toxicScore > 0. Off-ramp compliance rule: only exact score 0 passes; any non-zero score must be flagged."},"flaggedMetrics":{"type":"array","description":"Risk signals that contributed to the score. Empty array means all 15 risk categories are clean.","items":{"type":"object","properties":{"name":{"type":"string","description":"Risk category name. Known values: known_scammer, sanction_address, blacklist, initiator_scam_transactions, suspicious_dex_pair_deployer, suspicious_deployer, attack_money_target, zero_address_risk, rug_pull, rug_pull_trader, sanction_address_communication, fake_phishing_contract_communication, fake_phishing_transfer, mixer_transfers, non_kyc_transfers."},"risk":{"type":"number","description":"Risk contribution. >0 means flagged."},"type":{"type":"string","enum":["absolute","volume"],"description":"absolute = binary yes/no flag. volume = scaled by USD transaction volume."},"description":{"type":"string"},"txsCount":{"type":"number","description":"Number of flagged transactions (volume metrics only)."},"incomingMoneyUSD":{"type":"number","description":"Flagged incoming USD (volume metrics only)."},"outgoingMoneyUSD":{"type":"number","description":"Flagged outgoing USD (volume metrics only)."}}}},"ens":{"type":["string","null"],"description":"Resolved ENS name if the address has one, otherwise null."},"isContract":{"type":"boolean","description":"True if the address is a smart contract, not an EOA."},"addressExists":{"type":"boolean","description":"True if the address has any on-chain transaction history."}}},"example":{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","toxicScore":0.04,"riskLevel":"LOW","shouldFlag":true,"flaggedMetrics":[{"name":"non_kyc_transfers","risk":0.03,"type":"volume","description":"Transacted with non-KYC exchanges","txsCount":344,"incomingMoneyUSD":15722.47,"outgoingMoneyUSD":2484.15}],"ens":"vitalik.eth","isContract":false,"addressExists":true}}}},"402":{"description":"Payment required. Pay $0.01 USDC via x402 on Base (eip155:8453), Polygon (eip155:137), or Arbitrum (eip155:42161)."}}}},"/api/public/scan/solana":{"get":{"operationId":"scanWalletSolana","summary":"Scan EVM wallet for on-chain risk signals (pay with Solana USDC)","description":"Identical scan to /api/public/scan but payment is accepted in USDC on Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Scan result is the same -- EVM wallet history analyzed by Web3 Antivirus. Use shouldFlag for off-ramp compliance: any score above 0 is flagged.","x-payment-info":{"pricingMode":"fixed","price":"0.01","currency":"USD","protocols":["x402"],"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"},"parameters":[{"name":"address","in":"query","required":true,"description":"EVM wallet address (0x-prefixed, checksummed) or ENS name to scan.","example":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","schema":{"type":"string"}}],"responses":{"200":{"description":"Wallet scan result","content":{"application/json":{"schema":{"type":"object","required":["address","toxicScore","riskLevel","shouldFlag","flaggedMetrics"],"properties":{"address":{"type":"string","description":"The queried wallet address (checksummed or ENS-resolved)."},"toxicScore":{"type":"number","description":"Normalized risk score from 0 (clean) to 1 (critical). NOTE: the API may return scores as integers 0-100 for confirmed bad actors; always normalize with score > 1 ? score / 100 : score."},"riskLevel":{"type":"string","enum":["PASS","LOW","MIDDLE","CRITICAL"],"description":"PASS = score 0; LOW = 0-0.40; MIDDLE = 0.41-0.80; CRITICAL >= 0.81."},"shouldFlag":{"type":"boolean","description":"True if toxicScore > 0. Off-ramp compliance rule: only exact score 0 passes; any non-zero score must be flagged."},"flaggedMetrics":{"type":"array","description":"Risk signals that contributed to the score.","items":{"type":"object"}},"ens":{"type":["string","null"],"description":"Resolved ENS name if the address has one, otherwise null."},"isContract":{"type":"boolean","description":"True if the address is a smart contract, not an EOA."},"addressExists":{"type":"boolean","description":"True if the address has any on-chain transaction history."}}},"example":{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","toxicScore":0.04,"riskLevel":"LOW","shouldFlag":true,"flaggedMetrics":[{"name":"non_kyc_transfers","risk":0.03,"type":"volume","description":"Transacted with non-KYC exchanges","txsCount":344,"incomingMoneyUSD":15722.47,"outgoingMoneyUSD":2484.15}],"ens":"vitalik.eth","isContract":false,"addressExists":true}}}},"402":{"description":"Payment required. Use x402 protocol to pay $0.01 USDC on Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)."}}}},"/api/public/quick-scan":{"get":{"operationId":"quickScanWalletEvm","summary":"Fast wallet risk check (~350ms) — pay with EVM USDC","description":"Fast, low-latency wallet risk check for any EVM address or ENS name using Web3 Antivirus quick-scan. Returns in ~350ms vs ~9s for the full scan. Returns a toxic score, risk level, and which risk flags fired. No USD volume breakdown — use /api/public/scan for full details. For off-ramp compliance: use shouldFlag to block or escalate. Accepts USDC on Base (eip155:8453), Polygon (eip155:137), or Arbitrum (eip155:42161).","x-payment-info":{"pricingMode":"fixed","price":"0.01","currency":"USD","protocols":["x402"],"network":"eip155:8453"},"x-payment-networks":[{"network":"eip155:8453","label":"Base Mainnet","usdc":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},{"network":"eip155:137","label":"Polygon Mainnet","usdc":"0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"},{"network":"eip155:42161","label":"Arbitrum One","usdc":"0xaf88d065e77c8cC2239327C5EDb3A432268e5831"}],"parameters":[{"name":"address","in":"query","required":true,"description":"EVM wallet address (0x-prefixed, checksummed) or ENS name to scan.","example":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","schema":{"type":"string"}}],"responses":{"200":{"description":"Quick scan result","content":{"application/json":{"schema":{"type":"object","required":["address","toxicScore","riskLevel","shouldFlag","traits"],"properties":{"address":{"type":"string","description":"The queried wallet address as provided."},"toxicScore":{"type":"number","description":"Normalized risk score from 0 (clean) to 1 (critical). Raw API may return 0-100 integers for confirmed bad actors; always normalize with score > 1 ? score / 100 : score."},"riskLevel":{"type":"string","enum":["PASS","LOW","MIDDLE","CRITICAL"],"description":"PASS = score 0; LOW = 0-0.40; MIDDLE = 0.41-0.80; CRITICAL >= 0.81."},"shouldFlag":{"type":"boolean","description":"True if toxicScore > 0. Only exact score 0 passes for off-ramp compliance."},"traits":{"type":"array","description":"Risk flags that fired. Empty array means clean. No USD volume fields -- use /api/public/scan for full breakdown.","items":{"type":"object","properties":{"name":{"type":"string","description":"Risk category name. Known values: known_scammer, sanction_address, blacklist, initiator_scam_transactions, suspicious_dex_pair_deployer, suspicious_deployer, attack_money_target, zero_address_risk, rug_pull, rug_pull_trader, sanction_address_communication, fake_phishing_contract_communication, fake_phishing_transfer, mixer_transfers, non_kyc_transfers."},"risk":{"type":"number","description":"Risk contribution. >0 means flagged."},"txsCount":{"type":"number","description":"Number of transactions related to this flag."},"description":{"type":"string","description":"Human-readable explanation of what this flag detected."}}}}}},"example":{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","toxicScore":0.95,"riskLevel":"CRITICAL","shouldFlag":true,"traits":[{"name":"initiator_scam_transactions","risk":0.95,"txsCount":1,"description":"The address has initiated scam airdrops or poisoning attacks designed to create deceptive or misleading transaction patterns."}]}}}},"402":{"description":"Payment required. Pay $0.01 USDC via x402 on Base (eip155:8453), Polygon (eip155:137), or Arbitrum (eip155:42161)."}}}},"/api/public/quick-scan/solana":{"get":{"operationId":"quickScanWalletSolana","summary":"Fast wallet risk check (~350ms) — pay with Solana USDC","description":"Same fast risk check as /api/public/quick-scan but payment accepted in USDC on Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Returns in ~350ms. Returns a toxic score and which risk flags fired. Use shouldFlag to block or escalate for off-ramp compliance.","x-payment-info":{"pricingMode":"fixed","price":"0.01","currency":"USD","protocols":["x402"],"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"},"parameters":[{"name":"address","in":"query","required":true,"description":"EVM wallet address (0x-prefixed, checksummed) or ENS name to scan.","example":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","schema":{"type":"string"}}],"responses":{"200":{"description":"Quick scan result","content":{"application/json":{"schema":{"type":"object","required":["address","toxicScore","riskLevel","shouldFlag","traits"],"properties":{"address":{"type":"string","description":"The queried wallet address as provided."},"toxicScore":{"type":"number","description":"Normalized risk score from 0 (clean) to 1 (critical). Raw API may return 0-100 integers; always normalize with score > 1 ? score / 100 : score."},"riskLevel":{"type":"string","enum":["PASS","LOW","MIDDLE","CRITICAL"],"description":"PASS = score 0; LOW = 0-0.40; MIDDLE = 0.41-0.80; CRITICAL >= 0.81."},"shouldFlag":{"type":"boolean","description":"True if toxicScore > 0. Only exact score 0 passes for off-ramp compliance."},"traits":{"type":"array","description":"Risk flags that fired. Empty array means clean.","items":{"type":"object","properties":{"name":{"type":"string","description":"Risk category name."},"risk":{"type":"number","description":"Risk contribution. >0 means flagged."},"txsCount":{"type":"number","description":"Number of transactions related to this flag."},"description":{"type":"string","description":"Human-readable explanation of what this flag detected."}}}}}},"example":{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","toxicScore":0.95,"riskLevel":"CRITICAL","shouldFlag":true,"traits":[{"name":"initiator_scam_transactions","risk":0.95,"txsCount":1,"description":"The address has initiated scam airdrops or poisoning attacks designed to create deceptive or misleading transaction patterns."}]}}}},"402":{"description":"Payment required. Use x402 protocol to pay $0.01 USDC on Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)."}}}},"/api/public/sanctions-check":{"get":{"operationId":"sanctionsCheckEvm","summary":"Screen person or entity against OpenSanctions — pay with EVM USDC","description":"Screen any person, company, vessel, or other entity name against the OpenSanctions Default dataset: 1.3M+ targeted entries from OFAC SDN, EU Financial Sanctions, UN Consolidated List, and 330+ global sources. Updated weekly. Returns sanctioned: true/false plus entity type, risk topics (sanction, debarment, role.pep, crime.fin), matched data sources, and which input fields confirmed the match. Optional country (ISO-2), address, and birthDate params narrow false positives for common names. Use for AML/KYC pre-screening, crypto off-ramp compliance, and counterparty due diligence. Pay with USDC on Base (eip155:8453), Polygon (eip155:137), or Arbitrum (eip155:42161).","x-payment-info":{"pricingMode":"fixed","price":"0.04","currency":"USD","protocols":["x402"],"network":"eip155:8453"},"x-payment-networks":[{"network":"eip155:8453","label":"Base Mainnet","usdc":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},{"network":"eip155:137","label":"Polygon Mainnet","usdc":"0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"},{"network":"eip155:42161","label":"Arbitrum One","usdc":"0xaf88d065e77c8cC2239327C5EDb3A432268e5831"}],"parameters":[{"name":"name","in":"query","required":true,"description":"Full name of the person, company, or entity to screen.","example":"Viktor Bout","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"Optional ISO 3166-1 alpha-2 country code (e.g. US, RU, CN). Narrows false positives when both the query and the matched entity have a country.","example":"ru","schema":{"type":"string"}},{"name":"address","in":"query","required":false,"description":"Optional free-text address. Requires >= 2 strong tokens (length >= 3) to match a sanctioned address string.","example":"Moscow Russia","schema":{"type":"string"}},{"name":"birthDate","in":"query","required":false,"description":"Optional birth date: YYYY or YYYY-MM-DD. Partial dates supported (1967 matches 1967-01-13).","example":"1967-01-13","schema":{"type":"string"}}],"responses":{"200":{"description":"Screening result. sanctioned: true when one or more entities matched. matchCount indicates how many. Use country/birthDate params to narrow common names.","content":{"application/json":{"schema":{"type":"object","required":["sanctioned","name","matchCount","matches"],"properties":{"sanctioned":{"type":"boolean","description":"True when one or more entities passed all applied filters. False means clean."},"name":{"type":"string","description":"The name as submitted in the request."},"matchCount":{"type":"number","description":"Number of distinct entities that passed all filters. 0 when clean. Common names without country/birthDate may yield multiple matches."},"matches":{"type":"array","description":"All entities that passed the applied filters. Empty when sanctioned: false. Inspect matchedOn per entry to assess confidence.","items":{"type":"object","required":["entityId","caption","entityType","topics","matchedOn","datasets"],"properties":{"entityId":{"type":"string","description":"OpenSanctions identifier (NK-xxx or Wikidata Q-id)."},"caption":{"type":"string","description":"Canonical display name of the matched entity from OpenSanctions."},"entityType":{"type":"string","enum":["Person","Company","Organization","LegalEntity","Vessel","Other"],"description":"Type of the matched entity."},"topics":{"type":"array","items":{"type":"string"},"description":"Risk topic codes: sanction, debarment, role.pep, crime.fin, export.control, wanted, role.pol, role.rca."},"matchedOn":{"type":"array","items":{"type":"string","enum":["name","country","address","birthDate"]},"description":"Which input fields contributed. name is always present. High-confidence hits also include country and/or birthDate."},"datasets":{"type":"array","items":{"type":"string"},"description":"Up to 5 OpenSanctions source datasets, e.g. us_ofac_sdn, eu_financial_sanctions_files."}}}}}},"example":{"sanctioned":true,"name":"Viktor Bout","matchCount":1,"matches":[{"entityId":"Q314650","caption":"Viktor Anatolijevitch BOUT","entityType":"Person","topics":["role.pep","sanction","debarment"],"matchedOn":["name","country","birthDate"],"datasets":["us_ofac_sdn","us_trade_csl","eu_financial_sanctions_files"]}]}}}},"402":{"description":"Payment required. Pay $0.04 USDC via x402 on Base (eip155:8453), Polygon (eip155:137), or Arbitrum (eip155:42161)."},"503":{"description":"Sanctions database temporarily unavailable. Retry the request."}}}},"/api/public/sanctions-check/solana":{"get":{"operationId":"sanctionsCheckSolana","summary":"Screen person or entity against OpenSanctions — pay with Solana USDC","description":"Same OpenSanctions screening as /api/public/sanctions-check but payment accepted in USDC on Solana mainnet. Returns sanctioned: true/false plus entity type, risk topics, and source datasets. Optional country, address, birthDate params narrow false positives.","x-payment-info":{"pricingMode":"fixed","price":"0.04","currency":"USD","protocols":["x402"],"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"},"parameters":[{"name":"name","in":"query","required":true,"description":"Full name to screen.","example":"Viktor Bout","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"Optional ISO-2 country code.","example":"ru","schema":{"type":"string"}},{"name":"address","in":"query","required":false,"description":"Optional free-text address.","schema":{"type":"string"}},{"name":"birthDate","in":"query","required":false,"description":"Optional birth date YYYY or YYYY-MM-DD.","example":"1967-01-13","schema":{"type":"string"}}],"responses":{"200":{"description":"Screening result.","content":{"application/json":{"schema":{"type":"object","required":["sanctioned","name","matchCount","matches"],"properties":{"sanctioned":{"type":"boolean","description":"True when one or more entities matched. False means clean."},"name":{"type":"string","description":"The name as submitted."},"matchCount":{"type":"number","description":"Number of entities that passed all filters."},"matches":{"type":"array","items":{"type":"object","required":["entityId","caption","entityType","topics","matchedOn","datasets"],"properties":{"entityId":{"type":"string"},"caption":{"type":"string"},"entityType":{"type":"string","enum":["Person","Company","Organization","LegalEntity","Vessel","Other"]},"topics":{"type":"array","items":{"type":"string"}},"matchedOn":{"type":"array","items":{"type":"string","enum":["name","country","address","birthDate"]}},"datasets":{"type":"array","items":{"type":"string"}}}}}}},"example":{"sanctioned":true,"name":"Viktor Bout","matchCount":1,"matches":[{"entityId":"Q314650","caption":"Viktor Anatolijevitch BOUT","entityType":"Person","topics":["role.pep","sanction","debarment"],"matchedOn":["name","country","birthDate"],"datasets":["us_ofac_sdn"]}]}}}},"402":{"description":"Payment required. Use x402 on Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)."},"503":{"description":"Sanctions database temporarily unavailable."}}}}}}