# Perpetua Whale Risk Signal API

> Perpetua Whale Risk Signal API is a paid API for AI agents from api.tradeperpetua.xyz, paid per call via x402, $0.15/call, status unknown (last checked 2026-09-13).

Scores an EVM wallet address as a crypto whale/risk tier with detailed on-chain activity metrics on Base or Ethereum

## Facts

- Endpoint: GET https://api.tradeperpetua.xyz/whale
- Price: $0.15/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/perpetua-whale-risk-signal-api-a4a7f8d8
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_E9_Ll9O2iWRPd9J_cNO0g

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability perpetua-whale-risk-signal-api-a4a7f8d8
```

Example prompt: 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?

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

## Request schema (JSON Schema)

```json
{
 "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": {
       "typ
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/perpetua-whale-risk-signal-api-a4a7f8d8/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.tradeperpetua.xyz](https://www.zero.xyz/host/api.tradeperpetua.xyz/llms.txt)