{"openapi":"3.0.3","info":{"title":"Wallet Verify API","version":"1.1.0","description":"14-layer wallet risk intelligence with direct OSINT, on-chain freeze verification, and forensic graph analysis. Authenticated via API key. Beyond this /api/v1 surface, API keys are also accepted on the 14 forensic module endpoints (/api/wv-forensic/*) and selected /api/security/* endpoints — see the API Integration Guide (docs/manuals/api-integration.md).","contact":{"url":"https://walletverify.io/support"}},"servers":[{"url":"https://verify.blox.global/api/v1","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Wallet Verify API key. Generate via the admin UI or contact sales for enterprise keys. Pass either as `X-API-Key: <key>` or `Authorization: Bearer <key>`."}},"schemas":{"ScreenRequest":{"type":"object","required":["address"],"properties":{"address":{"type":"string","description":"Wallet address (EVM 0x-prefixed, BTC base58/bech32, Tron T-prefixed, Solana base58)."},"chainId":{"type":"string","description":"Chain identifier — numeric (\"1\") or name (\"ethereum\", \"tron\", \"btc\", \"solana\").","default":"1"},"type":{"type":"string","enum":["wallet","token"],"default":"wallet"}}},"ScreenResponse":{"type":"object","properties":{"schemaVersion":{"type":"string","example":"1.0"},"address":{"type":"string"},"chain":{"type":"string"},"verdict":{"type":"object","properties":{"risk":{"type":"string","enum":["safe","low","medium","high","critical","analyzing","unknown"]},"shouldBlock":{"type":"boolean"},"shouldFlag":{"type":"boolean"},"confidence":{"type":"integer"},"summary":{"type":"string"}}},"riskScore":{"type":"integer","minimum":0,"maximum":100},"riskLevel":{"type":"string"},"layers":{"type":"array","description":"Per-layer factor breakdown (Layers 1-14 plus forensic modules). Available on instant tier and above.","items":{"type":"object","properties":{"layer":{"type":"integer"},"name":{"type":"string"},"score":{"type":"integer"},"severity":{"type":"string"},"detail":{"type":"string"}}}},"knownLabel":{"type":"string","nullable":true},"launderingPhase":{"type":"object","properties":{"phase":{"type":"string","enum":["placement","layering","integration","normal"]},"confidence":{"type":"integer"},"signals":{"type":"array","items":{"type":"string"}}}},"counterpartyRiskScore":{"type":"object","description":"Forensic+ tier only. Actuarial probability the counterparty is or becomes sanctioned/frozen within 30 days.","properties":{"probability":{"type":"integer"},"tier":{"type":"string","enum":["CRITICAL","HIGH","MEDIUM","LOW","MINIMAL"]},"confidence":{"type":"integer"}}},"tokenHoneypotExposure":{"type":"object","description":"Deep+ tier only. Per-token honeypot assessment of the wallet's top 10 holdings.","nullable":true,"properties":{"honeypotCount":{"type":"integer"},"usdAtRisk":{"type":"number"},"summary":{"type":"string"}}},"cluster":{"type":"object","description":"Forensic+ tier only. Wallet cluster membership from common-control detection.","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"size":{"type":"integer"},"confidence":{"type":"integer"}}},"flags":{"type":"object","description":"Quick-access classification flags from the screening result.","properties":{"isSanctioned":{"type":"boolean"},"isPhishing":{"type":"boolean"},"isScam":{"type":"boolean"},"isMalicious":{"type":"boolean"},"isTrusted":{"type":"boolean"}}},"reasons":{"type":"array","description":"Individual risk reasons (also joined into verdict.summary).","items":{"type":"string"}},"onchainBlacklist":{"type":"object","nullable":true,"description":"Structured stablecoin on-chain blacklist result (which token contracts have frozen this address).","properties":{"isBlocked":{"type":"boolean"},"blockedTokens":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object","properties":{"token":{"type":"string"},"contract":{"type":"string"},"chain":{"type":"string"},"isBlocked":{"type":"boolean"}}}}}},"balances":{"type":"object","description":"Paid tiers. Native + token balances. Omitted when analytics sources were unavailable (see screening.analyticsDataUnavailable) — never zero-filled.","properties":{"native":{"type":"object","properties":{"symbol":{"type":"string"},"balance":{"type":"string","description":"Raw base-unit balance as an exact string."},"balanceFormatted":{"type":"string","description":"Human-readable, exact (trailing zeroes trimmed, never rounded)."},"valueUsd":{"type":"number"}}},"tokens":{"type":"array","items":{"type":"object","properties":{"contractAddress":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"decimals":{"type":"integer"},"balance":{"type":"string"},"balanceFormatted":{"type":"string"},"valueUsd":{"type":"number"},"verified":{"type":"boolean","description":"true = known official contract; false = potential impostor."},"possibleScam":{"type":"boolean","description":"Symbol matches a known token but the contract does not."}}}},"totalTokens":{"type":"integer"}}},"walletAge":{"type":"object","description":"Paid tiers. Age of the wallet derived from its first observed transaction.","properties":{"readable":{"type":"string","nullable":true,"example":"3 years, 2 months"},"days":{"type":"integer","nullable":true},"firstTransaction":{"type":"string","nullable":true},"lastTransaction":{"type":"string","nullable":true}}},"activity":{"type":"object","description":"Paid tiers. Transaction and token-transfer counts and values.","properties":{"total":{"type":"integer"},"inbound":{"type":"integer"},"outbound":{"type":"integer"},"inboundValue":{"type":"string"},"outboundValue":{"type":"string"},"tokenTransfersIn":{"type":"integer"},"tokenTransfersOut":{"type":"integer"},"tokenTransfersTotal":{"type":"integer"}}},"walletType":{"type":"object","description":"Paid tiers. Contract vs EOA classification.","properties":{"isContract":{"type":"boolean"},"contractName":{"type":"string","nullable":true},"contractVerified":{"type":"boolean","nullable":true}}},"suspiciousInteractions":{"type":"array","description":"Paid tiers. Direct interactions with flagged counterparties.","items":{"type":"object","properties":{"address":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"txHash":{"type":"string"},"timestamp":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"]}}}},"hasSuspiciousActivity":{"type":"boolean","description":"Paid tiers."},"freezePrediction":{"type":"object","nullable":true,"description":"Paid tiers. Predicted likelihood of an on-chain freeze based on matched historical patterns.","properties":{"likelihood":{"type":"number"},"timeframe":{"type":"string"},"matchedPatterns":{"type":"array","items":{"type":"string"}}}},"fraudPrediction":{"type":"object","nullable":true,"description":"Paid tiers. Similarity of this wallet's behavior to known-bad wallets.","properties":{"similarityScore":{"type":"number"},"confidence":{"type":"number"},"matchedTraits":{"type":"array","items":{"type":"string"}},"totalBadWalletsAnalyzed":{"type":"integer"}}},"aiNarrative":{"type":"string","nullable":true,"description":"Paid tiers. Model-generated narrative summary of the risk picture."},"screening":{"type":"object","description":"Screening provenance: which sources were checked, which responded, which failed, and whether the result is degraded.","properties":{"degraded":{"type":"boolean","description":"true = one or more threat-intel sources failed; treat coverage as partial."},"fromCache":{"type":"boolean"},"analyticsDataUnavailable":{"type":"boolean","description":"true = all wallet-analytics sources failed; balances/age/activity are omitted rather than zero-filled."},"historyUnavailable":{"type":"boolean","description":"true = balance is real (local node) but tx-history sources failed; walletAge/activity are omitted — unknown, not zero."},"sourcesChecked":{"type":"array","items":{"type":"string"}},"sourcesResponded":{"type":"array","items":{"type":"string"}},"sourcesFailed":{"type":"array","items":{"type":"string"}},"threatListsChecked":{"type":"array","items":{"type":"object","properties":{"listName":{"type":"string"},"provider":{"type":"string"},"entryCount":{"type":"integer"},"matched":{"type":"boolean"},"matchDetail":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"organizationSlug":{"type":"string"},"planTier":{"type":"string","enum":["free","instant","deep","forensic","enterprise"]},"quotaRemaining":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"}}}}},"PathTraceRequest":{"type":"object","required":["from","to"],"properties":{"chainId":{"type":"string","default":"ethereum"},"from":{"type":"string","description":"Source wallet address"},"to":{"type":"string","description":"Target wallet address"},"maxHops":{"type":"integer","minimum":1,"maximum":7,"default":5}}},"PathTraceResponse":{"type":"object","properties":{"found":{"type":"boolean"},"hops":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"txCount":{"type":"integer"},"volumeAToB":{"type":"string"},"volumeBToA":{"type":"string"},"firstAt":{"type":"string","format":"date-time","nullable":true},"lastAt":{"type":"string","format":"date-time","nullable":true}}}},"totalHops":{"type":"integer"},"pathStrength":{"type":"integer"},"searchTimeMs":{"type":"integer"},"timedOut":{"type":"boolean"}}}}},"paths":{"/screen":{"post":{"summary":"Screen a wallet for risk","description":"10-layer risk assessment. Free tier returns verdict only; deeper tiers add layer breakdown, laundering phase, counterparty risk, token honeypot, and cluster info.","tags":["Screening"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenRequest"}}}},"responses":{"200":{"description":"Screening result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenResponse"}}}},"400":{"description":"Bad request"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Insufficient scope"},"429":{"description":"Rate limit or quota exceeded"},"503":{"description":"Screening pipeline unavailable"}}}},"/path-trace":{"post":{"summary":"Trace funds flow between two wallets","description":"Forensic-tier path tracer. Returns shortest path from source to target through the relationship graph with edge metadata at each hop. Up to 5 hops by default. Forensic and Enterprise plans only.","tags":["Forensic"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PathTraceRequest"}}}},"responses":{"200":{"description":"Path trace result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PathTraceResponse"}}}},"403":{"description":"Forensic tier required"}}}},"/verify-report":{"post":{"summary":"Verify a signed Wallet Verify report","description":"Public verification of a cryptographically signed report. No API key required — verification is intentionally public so courts and auditors can independently authenticate reports.","tags":["Verification"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reportId","sealedAt","signature","data"],"properties":{"reportId":{"type":"string","format":"uuid"},"sealedAt":{"type":"string","format":"date-time"},"schemaVersion":{"type":"string"},"data":{"type":"object"},"signature":{"type":"string","description":"base64-encoded Ed25519 signature"},"publicKeyFingerprint":{"type":"string"},"hashAlgorithm":{"type":"string","enum":["SHA-256"]},"signatureAlgorithm":{"type":"string","enum":["Ed25519"]}}}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"reason":{"type":"string"},"signedAt":{"type":"string","format":"date-time"},"reportId":{"type":"string","format":"uuid"}}}}}}}}},"/clusters/{chain}/{address}":{"get":{"summary":"Cluster Explorer — common-control cluster for a wallet","description":"Returns the cluster this wallet belongs to (members, confidence, detection signals). Requires the cluster:read scope. Forensic and Enterprise plans only.","tags":["Forensic"],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string"}},{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cluster membership result","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Forensic tier or cluster:read scope required"},"404":{"description":"No cluster found for this wallet"}}}},"/honeypot/{chain}/{token}":{"get":{"summary":"Honeypot Simulator — single-token honeypot assessment","description":"Simulated buy/sell assessment (taxes, sellability, blacklist functions) for one token contract. Forensic and Enterprise plans only.","tags":["Forensic"],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"path","required":true,"schema":{"type":"string","description":"Token contract address"}}],"responses":{"200":{"description":"Honeypot assessment","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Forensic tier required"}}}},"/tokens/{chain}/{address}":{"get":{"summary":"Token Profile — identity, provenance, safety, concentration","description":"Canonical token profile: identity, deploy provenance, safety flags (blacklist/pause/mint functions), audit status, honeypot flags, holder concentration, top holders, composite risk score. Returns 202 with Retry-After when the contract is newly seen and a metadata sync has been enqueued. Requires tokens:read scope.","tags":["Tokens"],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["ethereum","polygon","arbitrum","base","optimism","bsc","avalanche","celo","tron"]}},{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Token profile","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Not yet indexed — sync enqueued, retry after the indicated delay"},"400":{"description":"Unsupported chain or malformed address"}}}},"/tokens/trace":{"post":{"summary":"Token origin trace — where did each held token come from","description":"For a holder wallet, traces first-receive transaction, originating wallet, and distance from contract deployment. Traces one token when tokenAddress is given, otherwise the top held tokens (max 10).","tags":["Tokens"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","holderAddress"],"properties":{"chain":{"type":"string","enum":["ethereum","polygon","arbitrum","base","optimism","bsc","avalanche","celo"]},"holderAddress":{"type":"string"},"tokenAddress":{"type":"string","description":"Optional — trace only this token"},"limit":{"type":"integer","maximum":10,"default":5}}}}}},"responses":{"200":{"description":"Per-token origin traces","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/time-machine":{"post":{"summary":"Time Machine — reconstruct wallet state at a historical date","description":"Balance, holdings and activity as of the given date. Requires time:read scope. Forensic and Enterprise plans only.","tags":["Forensic"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","address","date"],"properties":{"chain":{"type":"string"},"address":{"type":"string"},"date":{"type":"string","format":"date","description":"YYYY-MM-DD"},"includeEvents":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Historical wallet state","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Forensic tier or time:read scope required"}}}},"/cross-chain-link":{"post":{"summary":"Cross-Chain Identity Linker","description":"Links a wallet to counterpart identities on other chains via bridge-transaction correlation. Forensic and Enterprise plans only.","tags":["Forensic"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"chainId":{"type":"string","default":"ethereum"},"address":{"type":"string"},"maxLinks":{"type":"integer","maximum":20,"default":10},"windowDays":{"type":"integer","maximum":365,"default":90}}}}}},"responses":{"200":{"description":"Linked identities with confidence scores","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Forensic tier required"}}}},"/graphql":{"get":{"summary":"GraphQL schema (SDL)","description":"Returns the GraphQL schema definition. Forensic and Enterprise plans only.","tags":["GraphQL"],"responses":{"200":{"description":"Schema SDL"}}},"post":{"summary":"GraphQL query endpoint","description":"Query fields: screenWallet, pathTrace, counterparties, clusters, timeMachine, crossChain, honeypot, launderPhase. Lets one round-trip combine several analyses. Forensic and Enterprise plans only.","tags":["GraphQL"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"variables":{"type":"object"},"operationName":{"type":"string"}}}}}},"responses":{"200":{"description":"GraphQL execution result"}}}},"/me/usage":{"get":{"summary":"Organization usage rollup (last 30 days)","description":"Returns the calling organization (tier, quota, used) plus per-day per-endpoint request counts. Organization resolves from the API key; browser sessions resolve via email domain.","tags":["Account"],"responses":{"200":{"description":"Organization + usage rows","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key or session"}}}},"/watches":{"post":{"summary":"Subscribe a wallet for adverse-event alerts","description":"Watch one or more wallets. Alerts fire on outbound movement to exit venues AND on NEW adverse status from the intel layers — threat intelligence (OFAC/sanction/scam/hack), the risk models (elevated/critical), akamira contract signals, and drainer detection — delivered to the configured channels (webhook / email / SMS) and to the live stream. Cooldown-deduped. Scope watch:write.","tags":["Watch / Alerts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Single wallet to watch"},"chain":{"type":"string","default":"1"},"addresses":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"chain":{"type":"string"}}},"description":"Or several at once"},"label":{"type":"string"},"channels":{"type":"object","description":"At least one required","properties":{"webhook":{"type":"array","items":{"type":"string","format":"uri"},"description":"URLs that receive an HTTP POST per alert"},"email":{"type":"array","items":{"type":"string"}},"sms":{"type":"array","items":{"type":"string"}}}},"conditions":{"type":"object","properties":{"onAnyOutbound":{"type":"boolean"},"escalateLabels":{"type":"array","items":{"type":"string"}},"minValueUsd":{"type":"number"}}},"cooldownMinutes":{"type":"integer","default":30,"minimum":5}}}}}},"responses":{"201":{"description":"Watch created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Missing address or channel"}}},"get":{"summary":"List the caller's watches","description":"Returns the watch configs owned by the caller (org for API keys, email for sessions). Scope watch:read.","tags":["Watch / Alerts"],"responses":{"200":{"description":"Watches","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/watches/{id}":{"delete":{"summary":"Delete a watch","description":"Remove one of the caller's watch subscriptions (tenant-safe). Scope watch:write.","tags":["Watch / Alerts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Not found"}}}},"/watches/stream":{"get":{"summary":"Live alert stream (Server-Sent Events)","description":"Push-delivery of the caller's watch alerts in real time via SSE (`event: alert`). The real-time complement to the webhook/email/SMS channels. Scope watch:read.","tags":["Watch / Alerts"],"responses":{"200":{"description":"text/event-stream of alert events"}}}}}}