API reference

Pulse serves a read-only JSON API from the same port as the dashboard. Every example response on this page was captured from a real running Pulse instance and trimmed for length: long arrays keep one item and large objects show their first fields.

Conventions#

• Base URL: http://localhost:8787 by default (see PORT). All routes are under /api.
• Method: every route is GET. The API never writes to the archive.
• Auth: none. Pulse is built to run on your own machine or network. Put it behind your own proxy if you expose it, see Deployment.
• CORS: enabled for all origins on /api/*.
• Format: JSON. Numbers are plain JSON numbers, timestamps are ISO 8601 UTC strings.
• Errors: a JSON body with an error key. 404 for a missing token or report, 400 for an invalid export table, 500 with {"error":"internal error","detail":"..."} for an unexpected failure.
• Limits: integer parameters are clamped to their range rather than rejected.

GET/api/health#

Use it as a liveness and freshness check. lastCycle is the time the last collection cycle finished, or null before the first one. stream is null when the firehose is off.

{
  "ok": true,
  "db": "pglite",
  "lastCycle": "2026-10-10T20:50:28.055Z",
  "stream": null,
  "prices": {
    "solUsd": 110.30003830152059,
    "ethUsd": 2507.515
  }
}

GET/api/overview#

Everything the dashboard overview shows, in one call. The market totals Pulse stores exclude dead tokens, tokens at or above $1B market cap, and tokens tagged as stablecoins, liquid staking tokens, wrapped assets or tokenized equities, and count only tokens snapshotted in the last 2 hours, so the figures describe the trenches rather than majors.

{
  "markets": [
    {
      "ts": "2026-10-09T16:02:44.530Z",
      "chain": "robinhood",
      "native_usd": 2484.725,
      "tracked_tokens": 35,
      "total_mcap": 240440572,
      "total_volume_24h": 18053134.840000004,
      "launches_1h": 122,
      "graduations_1h": 0,
      "stream_trades_1h": null,
      "stream_volume_1h": null,
      "data": {}
    },
    {
      "ts": "2026-10-09T16:02:44.530Z",
      "chain": "solana",
      "native_usd": 109.50513045779886,
      "tracked_tokens": 814,
      "total_mcap": 15127778740.769213,
      "total_volume_24h": 826734738.1226892,
      "launches_1h": 4,
      "graduations_1h": 0,
      "stream_trades_1h": 937,
      "stream_volume_1h": 180689.35656318715,
      "data": {
        "pools1h": 0,
        "connected": true,
        "trackedTokens": 120,
        "tradersSeen1h": 728
      }
    }
  ],
  "series": [
    {
      "ts": "2026-10-09T15:54:36.513Z",
      "chain": "solana",
      "total_mcap": 98437580086.30959,
      "total_volume_24h": 6662829921.434305,
      "launches_1h": 0,
      "graduations_1h": 0,
      "stream_trades_1h": null,
      "stream_volume_1h": null,
      "native_usd": 109.54923272285733
    }
  ],
  "status": [
    {
      "chain": "solana",
      "status": "new",
      "tokens": 478,
      "mcap": 606009650.9817777
    },
    {
      "chain": "solana",
      "status": "graduated",
      "tokens": 160,
      "mcap": 1616868612.6361256
    },
    {
      "chain": "solana",
      "status": "running",
      "tokens": 258,
      "mcap": 98931876555.87157
    }
  ],
  "categories": [],
  "launches": [
    {
      "hour": "2026-10-09T04:00:00.000Z",
      "chain": "robinhood",
      "launches": 25,
      "graduations": 0
    },
    {
      "hour": "2026-10-09T05:00:00.000Z",
      "chain": "robinhood",
      "launches": 60,
      "graduations": 0
    }
  ],
  "hot": [],
  "stream": null,
  "prices": {
    "solUsd": 110.30668154929297,
    "ethUsd": 2507.195
  },
  "rules": {
    "running": "mcap at least 60% of ATH, ATH set within 24h, mcap >= $100k and 24h volume >= $50k",
    "dying": "mcap down 70% or more from an ATH of at least $50k, or 24h volume under 10% of its peak after peaking above $100k",
    "dead": "mcap down 90% or more from an ATH of at least $20k, or liquidity under $1k, or no fresh data for 3 days with negligible volume",
    "graduated": "the launchpad reported the bonding curve completed (pump.fun complete event, Odyssey PoolMigrated)",
    "new": "seen but none of the above yet"
  }
}

GET/api/tokens#

List tokens. Returns total (the count matching the filters, before pagination) and rows.

curl -s "http://localhost:8787/api/tokens?limit=2&sort=volume"

{
  "total": 1867,
  "rows": [
    {
      "chain": "solana",
      "address": "So11111111111111111111111111111111111111112",
      "symbol": "SOL",
      "name": "Wrapped SOL",
      "category": "unclassified",
      "tech_score": 0.55,
      "status": "running",
      "launchpad": null,
      "last_price": 109.5103588079291,
      "last_mcap": 64476277428.57601,
      "last_liquidity": 957580467.1244314,
      "last_volume_24h": 3558182124.809469,
      "last_holders": 3820662,
      "last_change_24h": 0.87256676,
      "ath_mcap": 64476790460.80474,
      "ath_at": "2026-10-09T16:00:11.988Z",
      "first_mcap": 64468339022.841034,
      "first_seen": "2026-10-09T15:54:53.355Z",
      "created_at": "2021-03-29T10:05:48.000Z",
      "graduated_at": null,
      "died_at": null,
      "status_changed_at": "2026-10-09T15:56:50.088Z"
    }
  ]
}

GET/api/tokens/:chain/:address#

Everything recorded about one token. Responds 404 with {"error":"token not found"} for an unknown token.

{
  "token": {
    "chain": "solana",
    "address": "FDJqEqqS68jummd8XGtBqzJTu2Pgc3pGQjozrpUzpump",
    "symbol": "Altai",
    "name": "Altai the Tiger",
    "decimals": 6,
    "description": "",
    "website": null,
    "twitter": "https://x.com/altai_sol?s=11",
    "telegram": null,
    "launchpad": "pump.fun",
    "creator": "AB35YcJ1Zpom1bp1BnAvjn7k4snoAPm4SeEd558d9w3y",
    "created_at": "2026-10-10T13:29:46.000Z",
    "first_seen": "2026-10-10T20:49:55.184Z",
    "last_seen": "2026-10-10T20:50:28.055Z",
    "last_snapshot_at": "2026-10-10T20:50:28.055Z",
    "category": "animal",
    "categories": [
      "animal"
    ],
    "tech_score": 0.2,
    "classified_at": "2026-10-10T20:49:57.371Z",
    "tags": [
      "token-2022",
      "unknown"
    ],
    "verified": null,
    "last_price": 0.0003297861387340371,
    "last_mcap": 314064.78595722513,
    "last_liquidity": 38788.82877527442,
    "last_volume_24h": 8638370.999944214,
    "last_holders": 2297,
    "last_change_24h": 2241.4512,
    "first_mcap": 314064.78595722513,
    "ath_mcap": 314064.78595722513,
    "ath_at": "2026-10-10T20:50:28.055Z",
    "peak_volume_24h": 8638370.999944214,
    "status": "running",
    "status_changed_at": "2026-10-10T20:50:42.489Z",
    "graduated_at": "2026-10-10T13:44:57.000Z",
    "died_at": null
  },
  "pairs": [
    {
      "chain": "solana",
      "address": "DU79t3yoStzeN9StbcXViGFB3xj44yDCyCtddP2ya2wd",
      "token_address": "FDJqEqqS68jummd8XGtBqzJTu2Pgc3pGQjozrpUzpump",
      "dex": "pumpswap",
      "quote_symbol": "SOL",
      "labels": [],
      "created_at": "2026-10-10T13:44:57.000Z",
      "url": "https://dexscreener.com/solana/du79t3yostzen9stbcxvigfb3xj44ydcyctddp2ya2wd"
    }
  ],
  "snapshots": [
    {
      "ts": "2026-10-10T20:50:28.055Z",
      "price_usd": 0.0003297861387340371,
      "mcap": 314064.78595722513,
      "liquidity": 38788.82877527442,
      "vol_1h": 100521.35195381555,
      "vol_24h": 8638370.999944214,
      "holders": 2297,
      "buys_24h": 48060,
      "sells_24h": 48991,
      "traders_24h": 9313,
      "organic_score": 75,
      "top_holders_pct": 26.11864
    }
  ],
  "lists": [
    {
      "list": "dex:profiles",
      "best_rank": 9,
      "appearances": 2,
      "first_ts": "2026-10-10T20:45:28.053Z",
      "last_ts": "2026-10-10T20:50:28.055Z"
    }
  ],
  "events": [],
  "trades": [],
  "positions": [],
  "heat": null
}

GET/api/tokens/:chain/:address/candles#

OHLCV candles for the token's newest pool, fetched live from GeckoTerminal (not stored in the archive). Up to 300 candles, oldest first.

The response has candles, source and, on success, pool. source is geckoterminal on success, none when Pulse has no pool for the token, and unavailable (with an error string) when the upstream call fails. Each candle is {time, open, high, low, close, volume} with time in Unix seconds.

{
  "candles": [
    {
      "time": 1791637200,
      "open": 0.00004163304555289392,
      "high": 0.00026714241397987187,
      "low": 0.00002535371499509234,
      "close": 0.00022522849120936112,
      "volume": 302569.54368149297
    },
    {
      "time": 1791640800,
      "open": 0.00022522849120936112,
      "high": 0.0016262733827770027,
      "low": 0.00017436239805011084,
      "close": 0.0008610642881990726,
      "volume": 3801661.058165243
    }
  ],
  "source": "geckoterminal",
  "pool": "DU79t3yoStzeN9StbcXViGFB3xj44yDCyCtddP2ya2wd"
}

GET/api/pump/:mint#

Proxies pump.fun's own record of a coin by mint address, including fields Pulse does not archive. Returns {"error":"not found"} when pump.fun has no such coin or cannot be reached.

{
  "error": "not found"
}

GET/api/launches#

Launch, graduation and pool events, newest first, joined to the token's current market cap, volume and status.

{
  "rows": [
    {
      "ts": "2026-10-09T16:04:01.000Z",
      "chain": "solana",
      "kind": "launch",
      "token": "6Q7QKJHRraB16eUwg185LtDSGNxmhuZSWjn8EwCupump",
      "launchpad": "pump",
      "actor": "8ARiUQUYgZPWiw1Sy1EcnKssQStRkus1vfNH8zavo96T",
      "name": "PepeBall",
      "symbol": "PEPEBALS",
      "last_mcap": null,
      "last_volume_24h": null,
      "status": "new"
    },
    {
      "ts": "2026-10-09T16:03:53.000Z",
      "chain": "solana",
      "kind": "launch",
      "token": "FnZF5BW55V6ZXskxBEAwoh817en4nRF3nePi6KPmpump",
      "launchpad": "pump",
      "actor": "FQXyscafwmteTNZrxgg4uFR6rmT1YQuXe441rZc2zVZC",
      "name": "Super Influencers",
      "symbol": "SI",
      "last_mcap": null,
      "last_volume_24h": null,
      "status": "new"
    }
  ]
}

GET/api/wallets#

Labelled wallets ordered by Pulse score (unscored last), then by trades in the last 24 hours. Returns at most 200 rows. Score columns are null until a wallet has recorded positions, see Wallet scoring.

{
  "rows": [
    {
      "chain": "solana",
      "address": "23fwPE81JitXcRC1Rm1iQKLwgx3bQYaa5xG1Dknpkp35",
      "label": null,
      "kind": "smart",
      "score": null,
      "win_rate": null,
      "tokens_traded": null,
      "early_hits": null,
      "best_multiple": null,
      "pnl_usd": null,
      "trades_24h": 0
    }
  ]
}

GET/api/wallets/:address#

One wallet: the wallets row joined to its score, up to 100 positions (joined to token symbol, market cap and status) and up to 100 recent trades. An unknown address returns {"wallet":null,"positions":[],"trades":[]} with status 200.

{
  "wallet": {
    "chain": "solana",
    "address": "8deJ9xeUvXSJwicYptA9mHsU2rN2pDx37KWzkDkEXhU6",
    "label": "Cooker",
    "kind": "kol",
    "first_seen": "2026-10-09T15:54:54.669Z",
    "updated_at": "2026-10-10T20:50:01.155Z",
    "meta": {
      "24h": {
        "wins": 47,
        "losses": 1,
        "pnlSol": 384.1629365706123
      }
    },
    "score": null,
    "win_rate": null,
    "tokens_traded": null,
    "early_hits": null,
    "best_multiple": null,
    "pnl_usd": null
  },
  "positions": [],
  "trades": []
}

GET/api/reports#

Stored newsletter issues, newest first, up to 120. sent is true once the issue went out on Telegram.

{
  "rows": [
    {
      "day": "2026-10-09T00:00:00.000Z",
      "generated_at": "2026-10-09T15:57:15.853Z",
      "sent": false
    }
  ]
}

GET/api/reports/:day#

One stored issue by YYYY-MM-DD: day, generated_at, data (the structured sections), markdown, html and telegram (send receipt or null). Returns 404 with {"error":"no report for that day"} when none exists.

{
  "day": "2026-10-09T00:00:00.000Z",
  "generated_at": "2026-10-09T15:57:15.853Z",
  "data": {
    "day": "2026-10-09",
    "dead": [],
    "dying": [],
    "stats": {
      "snapshots24h": 1155,
      "archiveTokens": 1583,
      "tokensSeen24h": 1583,
      "walletsTracked": 752,
      "archiveSnapshots": 1155,
      "tradesRecorded24h": 0
    },
    "markets": [
      {
        "chain": "solana",
        "native_usd": 109.50078265692568,
        "total_mcap": 98570612863.13484,
        "launches_24h": 0,
        "tracked_tokens": 631,
        "graduations_24h": 0,
        "mcap_change_pct": null,
        "total_volume_24h": 6662631270.839499
      }
    ],
    "runners": [
      {
        "mcap": 687899.8408945301,
        "name": "FrontLine",
        "chain": "solana",
        "status": "running",
        "symbol": "FPS",
        "address": "258hQ12j9UeGdiEaJzYuMjrgPFbsveNuK72uVKAR3DQj",
        "holders": 301,
        "ath_mcap": 687899.8408945301
      }
    ],
    "launches": [
      {
        "chain": "robinhood",
        "launches": 917,
        "launchpad": "pons",
        "graduations": 0
      }
    ],
    "promoted": [
      {
        "mcap": 310359,
        "name": "Gary the Cat",
        "chain": "solana",
        "status": "running",
        "symbol": "Gary",
        "address": "8ZCmwpW3MtC5UpNcZf7U4HMvRNTo71syU11BDiAFpump",
        "holders": null,
        "ath_mcap": 310359
      }
    ],
    "kolTokens": [],
    "narrative": null,
    "robinhood": [
      {
        "mcap": 234491890,
        "name": "Pons",
        "chain": "robinhood",
        "status": "new",
        "symbol": "PONS",
        "address": "0x39dBED3a2bd333467115dE45665cC57F813C4571",
        "holders": null,
        "ath_mcap": null
      }
    ],
    "techPicks": [
      {
        "mcap": 892756.4577401152,
        "name": "Claudia",
        "chain": "solana",
        "status": "running",
        "symbol": "CLAUDIA",
        "address": "2j5SaS7xy776qCBpyPQbZjyQSAtKiFgrwjfErthnW2ZM",
        "holders": 2935,
        "ath_mcap": 892756.4577401152
      }
    ],
    "topVolume": [
      {
        "mcap": 627898529.6902055,
        "name": "Global Dollar",
        "chain": "solana",
        "status": "running",
        "symbol": "USDG",
        "address": "2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH",
        "holders": 22338,
        "ath_mcap": 627898529.6902055
      }
    ],
    "categories": [
      {
        "mcap": 2878002946.701584,
        "tokens": 171,
        "category": "unclassified",
        "volume_24h": 378902459.1783221,
        "avg_change_24h": 703.0264223898916
      }
    ],
    "kolWallets": [],
    "newRunners": [
      {
        "mcap": 32663378.03420661,
        "name": "Strategic American Protocol",
        "chain": "solana",
        "status": "graduated",
        "symbol": "SARP",
        "address": "EGxBQN1iPbmfuzc3Ctw24puUma9R4o1SsWFsC3Jzpump",
        "holders": 2587,
        "ath_mcap": null
      }
    ],
    "persistent": [
      {
        "mcap": 14857535.574725615,
        "name": "baton",
        "chain": "solana",
        "lists": 13,
        "status": "running",
        "symbol": "baton",
        "address": "Hg5Ja55T5wESq4vyFoiVCMeHXtGyVA69X2UHq8hgpump",
        "holders": 17887
      }
    ],
    "generatedAt": "2026-10-09T15:57:15.828Z",
    "smartTokens": [],
    "windowHours": 24,
    "smartWallets": [],
    "holdersGrowth": []
  },
  "markdown": "# Pulse daily, 2026-10-09\n\n## Market pulse\n\n- Solana: $98.57B trench mcap, tokens under $1B (n/a), $6.66B 24h volume (n/a), 0 launches, 0 graduations, SOL $109....",
  "html": "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><title>Pulse daily 2026-10-09</tit...",
  "telegram": null
}

GET/api/reports/:day/live#

Recomputes the issue's structured data from the archive right now, without storing or sending anything. Useful for previewing the current day. Same shape as the data field above: day, generatedAt, windowHours, markets, launches, runners, newRunners, techPicks, topVolume, holdersGrowth, persistent, dying, dead, promoted, categories, kolWallets, kolTokens, smartWallets, smartTokens, robinhood and stats.

{
  "day": "2026-10-09",
  "generatedAt": "2026-10-10T20:50:51.953Z",
  "windowHours": 24,
  "markets": [
    {
      "chain": "solana",
      "native_usd": 110.30003830152059,
      "total_mcap": 15421100390.408724,
      "total_volume_24h": 547954842.8412031,
      "tracked_tokens": 1202,
      "launches_24h": 0,
      "graduations_24h": 0,
      "mcap_change_pct": 1.9389604691203752
    }
  ],
  "launches": [
    {
      "chain": "robinhood",
      "launchpad": "pons",
      "launches": 2348,
      "graduations": 0
    }
  ],
  "runners": [
    {
      "chain": "robinhood",
      "address": "0x000050E18ffa3F8F7aD170Eb9CeF160eb3Ed1111",
      "symbol": "TORCH",
      "name": "Torch",
      "category": "launchpad",
      "tech_score": 0.75,
      "status": "running",
      "mcap": 930348
    }
  ],
  "newRunners": [
    {
      "chain": "solana",
      "address": "jmPbUtnPpKUWgDDicW14WxvW5vvbw5sdrNknHULpump",
      "symbol": "USDF",
      "name": "United States Dividend Fund",
      "category": "unclassified",
      "tech_score": 0.4,
      "status": "running",
      "mcap": 827059261.1876895
    }
  ],
  "techPicks": [
    {
      "chain": "solana",
      "address": "2j5SaS7xy776qCBpyPQbZjyQSAtKiFgrwjfErthnW2ZM",
      "symbol": "CLAUDIA",
      "name": "Claudia",
      "category": "ai",
      "tech_score": 1,
      "status": "running",
      "mcap": 3035773.354698343
    }
  ],
  "dying": [
    {
      "chain": "solana",
      "address": "XsueG8BtpquVJX9LVLLEGuViXUungE6WmK5YZ3p3bd1",
      "symbol": "CRCLx",
      "name": "Circle xStock",
      "category": "rwa",
      "tech_score": 0.75,
      "status": "dying",
      "mcap": 70491670.29391104
    }
  ],
  "dead": [
    {
      "chain": "solana",
      "address": "46hMQPKT2sPwMSkVenXnpiKVQhrkFvJLSYMWtdkipump",
      "symbol": "D O T F",
      "name": "DOTF",
      "category": "unclassified",
      "tech_score": 0.4,
      "status": "dead",
      "mcap": 3657.3777532936906
    }
  ],
  "topVolume": [
    {
      "chain": "solana",
      "address": "SPCXxcqXj6e5dJDVNovHN8744zkbhM2bYudU45BimGb",
      "symbol": "SPCX",
      "name": "SpaceX - Backpack Securities",
      "category": "rwa",
      "tech_score": 0.75,
      "status": "running",
      "mcap": 7547015.908372643
    }
  ],
  "holdersGrowth": [
    {
      "chain": "solana",
      "address": "ERkmk5rs8KKD9u2fxoDZUmwwuVc7rT3sSeowGTrQuBit",
      "symbol": "QUBIT",
      "name": "QUBIT",
      "category": "unclassified",
      "tech_score": 0.4,
      "status": "running",
      "mcap": 164520.42781201043
    }
  ],
  "persistent": [
    {
      "chain": "solana",
      "address": "SPCXxcqXj6e5dJDVNovHN8744zkbhM2bYudU45BimGb",
      "symbol": "SPCX",
      "name": "SpaceX - Backpack Securities",
      "category": "rwa",
      "tech_score": 0.75,
      "status": "running",
      "mcap": 7547015.908372643
    }
  ],
  "promoted": [
    {
      "chain": "solana",
      "address": "BQAeeSowpwEx8Km8GcporcbuLKq4a7EQceH3F2qZpump",
      "symbol": "qOMPUTE",
      "name": "qOMPUTE",
      "category": "infra",
      "tech_score": 0.75,
      "status": "running",
      "mcap": 883755.8539648413
    }
  ],
  "categories": [
    {
      "category": "unclassified",
      "tokens": 262,
      "volume_24h": 217769313.24709335,
      "mcap": 4217300705.917731,
      "avg_change_24h": 186.3606074500956
    }
  ],
  "kolWallets": [],
  "smartWallets": [],
  "kolTokens": [],
  "smartTokens": [],
  "robinhood": [
    {
      "chain": "robinhood",
      "address": "0x39dBED3a2bd333467115dE45665cC57F813C4571",
      "symbol": "PONS",
      "name": "Pons",
      "category": "unclassified",
      "tech_score": 0.55,
      "status": "running",
      "mcap": 248346527
    }
  ],
  "stats": {
    "tokensSeen24h": 3666,
    "snapshots24h": 1833,
    "tradesRecorded24h": 0,
    "walletsTracked": 764,
    "archiveTokens": 5477,
    "archiveSnapshots": 4261
  }
}

GET/api/export/:table#

Raw rows, for analysis or model training. Allowed tables: tokens, token_snapshots, trades, launch_events, wallets, wallet_scores, wallet_positions, market_snapshots, list_appearances. Any other table returns 400. Rows come in storage order, not sorted by time.

curl -s "http://localhost:8787/api/export/market_snapshots?limit=1"

{
  "table": "market_snapshots",
  "rows": [
    {
      "ts": "2026-10-09T15:54:36.513Z",
      "chain": "solana",
      "native_usd": 109.54923272285733,
      "tracked_tokens": 541,
      "total_mcap": 98437580086.30959,
      "total_volume_24h": 6662829921.434305,
      "launches_1h": 0,
      "graduations_1h": 0,
      "stream_trades_1h": null,
      "stream_volume_1h": null,
      "data": {}
    }
  ]
}

An invalid table:

{
  "error": "table must be one of tokens, token_snapshots, trades, launch_events, wallets, wallet_scores, wallet_positions, market_snapshots, list_appearances"
}

Everything else#

Any other path serves the built dashboard. If the dashboard has not been built, the root returns a short text hint to run npm run build.