> ## Documentation Index
> Fetch the complete documentation index at: https://retinaos.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField path="address" type="string" required>
  The on-chain EVM wallet address.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET https://api.retinaos.xyz/v1/wallets/0xdef456... \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "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

<ParamField query="type" type="string">
  Filter by event type. Options: `swap`, `liquidity_add`, `liquidity_remove`, `transfer`.
</ParamField>

<ParamField query="page" type="integer">
  Page number (default: 1).
</ParamField>

<ParamField query="limit" type="integer">
  Results per page (default: 50, max: 200).
</ParamField>

### Example Response Entry

```json theme={null}
{
  "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

<ParamField query="type" type="string">
  Filter by event type. Options: `swap`, `liquidity_add`, `liquidity_remove`, `transfer`. Omit to return all event types.
</ParamField>

<ParamField query="token_address" type="string">
  Filter events to a specific token contract address.
</ParamField>

<ParamField query="wallet_address" type="string">
  Filter events to a specific wallet address.
</ParamField>

<ParamField query="since" type="string">
  ISO 8601 timestamp. Return only events after this time (e.g. `2025-01-15T00:00:00Z`).
</ParamField>

<ParamField query="page" type="integer">
  Page number (default: 1).
</ParamField>

<ParamField query="limit" type="integer">
  Results per page (default: 50, max: 200).
</ParamField>

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "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
}
```