{"uid":"cap_E9_Ll9O2iWRPd9J_cNO0g","slug":"perpetua-whale-risk-signal-api-a4a7f8d8","name":"Perpetua Whale Risk Signal API","description":"Whale intelligence for any EVM wallet: total USD size (native + priced tokens), tier, 0 to 100 whale score, 24h in/out/netflow, largest move, activity flags (accumulating, distributing, fresh, high-velocity) and a plain rationale. Base and Ethereum.","url":"https://api.tradeperpetua.xyz/whale","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":["address"],"properties":{"chain":{"enum":["base","ethereum"],"type":"string","default":"base","description":"Chain, one of base, ethereum"},"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"EVM wallet address to score"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","properties":{"tier":{"enum":["shrimp","fish","dolphin","whale","humpback"],"type":"string"},"chain":{"type":"string"},"flags":{"type":"array"},"address":{"type":"string"},"txCount":{"type":"number"},"tokenUsd":{"type":"number"},"totalUsd":{"type":"number"},"nativeUsd":{"type":"number"},"rationale":{"type":"string"},"confidence":{"enum":["low","medium","high"],"type":"string"},"isContract":{"type":"boolean"},"whaleScore":{"type":"number","description":"0 to 100 whale size/activity score"},"topHoldings":{"type":"array"},"inflowUsd24h":{"type":"number"},"activeLast24h":{"type":"boolean"},"balanceSource":{"enum":["chain","indexer"],"type":"string","description":"chain means balances were read live on-chain, indexer means a cached fallback"},"netflowUsd24h":{"type":"number"},"outflowUsd24h":{"type":"number"},"largestMoveUsd24h":{"type":"number"},"tokenTransfersCount":{"type":"number"}}}}}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.15","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.15/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.15","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.15","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_8bsjxKIfZOpV-lRx80V3Z","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.15","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Scores an EVM wallet address as a crypto whale/risk tier with detailed on-chain activity metrics on Base or Ethereum","exampleAgentPrompt":"Can you score the wallet 0xf977814e90da44bfa03b6295a0616a897441acec on Base and tell me if it's a whale — I want to know its tier, whale score, 24h netflow, and whether it's been accumulating?","exampleUseCases":[{"title":"Pre-trade counterparty whale check","prompt":"Before my protocol interacts with this address 0xabc123...def456 on Ethereum, can you check if it's a whale or just a small fish? I need the tier, whale score, and any risk flags."},{"title":"DeFi protocol whale accumulation alert","prompt":"Check wallet 0xf977814e90da44bfa03b6295a0616a897441acec on Base — is it actively accumulating in the last 24 hours? Give me the netflow, largest move, and confidence level."},{"title":"Token launch whale distribution analysis","prompt":"We just launched a token and I want to know if the address 0x1234567890abcdef1234567890abcdef12345678 on Base is a whale dumping or accumulating — pull the 24h inflow, outflow, and tier classification."}],"resultDescription":"Returns a JSON object containing: whale tier label (shrimp to humpback), numeric whale score 0–100, total portfolio value in USD broken down by native and tokens, 24-hour inflow/outflow/netflow and largest single move, transaction count, top holdings, active status, risk flags (e.g. high_velocity, accumulating), confidence level (low/medium/high), whether the address is a contract, and a plain-English rationale summary.","failureModes":["Invalid wallet address format (not 0x + 40 hex chars) returns validation error","Unsupported chain value returns enum validation error","Address with no on-chain history may return low confidence or shrimp tier with minimal data","Payment failure (insufficient USDC or x402 handshake error) blocks the request","Rate limiting or upstream RPC outage may return 5xx errors","Very new wallets with sparse data may return low confidence scores"],"whenToPreferThis":"Use this endpoint when you need a fast, pay-per-call on-chain whale classification for a specific EVM wallet on Base or Ethereum. It is ideal for DeFi risk assessment, pre-trade counterparty screening, protocol security monitoring, or any agent workflow that needs a structured risk tier + 24h flow summary without building your own on-chain data pipeline. Prefer this over general blockchain explorers when you need a structured signal (score + tier + flags) rather than raw transaction history.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-13T18:35:38.673Z","isFirstParty":false}