Wallets API: On-Chain Profiles, Portfolios, and Events

GET /wallets/:address for wallet profiles including portfolio and PnL, and GET /events for the global on-chain event stream of swaps and transfers.

The Wallets API exposes the same data shown on Retina Terminal wallet pages — portfolio holdings, estimated PnL, Cortex reputation score, behavioral classification, and recent trade history. Use it to build wallet-monitoring tools, leaderboard views, or copy-trading logic. This page also documents the global GET /events endpoint for querying the on-chain event stream across all wallets and tokens.

GET /wallets/:address

GET https://api.retinaos.xyz/v1/wallets/{address}

Path Parameter

address · string · required

The on-chain EVM wallet address.

Example Request

curl -X GET https://api.retinaos.xyz/v1/wallets/0xdef456... \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "address": "0xdef456...",
  "classification": "Early Mover",
  "reputation_score": 83,
  "reputation_confidence": "high",
  "portfolio": [
    {
      "token_address": "0xabc123...",
      "token_symbol": "EXT",
      "quantity": 125000,
      "value_usd": 3750
    }
  ],
  "pnl_estimate_usd": 42300,
  "pnl_confidence": "medium",
  "sector_preference": "early_stage_tokens",
  "trade_count": 214,
  "first_seen": "2024-08-01T00:00:00Z"
}

GET /wallets/:address/events — Trade History

GET https://api.retinaos.xyz/v1/wallets/{address}/events

Query Parameters

type · string

Filter by event type. Options: swap, liquidity_add, liquidity_remove, transfer.

page · integer

Page number (default: 1).

limit · integer

Results per page (default: 50, max: 200).

Example Response Entry

{
  "type": "swap",
  "token_address": "0xabc123...",
  "token_symbol": "EXT",
  "amount_usd": 1200,
  "direction": "buy",
  "timestamp": "2025-01-15T06:02:34Z",
  "tx_hash": "0x789abc..."
}

GET /events — Global On-Chain Event Stream

GET https://api.retinaos.xyz/v1/events

The /events endpoint provides a paginated stream of on-chain activity across all indexed wallets and tokens on Robinhood Chain — including swaps, liquidity adds and removes, and transfers. Use it to monitor market-wide activity, detect unusual patterns, or feed real-time data pipelines.

Query Parameters

type · string

Filter by event type. Options: swap, liquidity_add, liquidity_remove, transfer. Omit to return all event types.

token_address · string

Filter events to a specific token contract address.

wallet_address · string

Filter events to a specific wallet address.

since · string

ISO 8601 timestamp. Return only events after this time (e.g. 2025-01-15T00:00:00Z).

page · integer

Page number (default: 1).

limit · integer

Results per page (default: 50, max: 200).

Example Request

curl -X GET "https://api.retinaos.xyz/v1/events?type=swap&since=2025-01-15T00:00:00Z&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "type": "swap",
      "wallet_address": "0xdef456...",
      "token_address": "0xabc123...",
      "token_symbol": "EXT",
      "amount_usd": 1200,
      "direction": "buy",
      "timestamp": "2025-01-15T06:02:34Z",
      "tx_hash": "0x789abc..."
    },
    {
      "type": "liquidity_add",
      "wallet_address": "0xghi789...",
      "token_address": "0xabc123...",
      "token_symbol": "EXT",
      "amount_usd": 50000,
      "direction": null,
      "timestamp": "2025-01-15T06:01:10Z",
      "tx_hash": "0x456def..."
    }
  ],
  "total": 8420,
  "page": 1,
  "limit": 50
}