{"openapi":"3.0.3","info":{"title":"SpotBlock Security API","version":"1.0.0","description":"Public threat detection and security endpoints: threat DB lookups, umbrella security checks, transaction harm analysis, real-time monitoring, and signature-gated deep scans.","contact":{"name":"SpotBlock","url":"https://spotblock.org"}},"servers":[{"url":"https://spotblock.org"}],"paths":{"/api/threat-check":{"get":{"description":"Check a single address against the SpotBlock threat DB.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"outcome":{"type":"string","enum":["threat","safe"]},"source":{"type":"string"}}}}}},"400":{"description":"Invalid or missing address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Threat check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"post":{"description":"Check a single address against the SpotBlock threat DB (JSON body).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"outcome":{"type":"string","enum":["threat","safe"]},"source":{"type":"string"}}}}}},"400":{"description":"Invalid or missing address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Threat check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/security-check":{"get":{"description":"Umbrella check on any selector (EOA / contract address / ENS name / tx hash): runs threat DB, report, live contract state, profile, monitoring, and tx-harm checks.","parameters":[{"name":"selector","in":"query","required":true,"schema":{"type":"string"}},{"name":"network","in":"query","required":false,"schema":{"type":"string","enum":["ethereum","sepolia"],"default":"ethereum"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"selector":{"type":"string"},"resolved":{"type":"object","properties":{"kind":{"type":"string","enum":["address","ens","txhash"]},"address":{"type":"string"},"txHash":{"type":"string"},"ensName":{"type":"string"}}},"network":{"type":"string","enum":["ethereum","sepolia"]},"verdict":{"type":"object","properties":{"outcome":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}},"checks":{"type":"object","properties":{"ens":{"type":"object"},"threat":{"type":"object"},"report":{"type":"object"},"contractState":{"type":"object"},"profile":{"type":"object"},"monitoring":{"type":"object"},"tx":{"type":"object"}}},"nextActions":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Missing or invalid selector.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded (20/min per IP).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Security check failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/tx-harm":{"post":{"description":"Analyze a mined transaction (hash) or an unsigned raw transaction for threat-DB involvement, token transfers, and internal calls (call-trace mode when RPC_TRACE_URL is configured).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"txHash":{"type":"string","description":"0x + 64 hex chars (mined tx)."},"rawTx":{"type":"string","description":"0x-prefixed raw signed tx."},"network":{"type":"string","enum":["ethereum","sepolia"],"default":"ethereum"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","properties":{"kind":{"type":"string","enum":["hash","raw"]},"network":{"type":"string","enum":["ethereum","sepolia"]}}},"resolved":{"type":"object","properties":{"txHash":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"valueWei":{"type":"string"},"methodSelector":{"type":"string"},"status":{"type":"object"},"blockNumber":{"type":"number"},"mined":{"type":"boolean"}}},"traceMode":{"type":"string","enum":["call-trace","receipt-logs"]},"traceDepth":{"type":"number"},"touched":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"object"}},"tokenTransfers":{"type":"array","items":{"type":"object"}},"internalCalls":{"type":"array","items":{"type":"object"}}}},"verdict":{"type":"object","properties":{"outcome":{"type":"string","enum":["harmful","suspicious","clean","unknown"]},"reasons":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"Invalid txHash/rawTx.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Transaction not found (unknown or pruned).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded (10/min per IP).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Tx analysis failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/rt-monitor/list":{"get":{"description":"List active wallet + contract real-time watches, merged and sorted newest first.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"watches":{"type":"array","items":{"type":"object"}},"projects":{"type":"array","items":{"type":"object"}},"ungrouped":{"type":"array","items":{"type":"object"}},"summary":{"type":"object"}}}}}},"500":{"description":"Failed to list monitored addresses.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/rt-monitor/status":{"get":{"description":"Wallet monitoring status and alerts for a single address.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"}},{"name":"includeActivity","in":"query","required":false,"schema":{"type":"string","description":"\"true\" to include info-severity activity entries."}},{"name":"skip","in":"query","required":false,"schema":{"type":"number","default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"number","default":30,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"isMonitored":{"type":"boolean"},"since":{"type":"string"},"riskAlertCount":{"type":"number"},"activityCount":{"type":"number"},"alerts":{"type":"array","items":{"type":"object"}},"activity":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to fetch monitoring status.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/rt-monitor/watch":{"post":{"description":"Register an address for real-time monitoring; eth_getCode chooses wallet vs contract watch. Optional protocol grouping label.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string"},"protocol":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"address":{"type":"string"},"monitorKind":{"type":"string","enum":["wallet","contract"]},"addressType":{"type":"string"},"monitorId":{"type":"string"},"alreadyMonitored":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid Ethereum address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to register address for monitoring.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/rt-monitor/stop":{"post":{"description":"Stop real-time monitoring for an address (wallet and contract watches).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"address":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to stop monitoring.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/rt-contract-monitor/status":{"get":{"description":"Contract monitoring status and alerts (including risk-engine threat-intel fields).","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"}},{"name":"includeActivity","in":"query","required":false,"schema":{"type":"string"}},{"name":"skip","in":"query","required":false,"schema":{"type":"number","default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"number","default":30,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"monitorKind":{"type":"string"},"isMonitored":{"type":"boolean"},"since":{"type":"string"},"riskAlertCount":{"type":"number"},"activityCount":{"type":"number"},"alerts":{"type":"array","items":{"type":"object"}},"activity":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to fetch contract monitoring status.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/rt-contract-monitor/state":{"get":{"description":"Live on-chain contract state: owner, paused flag, EIP-1967 proxy implementation/admin/beacon, reconstructed role holders.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"isContract":{"type":"boolean"},"owner":{"type":"string"},"paused":{"type":"boolean"},"isProxy":{"type":"boolean"},"implementation":{"type":"string"},"admin":{"type":"string"},"beacon":{"type":"string"},"roles":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to fetch contract state.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/vuln-scan/nonce":{"get":{"description":"Issue a nonce + issuedAt pair for signing a vulnerability-scan request. Rate limited 10/min per IP.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"nonce":{"type":"string"},"issuedAt":{"type":"string"}}}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/vuln-scan/scan":{"post":{"description":"Queue a vulnerability scan for a contract address. Requires a signature over the exact scan-request message built from the nonce fields.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet","address","chainId","nonce","issuedAt","signature"],"properties":{"wallet":{"type":"string"},"address":{"type":"string"},"chainId":{"type":"number"},"nonce":{"type":"string"},"issuedAt":{"type":"string"},"signature":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string"},"attached":{"type":"boolean"},"requeued":{"type":"boolean"}}}}}},"400":{"description":"Invalid input, expired signature, or non-contract address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Signature invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to start vulnerability scan.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/vuln-scan/status":{"get":{"description":"Poll a vulnerability scan request by id.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"chainId":{"type":"number"},"address":{"type":"string"},"kind":{"type":"string"},"result":{"type":"object"},"error":{"type":"string"}}}}}},"400":{"description":"Missing id.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to fetch scan status.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/super-analyst/nonce":{"get":{"description":"Issue a nonce + issuedAt pair for signing an AI deep-scan request. Rate limited 10/min per IP.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"nonce":{"type":"string"},"issuedAt":{"type":"string"}}}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/super-analyst/scan":{"post":{"description":"Queue an AI deep scan (simple or advanced). Signature-gated; daily caps: 3/day per wallet, 5/day per IP, 25/day global.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet","address","chainId","depth","nonce","issuedAt","signature"],"properties":{"wallet":{"type":"string"},"address":{"type":"string"},"chainId":{"type":"number"},"depth":{"type":"string","enum":["simple","advanced"],"default":"simple"},"nonce":{"type":"string"},"issuedAt":{"type":"string"},"signature":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"Invalid input, expired signature, or non-contract address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Signature invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"409":{"description":"Scan already in progress/completed, or advanced scan already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Daily AI scan limit reached (wallet/ip/global).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to start scan.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/super-analyst/status":{"get":{"description":"Poll an AI deep-scan request by id.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"chainId":{"type":"number"},"address":{"type":"string"},"depth":{"type":"string"},"result":{"type":"object"},"error":{"type":"string"}}}}}},"400":{"description":"Missing id.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to fetch scan status.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/wallet-info":{"post":{"description":"Fetch a wallet's ETH balance and transaction count.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet"],"properties":{"wallet":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string"},"balance":{"type":"number","description":"Balance in ETH."},"txCount":{"type":"number"}}}}}},"400":{"description":"Invalid address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to fetch wallet info.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/ens-resolver":{"post":{"description":"Resolve a .eth ENS name to an address or an address to its primary ENS name.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","description":".eth name or 0x address."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ensName":{"type":"string"},"address":{"type":"string"}}}}}},"400":{"description":"Input must be a .eth ENS name or a 0x address.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to resolve name.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/gastracker":{"get":{"description":"Current Ethereum gas prices (Etherscan) and ETH/USD price (CoinGecko).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"SafeGasPrice":{"type":"string"},"ProposeGasPrice":{"type":"string"},"FastGasPrice":{"type":"string"},"suggestBaseFee":{"type":"string"},"LastBlock":{"type":"string"},"ethUsd":{"type":"number"}}}}}},"500":{"description":"Failed to fetch gas data.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"502":{"description":"Could not fetch gas.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/stats":{"get":{"description":"Core SpotBlock platform statistics (addresses tracked, sources, detections today).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"totalAddresses":{"type":"number"},"uniqueSources":{"type":"number"},"maliciousDetectedToday":{"type":"number"},"topSources":{"type":"array","items":{"type":"object"}}}}}}},"500":{"description":"Failed to fetch statistics.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/addresses":{"get":{"description":"Query the SpotBlock threat-DB address collection with filters, pagination, and facet stats.","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Address substring or exact 0x address."}},{"name":"label","in":"query","required":false,"schema":{"type":"string","enum":["safe","suspicious","threat","critical"]}},{"name":"source","in":"query","required":false,"schema":{"type":"string"}},{"name":"network","in":"query","required":false,"schema":{"type":"string"}},{"name":"severity","in":"query","required":false,"schema":{"type":"string"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"schema":{"type":"string"}},{"name":"reviewer","in":"query","required":false,"schema":{"type":"string"}},{"name":"hasVuln","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"page","in":"query","required":false,"schema":{"type":"number","default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"number","default":50,"maximum":200}},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["address","createdAt","updatedAt","severity"],"default":"updatedAt"}},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"object"}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}}},"stats":{"type":"object"}}}}}},"500":{"description":"Failed to query addresses.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/explorer/overview":{"get":{"description":"Aggregated threat-DB overview for the Explorer landing page (counts, classes, severities, networks).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"totalContracts":{"type":"number"},"withVulnSignals":{"type":"number"},"distinctClasses":{"type":"number"},"newlyFlagged7d":{"type":"number"},"topClasses":{"type":"array","items":{"type":"object"}},"severities":{"type":"array","items":{"type":"object"}},"networks":{"type":"array","items":{"type":"object"}},"generatedAt":{"type":"string"},"cached":{"type":"boolean"}}}}}},"500":{"description":"Failed to fetch overview.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/explorer/intelligence":{"get":{"description":"Curated intelligence snapshot: top threat creators, top detection signals, shared creation txs, AI rating distribution.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"topThreatCreators":{"type":"array","items":{"type":"object"}},"topDetectionSignals":{"type":"array","items":{"type":"object"}},"sharedCreationTxs":{"type":"array","items":{"type":"object"}},"aiRatingDistribution":{"type":"array","items":{"type":"object"}},"summary":{"type":"object"}}}}}},"500":{"description":"Failed to fetch intelligence data.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/contract-exists":{"get":{"description":"Check whether an address has deployed contract code on the active network.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"network":{"type":"string"},"exists":{"type":"boolean"},"cached":{"type":"boolean"}}}}}},"400":{"description":"Invalid address parameter.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to check contract.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}