API DOCUMENTATION.

All API requests require a Handler-tier key, generated from the settings page. Pass it as a Bearer token in the Authorization header. Keys are scoped to your account and can be rotated at any time. Lost or compromised keys should be revoked immediately.

# Bearer token authentication
curl https://api.dossier.io/v1/wallets \
  -H "Authorization: Bearer dsr_live_HK4m9PqR8n2WtY2k4Zx" \
  -H "Accept: application/json"

const response = await fetch('https://api.dossier.io/v1/wallets', {
  headers: {
    'Authorization': `Bearer ${process.env.DOSSIER_KEY}`,
    'Accept': 'application/json'
  }
});
const wallets = await response.json();

import requests, os

response = requests.get(
    "https://api.dossier.io/v1/wallets",
    headers={
        "Authorization": f"Bearer {os.environ['DOSSIER_KEY']}",
        "Accept": "application/json"
    }
)
wallets = response.json()

Rate limits are per-key, applied as token-bucket rolling windows. Limits reset on the second. Every response includes X-RateLimit-Remaining and X-RateLimit-Reset headers so you can pace requests.

Errors return standard HTTP status codes with a JSON body containing error.code, error.message, and a request_id for support.

Paginated list of tracked wallets, sortable by performance metrics. Returns scored wallets only — sub-50% win rate wallets and insider patterns are filtered server-side.

{
  "data": [
    {
      "file_no": "0001",
      "address": "7xK4m9PqR8n2WtY2k4ZxH6q8Lm",
      "alias": "RAYDIUM HUNTER",
      "pnl_7d": 284432.18,
      "pnl_pct_7d": 0.5688,
      "win_rate": 0.89,
      "trades_30d": 87,
      "avg_hold_minutes": 142,
      "grads_30d": 22,
      "signal_score": 5,
      "last_active": "2026-04-25T13:42:14Z"
    }
  ],
  "next_cursor": "eyJyYW5rIjo1MH0",
  "has_more": true
}

Detailed dossier for a single wallet — full position list, behavioral profile, intel notes.

Active convergence events. The flagship signal — 3+ tracked wallets independently buying the same token within a 6-hour window. This endpoint is what powers the Hot Signals strip on the dashboard.

{
  "data": [
    {
      "id": "conv_4421",
      "alert_id": "A47",
      "token": {
        "ticker": "WAKE",
        "name": "Wake Protocol",
        "mint": "WaKeP...jY9k",
        "current_mc_usd": 847000
      },
      "wallet_count": 4,
      "avg_entry_mc": 342000,
      "window_minutes": 90,
      "detected_at": "2026-04-22T15:48:11Z",
      "severity": "high",
      "wallets": ["#0001", "#0008", "#0006", "#0017"]
    }
  ]
}

Define a custom convergence rule. Subscribe to alerts when specific wallets, tokens, or patterns match. Watchlists are persistent and trigger both REST list filters and WebSocket events.

{
  "name": "RAYDIUM HUNTER moves",
  "rule": {
    "wallets": ["#0001"],
    "event": "buy",
    "min_position_usd": 10000,
    "mc_band": "sub_500k"
  },
  "deliver_via": ["telegram", "webhook"]
}

Real-time event stream for convergences, big moves, cluster exits, and individual tracked wallet activity. Sub-second latency from on-chain confirmation. Subscribe to specific event types or get the firehose.

const ws = new WebSocket(
  `wss://stream.dossier.io/v1?key=${process.env.DOSSIER_KEY}`
);

ws.addEventListener('open', () => {
  // Subscribe to convergence + big move events
  ws.send(JSON.stringify({
    action: 'subscribe',
    events: ['convergence', 'big_move'],
    filters: { mc_band: '100k_2m' }
  }));
});

ws.addEventListener('message', (e) => {
  const event = JSON.parse(e.data);
  console.log(event.type, event.payload);
});

import asyncio, json, os
import websockets

async def stream():
    url = f"wss://stream.dossier.io/v1?key={os.environ['DOSSIER_KEY']}"
    async with websockets.connect(url) as ws:
        await ws.send(json.dumps({
            "action": "subscribe",
            "events": ["convergence", "big_move"],
            "filters": {"mc_band": "100k_2m"}
        }))
        async for raw in ws:
            event = json.loads(raw)
            print(event["type"], event["payload"])

asyncio.run(stream())

All events are JSON objects with type, id, timestamp, and a type-specific payload. Subscribe to specific types or use "events": ["*"] for the full firehose.