madeonsol 2.25.0 → 2.26.0

package/README.md

@@ -12,6 +12,10 @@
 Official TypeScript/JavaScript SDK for the **[MadeOnSol](https://madeonsol.com) Solana API** — zero dependencies, fully typed, works in Node.js ≥ 18 and edge runtimes.
 > Real-time Solana trading intelligence: track 1,069 KOL wallets with <3s latency, score 23,000+ Pump.fun deployers, surface deshred deploy signals **~500ms before on-chain confirmation**, detect multi-KOL coordination, score token rug-risk 0–100 with a transparent factor breakdown, expose the bundle cohort that bought a token together and how much of supply it still holds, verify any wallet's current on-chain holdings with airdrop/insider `transfer_delta` detection, push every pump.fun graduation the second it bonds, and stream every DEX trade across 9+ programs. Free tier: 200 requests/day, every endpoint — no signup payment. Get a key at [madeonsol.com/pricing](https://madeonsol.com/pricing).
 
+> **New in 2.26.0 — token surges & revivals: momentum fires with the honest half attached — one endpoint + one live channel.** `client.token.surges(params?)` (typed `TokenSurgesResponse`) binds `GET /tokens/surges`: **`surge`** = a token < 30 min old whose MC runs hard vs its *launch* MC (tier `early` ≤ 10 min / ≥ $12k / ≥ 3×, `strong` ≤ 30 min / ≥ $30k / ≥ 6× and still climbing, `breakout` ≤ 2 min / ≥ $45k / ≥ 8× — each fires once per mint, and only when SUSTAINED across ≥ 10 s, never on a one-tick mark); **`revival`** = a token with no trade candle for ≥ 24 h that started trading again, confirmed by real buys + buy volume on the tape, never by the price move alone. Hard gates on both: liquidity ≥ $1.5k and ≥ 2 % of MC, and the MC gained must be *paid for* (buy volume ≥ 3 % of the move — a spoof-pool mark moves MC on ~$0). Every row carries `tape` (buys / sells / volume, `unique_buyers` only where wallet data exists — `wallet_data_available: false` otherwise, never inferred), `kol`, `early_buyers` (bundled / sold / sniper wallets), `deployer` reputation and **`risk_flags[]`** (`bundled_launch`, `few_buyers`, `wash_pattern`, `thin_liquidity`, `cold_deployer`, `sniper_heavy`, `early_buyers_exiting`, `sell_pressure`, `no_tape_trades`, `no_prior_price`, `mint_authority_active`, `transfer_fee`); rows ≥ 65 min old carry the +1 h `outcome` (`mc_1h_multiple`, `peak_1h_multiple`, `priced_after_1h`) and `stats: true` returns per-(kind, tier) hit-rates — out-of-sample by construction. Filters `kind`, `tier`, `mint`, `launchpad`, `deployer_tier`, `min_mc_usd` / `max_mc_usd`, `min_buys`, `exclude_flags`, `only_clean`; cursors `since` / `before`. Pushed live on the new **`token:surges`** WS channel (events `token:surge` / `token:revival`, typed `TokenSurgeStreamEvent`, server-side filters `TokenSurgesSubscribeFilters`: `kinds[]`, `tiers[]`, `launchpads[]`, `exclude_flags[]`, `min_mc_usd` / `max_mc_usd`, `deployer_tier[]`). Nearly every scalar is `| null` — null means unknown, never zero. **PRO+** (BASIC receives HTTP 403) on the keyed `msk_` API.
+
+> **New in 2.25.1 — stream tokens never expire.** `client.stream.getToken()` (`POST /stream/token`) now returns the **same token on every call, forever**. It stops working only if your subscription lapses or you call `client.stream.getToken({ rotate: true })` to replace it (the previous value keeps working for 60 s). `StreamToken.expires_at` and `next_refresh_at` are always `null` (kept for wire compatibility — do not schedule refreshes on them); the response gains `rotated: boolean` and `lifetime: string`. The server never rotates on its own and never sends `token_refresh` unless you rotated; a `4001` close means "mint again" (lapsed or rotated), never a timer. Prefer `Authorization: Bearer <token>` on the WebSocket handshake — `?token=` still works and is masked in access logs. `client.stream.connect()` already does the right thing (it calls `getToken()` on every (re)connect); no code change needed on your side.
+
 > **New in 2.25.0 — token locks & vesting, upcoming unlocks, and pump.fun creator-fee sharing / fee claims — five endpoints + two live channels.** `client.token.locks(mint, params?)` (typed `TokenLocksResponse`) binds `GET /tokens/{mint}/locks`: every on-chain Streamflow / Jupiter Lock / Bonfida lock or vesting contract on a mint, decoded from the locker programs' account state, with a LIVE-derived view (`locked_raw` still locked, `unlocked`, `withdrawn`, `claimable`, `status`, `next_unlock`) and a `summary` (locked / deposited totals, the 7d / 30d forward unlock schedule, `active_cancelable_by_sender` — a lock the sender can cancel is a weaker promise). `client.token.locksFeed(params?)` (`GET /tokens/locks`) is the cross-token feed of NEW contracts, cursor-paginated (`pagination.next_since` / `next_before`) and pushed live on the new **`token:locks`** WS channel (event `token:lock`, typed `TokenLockStreamEvent`). `client.token.unlocks(params?)` (`GET /tokens/unlocks`) lists upcoming unlock EVENTS (cliff / period / final / tranche) inside `within=1h…90d` with `window_amount_*` per contract. `client.token.feeShares(mint)` (`GET /tokens/{mint}/fee-shares`) decodes a pump.fun coin's on-chain `SharingConfig` — who its creator fees are redirected to (`share_bps`, `is_admin`, `is_social_pda` for fees earmarked for an X account etc., `redirected_bps`, `social_bps`, `is_default` = 100% to the creator) plus the distribution rollup per recipient and the config change log; `client.token.feeClaims(params?)` (`GET /tokens/fee-claims`) is the fee-event feed (`distribution` with per-address `payouts[]`, `social_claim`, `shares_created` / `updated` / `reset`, `creator_transferred`, `creator_claim` on request), pushed live on the new **`token:fee_claims`** channel (event `token:fee_claim`, typed `TokenFeeClaimStreamEvent`). Honest limits: base-unit amounts are **strings** and ui / usd / pct are `null` when decimals or price are unknown; **LP locks are NOT included** (token / vesting locks only); **fee-event history starts 2026-08-17**; all five are **PRO+** (BASIC receives HTTP 403) on the keyed `msk_` API.
 
 > **New in 2.24.0 — live holder census: exact holder count, labelled holders, and pools that are named, not just excluded.** `client.alpha.holders(mint)` (typed `TokenHoldersResponse`) binds `GET /tokens/{mint}/holders` (PRO+): every token account of the mint read from the ledger at `confirmed` and merged per owner, so `concentration.holder_count` is EXACT (distinct non-zero owners minus pools / bonding curves / burns) — never a trade-derived estimate; it is `null` only when the provider refuses the census for a mega-cap, in which case you get the top-20 view and `source.census_fallback_reason` says so. Each disclosed owner carries our labels (`deployer` / `kol` / `early_buyer` / `bundle` / `bot` / `dump_cluster` — empty means unknown to us, not clean), and `excluded[]` NAMES what was taken out of the circulating denominator: `reason` = `pool` (with `dex` + `pool_address`), `bonding_curve` (pump.fun / LaunchLab), `burn`, or `program_account` only when we genuinely cannot attribute the PDA; `pool_pct` / `burned_pct` / `program_pct` split the exclusion. Amounts are raw u64 **strings**. Disclosure: PRO ranks 1–10, ULTRA 1–50, BUSINESS 1–100 — the maths is tier-independent. Big tokens take 5–30 s upstream: you get `503 holder_scan_in_progress` with `retry_after_seconds: 20` while the scan finishes into the cache, and the retry is instant.
@@ -1179,6 +1183,36 @@ Returns: `TokenFeeClaimsResponse` (`TokenFeeClaimEvent`, `TokenFeePayout`, `Toke
 
 ---
 
+#### `client.token.surges(params?)` *(new in 2.26 — PRO+)*
+
+Token **momentum fires**, newest first (`GET /tokens/surges`). Two kinds. **`surge`** — a token < 30 min old whose market cap runs hard vs its *launch* MC: tier `early` (≤ 10 min, ≥ $12k, ≥ 3× launch MC), `strong` (≤ 30 min, ≥ $30k, ≥ 6× launch **and** ≥ 2× the lowest sample of the last 3 min — it is climbing *now*), `breakout` (≤ 2 min, ≥ $45k, ≥ 8×). Each tier fires at most once per mint; tiers are independent (a token can go straight to breakout). A tier must be **sustained** — floor + multiple hold on the current tick *and* on a sample ≥ 10 s older, and nothing fires before 20 s of age: a one-tick mark (same-slot bundle, routed dust) is a spike, not a surge. When the engine first saw the token late (`baseline_source: "late"`) the launch multiple is not applied — USD floor + velocity only. **`revival`** — a token with **no 1-minute trade candle for ≥ 24 h** that starts trading again, confirmed **only by the tape** (≥ 5 buys, ≥ $500 buy volume, MC ≥ 1.5× the pre-dormancy close — or ≥ 20 buys / ≥ $5k regardless), never by the price mark: a single dust buy into an empty pool marks MC up 300 % and is not a revival. One fire per dormancy episode (24 h re-fire guard). **Hard gates on both kinds** (not flags): liquidity ≥ $1.5k *and* ≥ 2 % of MC when known, MC ≤ $100B, and the MC gained must be **paid for** — buy volume on the tape ≥ 3 % × (MC − launch / pre-dormancy MC); a price mark in a spoof pool moves MC on ~$0 of volume. **PRO+** — BASIC receives HTTP 403.
+
+Every row carries `tape` (buys / sells / volume since birth or revival; `tape.source` = `candles` or `wallet_trades`, `tape.available: false` with nulls while no tape covers the window yet; `unique_buyers` / `trades_per_wallet` only when the mint is in `token_trades` coverage — `wallet_data_available: false` otherwise, **never inferred zero**), `kol` (tracked-KOL buyers + names), `early_buyers` (first-20 cohort: bundled, cohort SOL, sold, sniper wallets), `deployer` (tier, bonding / runner rate, labeled tokens) and **`risk_flags[]`** — the honest half (thresholds echoed in `definitions.risk_flags`). Rows ≥ 65 min old carry `outcome` (`mc_usd_1h_after`, `peak_mc_usd_1h_after`, `low_mc_usd_1h_after`, `mc_1h_multiple`, `peak_1h_multiple`, `priced_after_1h` — `false` = no candle in the hour, not zero); `stats: true` adds per-(kind, tier) hit-rates over `days` (`up_1h_pct`, `median_peak_multiple`, `doubled_1h_pct`) — out-of-sample by construction, the fire is recorded before the outcome exists. The live thresholds are echoed in `definitions` (read from the engine, so they cannot drift from what fires). Poll with `since = pagination.next_since`, or subscribe to the **`token:surges`** WS channel (events `token:surge` / `token:revival` — the same object minus `outcome`).
+
+- Nearly every scalar is `| null` — null means unknown, never zero. `tier` is null on revivals; `dormant_hours` / `prev_mc_usd` / `mc_vs_prev_multiple` are null on surges; `baseline_*` / `mc_multiple` / `mc_change_3m_pct` are null on revivals.
+- `launchpad` is the venue at *birth*, `primary_dex` where it trades at fire time — a pump token that graduated inside its first 10 min is `pumpfun` / `pumpswap`.
+- `tier` with `kind: "revival"` is a 400; an unknown flag in `exclude_flags` is a 400 with `known_flags[]`.
+
+```ts
+const { events, stats } = await client.token.surges({ kind: "surge", tier: "strong", exclude_flags: ["bundled_launch", "sniper_heavy"], stats: true });
+for (const e of events) {
+  console.log(e.symbol, `$${e.market_cap_usd}`, `${e.mc_multiple}× launch`, e.tape.buys, "buys /", e.tape.unique_buyers ?? "n/a", "buyers", e.risk_flags, e.outcome ? `${e.outcome.peak_1h_multiple}× peak in 1h` : "outcome pending");
+}
+for (const r of stats?.rows ?? []) console.log(r.kind, r.tier, `${r.up_1h_pct}% up after 1h`, "median peak", r.median_peak_multiple, `(${r.with_outcome} fires)`);
+
+// live
+const stream = await client.stream.connect();
+stream.subscribe(["token:surges"], { kinds: ["surge"], tiers: ["strong", "breakout"], exclude_flags: ["bundled_launch"], min_mc_usd: 30_000 } satisfies TokenSurgesSubscribeFilters);
+stream.on("token:surge", (d) => { const e = d as TokenSurgeStreamEvent; console.log(e.tier, e.symbol, e.market_cap_usd, e.risk_flags); });
+stream.on("token:revival", (d) => { const e = d as TokenSurgeStreamEvent; console.log("revived after", e.dormant_hours, "h", e.symbol, e.mc_vs_prev_multiple); });
+```
+
+Params: `kind` (surge | revival), `tier` (early | strong | breakout — surge only), `mint`, `since` / `before` (ISO date-time cursors), `min_mc_usd` / `max_mc_usd`, `min_buys`, `launchpad`, `deployer_tier` (elite | good | moderate | rising | cold | unranked), `exclude_flags` (array or comma list), `only_clean` (boolean), `stats` (boolean), `days` (1–30, default 7), `limit` (1–200, default 50).
+
+Returns: `TokenSurgesResponse` (`TokenSurgeEvent`, `TokenSurgeStreamEvent`, `TokenSurgeTape`, `TokenSurgeKol`, `TokenSurgeEarlyBuyers`, `TokenSurgeDeployer`, `TokenSurgeOutcome`, `TokenSurgeStats`, `TokenSurgeStatsRow`, `TokenSurgesFilters`, `TokenSurgeDefinitions`, `TokenSurgeKind`, `TokenSurgeTier`, `TokenSurgeRiskFlag`, `TokenSurgeDeployerTier`, `TokenSurgesSubscribeFilters`, `TokenFeedPagination`, `TokenFeedStreamPointer`)
+
+---
+
 ### Account — `client.me()` *(new in 2.6)*
 
 Inspect your tier, quota state, and feature usage in one call. Reads from the same in-memory counters that drive rate-limit enforcement, so `quota.daily.remaining` is authoritative — no header parsing needed. Works on every tier (BASIC/PRO/ULTRA).
@@ -1235,19 +1269,23 @@ Returns: `ToolsSearchResponse`
 
 #### `client.stream.getToken()`
 
-Generate a 24-hour WebSocket streaming token. Pro/Ultra subscribers get `ws_url` for KOL/deployer event streaming. Ultra subscribers also get `dex_ws_url` for the all-DEX trade stream.
+Issue your WebSocket streaming token. Pro/Ultra subscribers get `ws_url` for KOL/deployer event streaming. Ultra subscribers also get `dex_ws_url` for the all-DEX trade stream.
+
+Stream tokens **never expire** (since 2.25.1): the same token comes back on every call until your subscription lapses or you pass `{ rotate: true }` to replace it (the previous value keeps working for 60 s). Send it as `Authorization: Bearer <token>` on the WebSocket handshake (`?token=` still works). A `4001` close means "mint again", never a timer.
 
 ```ts
 const token = await client.stream.getToken();
 console.log(token.ws_url);      // wss://madeonsol.com/ws/v1/stream
 console.log(token.dex_ws_url);  // wss://madeonsol.com/ws/v1/dex-stream (Ultra only)
+console.log(token.expires_at);  // null — never expires
+const fresh = await client.stream.getToken({ rotate: true }); // replace it
 ```
 
-Returns: `StreamToken` — `{ token, expires_at, ws_url, dex_ws_url?, usage }`
+Returns: `StreamToken` — `{ token, expires_at: null, next_refresh_at: null, rotated, lifetime, ws_url, dex_ws_url?, usage }`
 
 #### `client.stream.connect()` *(new in 2.10)*
 
-Open a **managed** stream — token fetch + 24h refresh, auto-reconnect (backoff + jitter), heartbeat liveness, and typed events are handled for you. No need to touch `getToken()` or `ws` directly.
+Open a **managed** stream — token fetch (the token never expires; `getToken()` is called on every (re)connect), auto-reconnect (backoff + jitter), heartbeat liveness, and typed events are handled for you. No need to touch `getToken()` or `ws` directly.
 
 ```ts
 const stream = client.stream.connect();
@@ -1257,7 +1295,7 @@ stream.subscribe(["kol:trades", "deployer:alerts"]);
 // stream.unsubscribe([...]) / stream.close() when done
 ```
 
-Channels: `kol:trades`, `kol:coordination`, `kol:first_touches`, `deployer:alerts`, `wallet_tracker:events`, `copytrade:signals`, `price_alert:events`, `sniper:deploys`, `token:graduations` (every pump.fun graduation in real time, tracked deployer or not — typed `GraduationEvent`), `token:locks` (**new 2.25** — event `token:lock` for every NEW Streamflow / Jupiter Lock / Bonfida lock or vesting contract, typed `TokenLockStreamEvent`; PRO+; updates are not pushed — poll `client.token.locks()`), `token:fee_claims` (**new 2.25** — event `token:fee_claim` for every pump.fun fee event: distributions, social-handle claims, config changes, typed `TokenFeeClaimStreamEvent`; PRO+). Lifecycle: `open`, `close`, `reconnect`, `heartbeat`, `error`. Node 22+ uses the global `WebSocket`; on Node < 22 also `npm i ws`.
+Channels: `kol:trades`, `kol:coordination`, `kol:first_touches`, `deployer:alerts`, `wallet_tracker:events`, `copytrade:signals`, `price_alert:events`, `sniper:deploys`, `token:graduations` (every pump.fun graduation in real time, tracked deployer or not — typed `GraduationEvent`), `token:locks` (**new 2.25** — event `token:lock` for every NEW Streamflow / Jupiter Lock / Bonfida lock or vesting contract, typed `TokenLockStreamEvent`; PRO+; updates are not pushed — poll `client.token.locks()`), `token:fee_claims` (**new 2.25** — event `token:fee_claim` for every pump.fun fee event: distributions, social-handle claims, config changes, typed `TokenFeeClaimStreamEvent`; PRO+), `token:surges` (**new 2.26** — events `token:surge` / `token:revival` the moment a momentum fire is confirmed, typed `TokenSurgeStreamEvent` with `tape` / `kol` / `early_buyers` / `deployer` / `risk_flags[]`; server-side filters `kinds[]`, `tiers[]`, `launchpads[]`, `exclude_flags[]`, `min_mc_usd` / `max_mc_usd`, `deployer_tier[]` — typed `TokenSurgesSubscribeFilters`; PRO+; the +1 h `outcome` is REST-only — poll `client.token.surges()`). Lifecycle: `open`, `close`, `reconnect`, `heartbeat`, `error`. Node 22+ uses the global `WebSocket`; on Node < 22 also `npm i ws`.
 
 #### `client.stream.sessions()` / `client.stream.deleteSession(id)` *(new in 2.17 — PRO+)*
 

package/dist/index.d.ts

@@ -2193,6 +2193,301 @@ export interface TokenFeeClaimStreamEvent {
     social_fee_pda: string | null;
     shareholders: TokenFeeShareEntry[] | null;
 }
+/** `surge` = a token < 30 min old running hard vs its launch MC; `revival` = a token dormant ≥ 24 h that started trading again (confirmed by real buys, never by a price mark). */
+export type TokenSurgeKind = "surge" | "revival";
+/** Surge tiers — each fires at most once per mint; tiers are independent. Revivals have no tier (`null`). */
+export type TokenSurgeTier = "early" | "strong" | "breakout";
+/** How the token's birth was established: pre-confirm pump.fun deploy (deshred), confirmed on-chain create, or the first trade the firehose observed. */
+export type TokenSurgeBirthSource = "sniper" | "deployer" | "first_seen";
+/** `launch` = the first MC sample after birth (≤ 90 s); `late` = the engine first saw the token later (restart mid-life) — the launch multiple is then NOT applied. */
+export type TokenSurgeBaselineSource = "launch" | "late";
+/** What the burst tape was measured on: 1-minute candles (every DEX we price) or live `token_trades` rows (pump-pipeline mints). */
+export type TokenSurgeTapeSource = "candles" | "wallet_trades";
+/** Deployer reputation tier as carried on the fire (`unranked` = no score yet). */
+export type TokenSurgeDeployerTier = "elite" | "good" | "moderate" | "rising" | "cold" | "unranked";
+/** Risk flags a fire can carry — the honest half. Thresholds are echoed in `definitions.risk_flags`. */
+export type TokenSurgeRiskFlag = "bundled_launch" | "few_buyers" | "wash_pattern" | "thin_liquidity" | "cold_deployer" | "sniper_heavy" | "early_buyers_exiting" | "sell_pressure" | "no_tape_trades" | "no_prior_price" | "mint_authority_active" | "transfer_fee";
+/**
+ * The burst tape — trades since birth (surge) or since the revival minute.
+ * `available: false` = no tape covers the window yet (candle lag; every count is
+ * null). `unique_buyers` / `unique_wallets` / `trades_per_wallet` are null when
+ * the mint is outside `token_trades` coverage (`wallet_data_available: false`) —
+ * never inferred.
+ */
+export interface TokenSurgeTape {
+    since: string | null;
+    available: boolean;
+    source: TokenSurgeTapeSource | null;
+    buys: number | null;
+    sells: number | null;
+    trades: number | null;
+    buy_volume_usd: number | null;
+    sell_volume_usd: number | null;
+    volume_usd: number | null;
+    mev_volume_usd: number | null;
+    buy_sol: number | null;
+    sell_sol: number | null;
+    unique_buyers: number | null;
+    unique_wallets: number | null;
+    trades_per_wallet: number | null;
+    wallet_data_available: boolean;
+}
+/** Tracked-KOL involvement on the tape (max 10 `names`). */
+export interface TokenSurgeKol {
+    buyers: number;
+    buys: number;
+    sells: number;
+    names: string[];
+}
+/** The first-20 early-buyer cohort at fire time. */
+export interface TokenSurgeEarlyBuyers {
+    count: number;
+    /** Bought in the same block as ≥ 2 other early buyers. */
+    bundled: number;
+    cohort_sol: number | null;
+    /** Cohort wallets that have already sold. */
+    sold: number;
+    /** Early buyers that are known sniper wallets. */
+    sniper_wallets: number;
+}
+/** Deployer reputation as carried on the fire (`null` on the event when the deployer is unknown). */
+export interface TokenSurgeDeployer {
+    wallet: string | null;
+    tier: TokenSurgeDeployerTier;
+    bonding_rate: number | null;
+    total_bonded: number | null;
+    total_deployed: number | null;
+    runner_rate: number | null;
+    labeled_tokens: number | null;
+    /** Last-10 outcome string, e.g. "BDDBBDDDBD" (B = bonded, D = dead). */
+    recent: string | null;
+}
+/**
+ * +1 h outcome, present on REST rows ≥ 65 min old (computed from candles every
+ * 10 min). `priced_after_1h: false` = no candle in the hour — the token stopped
+ * being priced, NOT zero. Never on the WS event.
+ */
+export interface TokenSurgeOutcome {
+    computed_at: string;
+    mc_usd_1h_after: number | null;
+    peak_mc_usd_1h_after: number | null;
+    low_mc_usd_1h_after: number | null;
+    /** `mc_usd_1h_after ÷ market_cap_usd` at the fire. */
+    mc_1h_multiple: number | null;
+    /** `peak_mc_usd_1h_after ÷ market_cap_usd` at the fire. */
+    peak_1h_multiple: number | null;
+    priced_after_1h: boolean;
+}
+/**
+ * Payload of a `token:surge` / `token:revival` WS event (channel `token:surges`)
+ * — pushed by the surge-tracker the moment a fire is confirmed. Both kinds share
+ * one shape: `tier` is null on revivals; `dormant_hours` / `prev_mc_usd` /
+ * `mc_vs_prev_multiple` are null on surges; `baseline_*` / `mc_multiple` /
+ * `mc_change_3m_pct` are null on revivals. Nearly every scalar is nullable —
+ * a null is "not known", never zero.
+ */
+export interface TokenSurgeStreamEvent {
+    id: number | null;
+    kind: TokenSurgeKind;
+    tier: TokenSurgeTier | null;
+    mint: string;
+    symbol: string | null;
+    name: string | null;
+    /** Venue at birth / classification (what the first_seen rule was judged on). */
+    launchpad: string | null;
+    /** Where it trades at fire time — a pump token that graduated is `pumpfun` / `pumpswap`. */
+    primary_dex: string | null;
+    fired_at: string;
+    birth_at: string | null;
+    birth_source: TokenSurgeBirthSource | null;
+    age_seconds: number | null;
+    market_cap_usd: number | null;
+    liquidity_usd: number | null;
+    liquidity_to_mc_ratio: number | null;
+    price_usd: number | null;
+    /** Surge only: launch MC (`baseline_source: "launch"`). */
+    baseline_mc_usd: number | null;
+    baseline_source: TokenSurgeBaselineSource | null;
+    /** Surge only: `market_cap_usd ÷ baseline_mc_usd`; null when the baseline is `late`. */
+    mc_multiple: number | null;
+    /** Surge only: climb vs the lowest sample of the last 3 min. */
+    mc_change_3m_pct: number | null;
+    /** Revival only. */
+    dormant_hours: number | null;
+    /** Revival only: pre-dormancy candle close MC. */
+    prev_mc_usd: number | null;
+    /** Revival only: `market_cap_usd ÷ prev_mc_usd`. */
+    mc_vs_prev_multiple: number | null;
+    peak_mc_usd: number | null;
+    pct_of_peak: number | null;
+    bonding_progress_pct: number | null;
+    is_bonded: boolean | null;
+    tape: TokenSurgeTape;
+    kol: TokenSurgeKol;
+    early_buyers: TokenSurgeEarlyBuyers;
+    deployer: TokenSurgeDeployer | null;
+    /** Flat copies of `deployer.wallet` / `deployer.tier` (what the subscribe filter reads). */
+    deployer_wallet: string | null;
+    deployer_tier: TokenSurgeDeployerTier | null;
+    mint_authority_revoked: boolean | null;
+    freeze_authority_revoked: boolean | null;
+    is_token_2022: boolean | null;
+    risk_flags: TokenSurgeRiskFlag[];
+    detail_url: string;
+    /** false when the one-round-trip enrichment failed (tape / kol / early_buyers then carry zeros / nulls). */
+    enrichment_available?: boolean;
+}
+/** A REST row on GET /tokens/surges — the WS payload plus the +1 h `outcome` (null until the fire is ≥ 65 min old). */
+export interface TokenSurgeEvent extends TokenSurgeStreamEvent {
+    id: number;
+    outcome: TokenSurgeOutcome | null;
+}
+/** Query params for GET /tokens/surges. */
+export interface TokenSurgesParams {
+    kind?: TokenSurgeKind;
+    /** Surge only — 400 with `kind: "revival"`. */
+    tier?: TokenSurgeTier;
+    mint?: string;
+    /** ISO date-time — only fires after this instant (use `pagination.next_since`). */
+    since?: string;
+    /** ISO date-time — page back: only fires before this instant (`pagination.next_before`). */
+    before?: string;
+    min_mc_usd?: number;
+    max_mc_usd?: number;
+    /** Buys on the tape at fire time ≥. */
+    min_buys?: number;
+    /** Launchpad at birth, e.g. "pumpfun". */
+    launchpad?: string;
+    deployer_tier?: TokenSurgeDeployerTier;
+    /** Drop rows carrying ANY of these flags (array or comma list; unknown flag → 400 with `known_flags[]`). */
+    exclude_flags?: TokenSurgeRiskFlag[] | string;
+    /** Only rows with no risk flags at all. */
+    only_clean?: boolean;
+    /** Also return per-(kind, tier) hit-rates over `days`. */
+    stats?: boolean;
+    /** Stats window, 1–30, default 7. */
+    days?: number;
+    /** 1–200, default 50. */
+    limit?: number;
+}
+/** One per-(kind, tier) hit-rate row from `?stats=true`. Out-of-sample by construction. */
+export interface TokenSurgeStatsRow {
+    kind: TokenSurgeKind;
+    tier: TokenSurgeTier | null;
+    fires: number;
+    /** Fires ≥ 65 min old with a computed outcome — the denominator. */
+    with_outcome: number;
+    /** MC one hour after the fire ≥ MC at the fire. */
+    up_1h: number;
+    up_1h_pct: number | null;
+    median_peak_multiple: number | null;
+    p75_peak_multiple: number | null;
+    median_mc_1h_multiple: number | null;
+    doubled_1h: number;
+    doubled_1h_pct: number | null;
+}
+export interface TokenSurgeStats {
+    days: number;
+    note: string;
+    rows: TokenSurgeStatsRow[];
+}
+/** Echo of the filters the request was served with. */
+export interface TokenSurgesFilters {
+    kind: TokenSurgeKind | null;
+    tier: TokenSurgeTier | null;
+    mint: string | null;
+    launchpad: string | null;
+    deployer_tier: TokenSurgeDeployerTier | null;
+    min_mc_usd: number | null;
+    max_mc_usd: number | null;
+    min_buys: number | null;
+    exclude_flags: string[];
+    only_clean: boolean;
+}
+/** Per-tier surge thresholds as read from the live rule engine. */
+export interface TokenSurgeTierDefinition {
+    max_age_seconds: number;
+    min_market_cap_usd: number;
+    min_launch_multiple: number;
+    /** `strong` only. */
+    min_3m_climb_multiple?: number;
+}
+/**
+ * The live rule thresholds the response was produced under — read straight from
+ * the engine, so they cannot drift from what fires.
+ */
+export interface TokenSurgeDefinitions {
+    surge: {
+        early: TokenSurgeTierDefinition;
+        strong: TokenSurgeTierDefinition;
+        breakout: TokenSurgeTierDefinition;
+        min_age_seconds: number;
+        sustained_seconds: number;
+        birth_sources: TokenSurgeBirthSource[];
+        first_seen_launchpads: string[];
+        birth_note: string;
+        note: string;
+    };
+    revival: {
+        min_dormant_hours: number;
+        confirm_window_seconds: number;
+        min_buys: number;
+        min_buy_volume_usd: number;
+        min_market_cap_usd: number;
+        min_multiple_vs_prev_mc: number;
+        unknown_prev_mc_min_buy_volume_usd: number;
+        strong_confirm: {
+            min_buys: number;
+            min_buy_volume_usd: number;
+        };
+        refire_guard_hours: number;
+        note: string;
+    };
+    shared: {
+        min_liquidity_usd: number;
+        min_liq_to_mc_ratio: number;
+        volume_backing_ratio: number;
+        unbacked_max_multiple: number;
+        mc_sanity_max_usd: number;
+        tape_lag_seconds: number;
+        note: string;
+    };
+    /** Flag → human-readable threshold. */
+    risk_flags: Record<string, string>;
+    tiers: TokenSurgeTier[];
+}
+/**
+ * GET /tokens/surges — token momentum fires (surges + revivals), newest first,
+ * each with the burst tape, KOL involvement, early-buyer cohort, deployer
+ * reputation, `risk_flags[]` and (≥ 65 min old) the +1 h `outcome`. PRO+, keyed only.
+ */
+export interface TokenSurgesResponse {
+    events: TokenSurgeEvent[];
+    pagination: TokenFeedPagination;
+    filters: TokenSurgesFilters;
+    /** Only with `stats: true`. */
+    stats?: TokenSurgeStats;
+    /** Pointer to the `token:surges` WS channel (events `token:surge` / `token:revival`). */
+    stream: TokenFeedStreamPointer;
+    definitions: TokenSurgeDefinitions;
+    note: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Server-side subscribe filters for the `token:surges` WS channel — pass as the
+ * `filters` argument of `stream.subscribe(["token:surges"], filters)`. `tiers`
+ * applies to surges only (revivals always pass it); `exclude_flags` drops a fire
+ * carrying ANY listed flag.
+ */
+export interface TokenSurgesSubscribeFilters {
+    kinds?: TokenSurgeKind[];
+    tiers?: TokenSurgeTier[];
+    launchpads?: string[];
+    exclude_flags?: TokenSurgeRiskFlag[];
+    min_mc_usd?: number;
+    max_mc_usd?: number;
+    deployer_tier?: TokenSurgeDeployerTier[];
+}
 export type CandleTimeframe = "1m" | "5m" | "15m" | "1h" | "4h" | "1d";
 export interface CandlesParams {
     /** Bar size. Default "1h". */
@@ -3187,8 +3482,14 @@ export interface ToolsSearchResponse {
 }
 export interface StreamToken {
     token: string;
-    expires_at: string;
+    /** Always `null` since 2026-08-27 — stream tokens never expire. Kept for wire compatibility; do not schedule refreshes on it. */
+    expires_at: string | null;
+    /** Always `null` since 2026-08-27 — the server never rotates a token on its own. Kept for wire compatibility. */
     next_refresh_at?: string | null;
+    /** `true` when this call replaced your previous token (`rotate: true`); the old value keeps working for 60 s. */
+    rotated?: boolean;
+    /** Human-readable lifetime statement ("This token does not expire. …"). */
+    lifetime?: string;
     ws_url: string;
     /** DEX trade stream URL — only present for Ultra tier subscribers */
     dex_ws_url?: string | null;
@@ -3725,6 +4026,44 @@ declare class TokenClient {
      * ```
      */
     feeClaims(params?: TokenFeeClaimsParams): Promise<TokenFeeClaimsResponse>;
+    /**
+     * v2.26 — Token momentum fires, newest first (`GET /tokens/surges`). Two
+     * kinds. **`surge`** — a token < 30 min old whose MC runs hard vs its LAUNCH
+     * MC: tier `early` (≤ 10 min, ≥ $12k, ≥ 3× launch MC), `strong` (≤ 30 min,
+     * ≥ $30k, ≥ 6× launch AND ≥ 2× the lowest sample of the last 3 min — it is
+     * climbing NOW), `breakout` (≤ 2 min, ≥ $45k, ≥ 8×); each tier fires at
+     * most once per mint and a tier must be SUSTAINED (floor + multiple hold on
+     * the current tick and on a sample ≥ 10 s older; nothing fires before 20 s
+     * of age — a one-tick mark is a spike, not a surge). **`revival`** — a token
+     * with no 1-minute trade candle for ≥ 24 h that started trading again,
+     * CONFIRMED by the tape (≥ 5 buys, ≥ $500 buy volume, MC ≥ 1.5× the
+     * pre-dormancy close — or ≥ 20 buys / ≥ $5k regardless), never by the price
+     * mark alone. Hard gates on both: liquidity ≥ $1.5k and ≥ 2% of MC when
+     * known, MC ≤ $100B, and the MC gained must be PAID FOR (buy volume ≥ 3% of
+     * the move — a price mark in a spoof pool moves MC on ~$0 of volume).
+     *
+     * Every row carries `tape` (buys / sells / volume since birth or revival —
+     * `tape.source` says whether it was measured on candles or live wallet
+     * trades; `unique_buyers` only when the mint is in `token_trades` coverage,
+     * `wallet_data_available: false` otherwise, never inferred zero), `kol`,
+     * `early_buyers` (first-20 cohort: bundled / sold / sniper wallets),
+     * `deployer` and **`risk_flags[]`** — the honest half. Rows ≥ 65 min old
+     * also carry `outcome` (MC / peak / low one hour after, `priced_after_1h:
+     * false` = no candle in the hour, not zero) and `stats: true` prints
+     * per-(kind, tier) hit-rates over `days` — out-of-sample by construction,
+     * the fire is recorded before the outcome exists. The live thresholds are
+     * echoed in `definitions`. Poll with `since = pagination.next_since` or
+     * subscribe to the **`token:surges`** WS channel (events `token:surge` /
+     * `token:revival`, typed `TokenSurgeStreamEvent`; server-side filters
+     * `TokenSurgesSubscribeFilters`). **PRO+** — BASIC receives HTTP 403.
+     * @example
+     * ```ts
+     * const { events, stats } = await client.token.surges({ kind: "surge", tier: "strong", only_clean: true, stats: true });
+     * for (const e of events) console.log(e.symbol, e.market_cap_usd, `${e.mc_multiple}× launch`, e.tape.buys, "buys", e.outcome?.peak_1h_multiple ?? "pending");
+     * for (const r of stats?.rows ?? []) console.log(r.kind, r.tier, `${r.up_1h_pct}% up after 1h`, "median peak", r.median_peak_multiple);
+     * ```
+     */
+    surges(params?: TokenSurgesParams): Promise<TokenSurgesResponse>;
 }
 declare class DeployerClient {
     private readonly _fetch;
@@ -4252,13 +4591,22 @@ declare class StreamClient {
     private readonly _post;
     private readonly _delete;
     private readonly _baseUrl;
-    constructor(_get: <T>(url: string) => Promise<T>, _post: <T>(url: string) => Promise<T>, _delete: <T>(url: string) => Promise<T>, _baseUrl: string);
+    constructor(_get: <T>(url: string) => Promise<T>, _post: <T>(url: string, body?: unknown) => Promise<T>, _delete: <T>(url: string) => Promise<T>, _baseUrl: string);
     /**
-     * Generate a 24-hour WebSocket streaming token.
+     * Issue your WebSocket streaming token. Stream tokens never expire (since
+     * 2026-08-27): every call returns the same token until your subscription
+     * lapses or you pass `{ rotate: true }`, which replaces it (the previous
+     * value keeps working for 60 s). `expires_at` / `next_refresh_at` are always
+     * `null` — the server never rotates on its own and never sends
+     * `token_refresh` unless you rotated. A `4001` close means "mint again"
+     * (lapsed or rotated), never a timer. Authenticate the handshake with
+     * `Authorization: Bearer <token>` (`?token=` still works, masked in logs).
      * Pro/Ultra: ws_url for KOL/deployer event streaming.
      * Ultra only: dex_ws_url for all-DEX trade streaming.
      */
-    getToken(): Promise<StreamToken>;
+    getToken(opts?: {
+        rotate?: boolean;
+    }): Promise<StreamToken>;
     /**
      * List your live WebSocket sessions across the KOL/deployer (`ws-streaming`)
      * and all-DEX (`dex-stream`) services — id, tier, subscribed channels, connect