@dcasegr/amm-client 0.38.1 → 0.39.0

package/README.md

@@ -39,9 +39,16 @@ exchange with another wallet, keeping what was read and quoted.
 
 The client (each an async function unless noted):
 
-- the exchange: `enabledList`, `registeredTokens`, `tokenBaseOf`, `hostedTokens`,
-  `watchHostedPools` / `watchTokenPools` (event streams, sync, return the unsubscribe),
+- the exchange: `enabledList`, `registeredTokens`, `tokenBaseOf`, `hostedTokens` (the token list
+  and ONE `GET /amm/stats`), `watchTokenPools` (the token's pools route as an event stream: the
+  whole answer, then each `change` — `swap`, `deploy`, `close`, `rescind` — applied to it, one it
+  cannot apply read again once; sync, returns the unsubscribe; 0.39.0: no host-wide stream),
   `claimStatus`, `isRoot`, `claimExchange`, `discoveryBase` (sync), `onDataChange` (sync);
+- history (0.39.0, plain GETs): `trades(tokenId, {from?, to?, limit?, before?, lp?})` →
+  `{trades, next}`, `trade(tokenId, txid)` → a `Trade` or null, `candles(tokenId, {tf, from, to})`,
+  `stats(tokenId)`, `statsAll({ids?})`, `holders(tokenId, {limit?, skip?})` → `{count, rows}`,
+  `positionsAll(lpKeys)` (every enabled token's positions); amounts bigints, prices `{sats,
+  tokens}` pairs of bigints (base units both);
 - swap: `quoteSwap(request, poolsAnswer, {sym, dec})` (sync: the engine's plan over the pools the
   token's pools stream gave), `executeSwap(quote, {onProgress})`, `checkSwapAgain(leg)`,
   `walletSats`;
@@ -54,7 +61,7 @@ The client (each an async function unless noted):
   `setDefaultTerms`, `clearDefaultTerms`, `setDefaultMarket`, `clearDefaultMarket`, `tokenTerms`,
   `setTokenTerms`, `discoveryState`, `setDiscovery`.
 
-Pure helpers beside it: `hostedFrom`, `poolViews`, `poolFees`, `withLeg`, `hasTerms`,
+Pure helpers beside it: `hostedFrom`, `applyPoolChange`, `parseChange`, `poolViews`, `poolFees`, `withLeg`, `hasTerms`,
 `enableCandidates`, `topicOf`, `lookupOf`, `ammLookupOf`, `walletDeployBeef`, `exchangeBase`,
 `tokenBase`; the types (`Quote`, `SwapResult`, `LegResult`, `Position`, `WalletToken`, …).
 

package/dist/client.d.ts

@@ -11,10 +11,13 @@
  *
  * - **The token list** (`GET <swap>/tokens`): read ONCE per client (D4; `enabledList`), again
  *   only after its own enable or disable changed it.
- * - **Prices** (D6, D22): the host-wide pools route `GET <origin>/amm/pools` (`hostedTokens`,
- *   `watchHostedPools`); a token's price is Σsats / Σtokens over its listed pools.
+ * - **Prices** (0.39.0, D3, D7): ONE read of the host-wide stats `GET <origin>/amm/stats`
+ *   (`hostedTokens`): each token's price, liquidity (TVL) and pool count; no host-wide stream.
+ * - **History** (0.39.0, D1–D6): `trades`, `trade`, `candles`, `stats`, `statsAll`, `holders`,
+ *   `positionsAll` — plain GETs of the history routes (H1–H6, src/lib/overlay.ts).
  * - **Swap** (D11–D16): the token's pools route `GET /@<token>/amm/pools` held as an event stream
- *   (`watchTokenPools`): the pools whose validator is beating and whose commission meets the
+ *   (`watchTokenPools`; 0.39.0, D7: the whole answer once, then one `change` per pool change,
+ *   applied to the held answer): the pools whose validator is beating and whose commission meets the
  *   market's minimum (the host's filter), the market's commission key hash; a quote is the
  *   matching engine's plan over that list (no request); a swap reads ONE `GET
  *   /@<token>/amm/pools/beef?lp=` for its legs (freshness, the pools' BEEF), then each leg's relay
@@ -40,7 +43,7 @@
 import { type WalletInterface } from "@bsv/sdk";
 import { type Send1ColorResult } from "@1sat/actions";
 import { type PoolState, type Plan } from "@dcasegr/amm-engine";
-import { type LiveAnswer, type PoolRow, type PoolsAnswer, type SignedFetch } from "./lib/overlay.js";
+import { type Candle, type CandleTf, type Holders, type TokenPosition, type TokenStats, type Trade, type TradesPage, type LiveAnswer, type PoolRow, type PoolsAnswer, type SignedFetch } from "./lib/overlay.js";
 import { type Defaults, type Discovery, type EnabledToken, type ListedToken } from "./lib/skein.js";
 import type { AuthFetchLike } from "./market/relay.js";
 import { type PreparedSwap } from "./market/swapAction.js";
@@ -262,7 +265,9 @@ export interface RegisteredToken {
     icon?: string;
     status: EnabledToken["status"];
 }
-export type { EnabledToken, Defaults, Discovery, PoolRow, PoolsAnswer };
+export type { EnabledToken, Defaults, Discovery, PoolRow, PoolsAnswer, Candle, CandleTf, Holders, TokenPosition, TokenStats, Trade, TradesPage };
+export type { PoolChange, Price } from "./lib/overlay.js";
+export { applyPoolChange, parseChange } from "./lib/overlay.js";
 /** A token's symbol, decimals and icon, read off its deploy output. */
 export interface DeployMeta {
     sym?: string;
@@ -287,11 +292,12 @@ export interface ClaimStatus {
     claimant?: string;
 }
 /**
- * The hosted tokens (the enabled 1Color tokens at output 0), each priced from its rows of the
- * host-wide pools route (D6, D22: P1, the pools whose validator is beating): Σsats / Σtokens.
- * `rows` null: not read yet (no prices). Pure.
+ * The hosted tokens (the enabled 1Color tokens at output 0), each with its record of the host-wide
+ * stats (0.39.0, D3, D7: H4): the price (`price`, sats per whole token), the liquidity (`tvlSats`,
+ * `tvlTokens`) and the pool count. `stats` null: not read yet (no prices); a token the stats lack:
+ * no price, no pools. Pure.
  */
-export declare function hostedFrom(list: EnabledToken[], rows: PoolRow[] | null): HostedToken[];
+export declare function hostedFrom(list: EnabledToken[], stats: TokenStats[] | null): HostedToken[];
 /** The pools the Swap page lists (D11, D13): the token's pools route's rows, every validator live (the host lists no other). */
 export declare function poolViews(answer: PoolsAnswer | null, tokenId: TokenId): PoolView[];
 /** The fees a pool's own record names (D13: the Swap page's fee line), basis points. */
@@ -444,8 +450,29 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
         isRoot: (identityKey: string | null) => Promise<boolean>;
         claimExchange: () => Promise<boolean>;
         hostedTokens: () => Promise<HostedToken[]>;
-        watchHostedPools: (onRows: (rows: PoolRow[]) => void, onLive?: (live: boolean) => void) => () => void;
         watchTokenPools: (tokenId: TokenId, onAnswer: (a: PoolsAnswer) => void, onError?: (e: unknown) => void) => () => void;
+        trades: (tokenId: string, o?: {
+            from?: number;
+            to?: number;
+            limit?: number;
+            before?: string;
+            lp?: string;
+        } | undefined) => Promise<TradesPage>;
+        trade: (tokenId: string, txid: string) => Promise<Trade | null>;
+        candles: (tokenId: string, o: {
+            tf: CandleTf;
+            from: number;
+            to: number;
+        }) => Promise<Candle[]>;
+        stats: (tokenId: string) => Promise<TokenStats>;
+        statsAll: (o?: {
+            ids?: TokenId[];
+        } | undefined) => Promise<TokenStats[]>;
+        holders: (tokenId: string, o?: {
+            limit?: number;
+            skip?: number;
+        } | undefined) => Promise<Holders>;
+        positionsAll: (lpKeys: string[]) => Promise<TokenPosition[]>;
         registeredTokens: () => Promise<RegisteredToken[]>;
         quoteSwap: (req: QuoteRequest, held: PoolsAnswer | null, meta: {
             sym: string;
@@ -493,8 +520,29 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
     isRoot: (identityKey: string | null) => Promise<boolean>;
     claimExchange: () => Promise<boolean>;
     hostedTokens: () => Promise<HostedToken[]>;
-    watchHostedPools: (onRows: (rows: PoolRow[]) => void, onLive?: (live: boolean) => void) => () => void;
     watchTokenPools: (tokenId: TokenId, onAnswer: (a: PoolsAnswer) => void, onError?: (e: unknown) => void) => () => void;
+    trades: (tokenId: string, o?: {
+        from?: number;
+        to?: number;
+        limit?: number;
+        before?: string;
+        lp?: string;
+    } | undefined) => Promise<TradesPage>;
+    trade: (tokenId: string, txid: string) => Promise<Trade | null>;
+    candles: (tokenId: string, o: {
+        tf: CandleTf;
+        from: number;
+        to: number;
+    }) => Promise<Candle[]>;
+    stats: (tokenId: string) => Promise<TokenStats>;
+    statsAll: (o?: {
+        ids?: TokenId[];
+    } | undefined) => Promise<TokenStats[]>;
+    holders: (tokenId: string, o?: {
+        limit?: number;
+        skip?: number;
+    } | undefined) => Promise<Holders>;
+    positionsAll: (lpKeys: string[]) => Promise<TokenPosition[]>;
     registeredTokens: () => Promise<RegisteredToken[]>;
     quoteSwap: (req: QuoteRequest, held: PoolsAnswer | null, meta: {
         sym: string;

package/dist/client.js

@@ -11,10 +11,13 @@
  *
  * - **The token list** (`GET <swap>/tokens`): read ONCE per client (D4; `enabledList`), again
  *   only after its own enable or disable changed it.
- * - **Prices** (D6, D22): the host-wide pools route `GET <origin>/amm/pools` (`hostedTokens`,
- *   `watchHostedPools`); a token's price is Σsats / Σtokens over its listed pools.
+ * - **Prices** (0.39.0, D3, D7): ONE read of the host-wide stats `GET <origin>/amm/stats`
+ *   (`hostedTokens`): each token's price, liquidity (TVL) and pool count; no host-wide stream.
+ * - **History** (0.39.0, D1–D6): `trades`, `trade`, `candles`, `stats`, `statsAll`, `holders`,
+ *   `positionsAll` — plain GETs of the history routes (H1–H6, src/lib/overlay.ts).
  * - **Swap** (D11–D16): the token's pools route `GET /@<token>/amm/pools` held as an event stream
- *   (`watchTokenPools`): the pools whose validator is beating and whose commission meets the
+ *   (`watchTokenPools`; 0.39.0, D7: the whole answer once, then one `change` per pool change,
+ *   applied to the held answer): the pools whose validator is beating and whose commission meets the
  *   market's minimum (the host's filter), the market's commission key hash; a quote is the
  *   matching engine's plan over that list (no request); a swap reads ONE `GET
  *   /@<token>/amm/pools/beef?lp=` for its legs (freshness, the pools' BEEF), then each leg's relay
@@ -42,7 +45,7 @@ import { send1Color } from "@1sat/actions";
 import { computeSwap } from "@dcasegr/amm-engine";
 import { outpointText, parseOutpoint, parseTokenId, sdkTokenId, tokenIdText } from "./lib/tokenId.js";
 import { DEFAULT_FEE_RATE_SATS_PER_KB, appName, exchangeBase, tokenBase } from "./lib/config.js";
-import { ammLookupService, liveOfPools, parseAllPools, parsePools, parseTokenTopic, poolOutputOf, poolsUrl, readDiscoveryDeploy, readDiscoveryIds, readDiscoveryList, readPoolsBeef, readPools, readPositions, readTerms, readTx, watchPools, } from "./lib/overlay.js";
+import { ammLookupService, applyPoolChange, liveOfPools, parsePools, parseTokenTopic, poolOutputOf, poolsUrl, readDiscoveryDeploy, readDiscoveryIds, readDiscoveryList, readAllPositions, readAllStats, readCandles, readHolders, readPoolsBeef, readPools, readPositions, readStats, readTerms, readTrade, readTrades, readTx, watchPools, } from "./lib/overlay.js";
 import { authFetchPerInstance, instanceBase, readDefaults, readDiscovery, readTokens, sendMessage } from "./lib/skein.js";
 import { depthOf } from "./market/prices.js";
 import { buildPlanRequest, goneFromLookup, quote as planQuote } from "./market/plan.js";
@@ -72,6 +75,7 @@ export const NO_TERMS_TEXT = "This exchange validates nothing: no terms are set.
 export function hasTerms(t) {
     return !!t && !("none" in t);
 }
+export { applyPoolChange, parseChange } from "./lib/overlay.js";
 /** The metadata of the deploy output `vout` of an Atomic BEEF's subject; null when that output is no 1Color deploy. */
 function deployMetaOf(beef, vout) {
     const tx = Transaction.fromAtomicBEEF(beef);
@@ -85,11 +89,12 @@ function symOf(meta, tokenId) {
     return meta.get(tokenId)?.sym ?? tokenId.slice(0, 8);
 }
 /**
- * The hosted tokens (the enabled 1Color tokens at output 0), each priced from its rows of the
- * host-wide pools route (D6, D22: P1, the pools whose validator is beating): Σsats / Σtokens.
- * `rows` null: not read yet (no prices). Pure.
+ * The hosted tokens (the enabled 1Color tokens at output 0), each with its record of the host-wide
+ * stats (0.39.0, D3, D7: H4): the price (`price`, sats per whole token), the liquidity (`tvlSats`,
+ * `tvlTokens`) and the pool count. `stats` null: not read yet (no prices); a token the stats lack:
+ * no price, no pools. Pure.
  */
-export function hostedFrom(list, rows) {
+export function hostedFrom(list, stats) {
     const out = [];
     for (const t of list) {
         if (t.status !== "enabled")
@@ -97,17 +102,18 @@ export function hostedFrom(list, rows) {
         const topic = parseTokenTopic(t.topic);
         if (!topic || topic.kind !== "native")
             continue;
-        const mine = (rows ?? []).filter((r) => r.tokenId !== undefined && canonicalId(r.tokenId) === t.tokenId);
-        const sats = mine.reduce((a, p) => a + p.bsvReserve, 0n);
-        const tokens = mine.reduce((a, p) => a + p.tokenReserve, 0n);
+        const st = (stats ?? []).find((r) => canonicalId(r.tokenId) === t.tokenId);
+        const sats = st?.tvlSats ?? 0n;
+        const tokens = st?.tvlTokens ?? 0n;
+        const price = st?.price ?? null;
         out.push({
             tokenId: t.tokenId,
             sym: t.sym || t.tokenId.slice(0, 8),
             dec: t.dec,
             ...(t.icon ? { icon: t.icon } : {}),
-            marginalPrice: tokens > 0n ? Number(sats) / (Number(tokens) / 10 ** t.dec) : null,
+            marginalPrice: price && price.tokens > 0n ? Number(price.sats) / (Number(price.tokens) / 10 ** t.dec) : null,
             depth: depthOf(sats),
-            pools: mine.length,
+            pools: st?.pools ?? 0,
             reserves: { sats, tokens },
         });
     }
@@ -459,24 +465,47 @@ function makeClient(opts, s) {
             throw new Error("The claim was sent, but this wallet is not the admin: someone else may have claimed this exchange first.");
         return root;
     }
-    /** The tokens this exchange hosts, priced: the token list (once) and ONE read of the host-wide pools route. No wallet needed. */
+    /** The tokens this exchange hosts, priced: the token list (once) and ONE read of the host-wide stats (0.39.0, H4). No wallet needed. */
     async function hostedTokens() {
-        const [list, rows] = await Promise.all([enabledList(), readAllPools().catch(() => null)]);
-        return hostedFrom(list, rows);
+        const [list, stats] = await Promise.all([enabledList(), statsAll().catch(() => null)]);
+        return hostedFrom(list, stats);
     }
-    async function readAllPools() {
-        const res = await f(poolsUrl(swapBase), { headers: { accept: "application/json" } });
-        if (!res.ok)
-            throw new Error(`GET ${poolsUrl(swapBase)}: ${res.status}`);
-        return parseAllPools(await res.json());
+    /**
+     * A token's pools route held as an event stream (D16; 0.39.0, D7): the whole answer (`pools`)
+     * held, each `change` applied to it (`applyPoolChange`), one it cannot apply → the route read once
+     * again; each new answer to `onAnswer`. → the unsubscribe.
+     */
+    function watchTokenPools(tokenId, onAnswer, onError) {
+        return watchPools(poolsUrl(tokenBase(tokenId, swapBase)), parsePools, onAnswer, { ...(onError ? { onError } : {}), fetch: f, change: applyPoolChange });
     }
-    /** The host-wide pools route held as an event stream (D22: one connection): each answer's rows to `onRows`; `onLive` the connection's state. → the unsubscribe. */
-    function watchHostedPools(onRows, onLive) {
-        return watchPools(poolsUrl(swapBase), parseAllPools, onRows, { onError: () => onLive?.(false), onOpen: () => onLive?.(true), fetch: f });
+    // ---------------------------------------------------------------- history (0.39.0, H1–H6)
+    /** H1: a token's trades, newest first (`from ≤ at < to` ms, `limit` 1–500, `before` the cursor `next`, `lp` one LP key's). */
+    async function trades(tokenId, o = {}) {
+        return readTrades(tokenBase(tokenId, swapBase), o, ff);
     }
-    /** A token's pools route held as an event stream (D16): each answer to `onAnswer`. → the unsubscribe. */
-    function watchTokenPools(tokenId, onAnswer, onError) {
-        return watchPools(poolsUrl(tokenBase(tokenId, swapBase)), parsePools, onAnswer, { ...(onError ? { onError } : {}), fetch: f });
+    /** H1 with `txid`: one Swap's trade row, null when it has none. */
+    async function trade(tokenId, txid) {
+        return readTrade(tokenBase(tokenId, swapBase), txid, ff);
+    }
+    /** H2: a token's candles, one per non-empty bucket of `tf` over `from ≤ at < to` (ms). */
+    async function candles(tokenId, o) {
+        return readCandles(tokenBase(tokenId, swapBase), o, ff);
+    }
+    /** H3: a token's stats. */
+    async function stats(tokenId) {
+        return readStats(tokenBase(tokenId, swapBase), ff);
+    }
+    /** H4: every enabled token's stats (`ids`: those only, in that order). */
+    async function statsAll(o = {}) {
+        return readAllStats(swapBase, o.ids, ff);
+    }
+    /** H6: a token's holders, largest first (`limit` 1–100, `skip`). */
+    async function holders(tokenId, o = {}) {
+        return readHolders(tokenBase(tokenId, swapBase), tokenId, o, ff);
+    }
+    /** H5: the LP keys' positions on every enabled token. */
+    async function positionsAll(lpKeys) {
+        return readAllPositions(swapBase, lpKeys, ff);
     }
     /**
      * A quote for one token (D12): the matching engine's plan over the pools the Swap page holds
@@ -1282,8 +1311,15 @@ function makeClient(opts, s) {
         isRoot,
         claimExchange: guard(claimExchange),
         hostedTokens: guard(hostedTokens),
-        watchHostedPools,
         watchTokenPools,
+        // history (0.39.0)
+        trades: guard(trades),
+        trade: guard(trade),
+        candles: guard(candles),
+        stats: guard(stats),
+        statsAll: guard(statsAll),
+        holders: guard(holders),
+        positionsAll: guard(positionsAll),
         registeredTokens: guard(registeredTokens),
         // swap
         quoteSwap,

package/dist/lib/overlay.d.ts

@@ -100,16 +100,22 @@ export interface EventSourceLike {
 }
 export type EventSourceCtor = new (url: string) => EventSourceLike;
 /**
- * Holds a pools route (P1 or P2) as an event stream (D16, D22): `GET <url>` with `Accept:
- * text/event-stream` (the browser's EventSource sends it), the event `pools` carrying the answer,
- * first the current one, then again each time it changes; `onAnswer` gets each. Without an
- * EventSource (an old browser, a test): ONE plain GET, no poll. → the unsubscribe.
+ * Holds a pools route as an event stream (D16; 0.39.0, D7): `GET <url>` with `Accept:
+ * text/event-stream` (the browser's EventSource sends it). The event `pools` carries the whole
+ * answer (first the current one; again when the host cannot say what changed): it replaces the held
+ * answer. With `change` (P2), the event `change` carries one pool change: `change(held, x)` applies
+ * it to the held answer (null: it cannot); one it cannot apply (no answer held yet, an unknown
+ * kind, a row it names not held) → the route is read again ONCE (a plain GET) and that answer is
+ * held (changes arriving while it is read are dropped: the answer read is the newer state). Each
+ * new held answer goes to `onAnswer`. Without an EventSource (an old browser, a test): ONE plain
+ * GET, no poll. → the unsubscribe.
  */
 export declare function watchPools<T>(url: string, parse: (x: unknown) => T, onAnswer: (a: T) => void, o?: {
     onError?: (e: unknown) => void;
     onOpen?: () => void;
     EventSource?: EventSourceCtor | null;
     fetch?: FetchFn;
+    change?: (held: T, x: unknown) => T | null;
 }): () => void;
 /** P3's answer: the LP keys' current pools and one BEEF of their transactions. */
 export interface PoolsBeef {
@@ -187,4 +193,123 @@ export declare function readDiscoveryIds(discovery: string, ids: string[], fetch
 export declare function readDiscoveryList(discovery: string, fetchFn?: FetchFn): Promise<DiscoveryRow[]>;
 /** P16: `GET <discovery>/<token>/deploy`: the deploy's BEEF; null when discovery does not hold it. */
 export declare function readDiscoveryDeploy(discovery: string, tokenId: string, fetchFn?: FetchFn): Promise<number[] | null>;
+/** A price, exact (H1–H4): `sats` satoshis per `tokens` token base units (divide in the caller). */
+export interface Price {
+    sats: bigint;
+    tokens: bigint;
+}
+/** A Swap's trade row (H1; the `swap` change's `trade`): amounts in base units, fees in the input asset, the pool's reserves after it. */
+export interface Trade {
+    txid: string;
+    lpPubKey: string;
+    /** `buy`: sats in, tokens out; `sell`: tokens in. */
+    side: "buy" | "sell";
+    amountIn: bigint;
+    amountOut: bigint;
+    feeLp: bigint;
+    feeValidator: bigint;
+    feeCommission: bigint;
+    bsvReserve: bigint;
+    tokenReserve: bigint;
+    /** The admitting step's time, ms. */
+    at: number;
+    /** The block height where the overlay has the transaction placed, else null. */
+    height: number | null;
+}
+/** H1's page: the trades newest first, `next` the cursor of the page after (null: the last page). */
+export interface TradesPage {
+    trades: Trade[];
+    next: string | null;
+}
+/** One non-empty bucket (H2): its start (ms), the first, highest, lowest and last trade's prices, each side's amounts summed, the trade count. */
+export interface Candle {
+    t: number;
+    o: Price;
+    h: Price;
+    l: Price;
+    c: Price;
+    volumeSats: bigint;
+    volumeTokens: bigint;
+    n: number;
+}
+/** A candle's resolution (H2). */
+export type CandleTf = "1m" | "5m" | "15m" | "1h" | "4h" | "1d";
+/** A token at the read's time (H3, H4): the changes in bps (null without a trade at or before the window's start). */
+export interface TokenStats {
+    tokenId: string;
+    /** The last trade's, else the deepest live pool's, else null. */
+    price: Price | null;
+    change1h: number | null;
+    change24h: number | null;
+    volume24hSats: bigint;
+    volume24hTokens: bigint;
+    buys24h: number;
+    sells24h: number;
+    lastTradeAt: number | null;
+    tvlSats: bigint;
+    tvlTokens: bigint;
+    pools: number;
+}
+/** A token's holders (H6): `count` the addresses with a balance, `rows` largest balance first. */
+export interface Holders {
+    count: number;
+    rows: {
+        address: string;
+        balance: bigint;
+    }[];
+}
+/** One LP key's position on one token (H5): P4's record with its token. */
+export interface TokenPosition extends LpPool {
+    tokenId: string;
+}
+/** One pool change on P2's stream (event `change`, D7). */
+export interface PoolChange {
+    kind: "deploy" | "swap" | "close" | "rescind";
+    /** The new pool output (deploy, swap) or the one gone (close, rescind). */
+    outpoint: string;
+    /** deploy, swap: the pool's row. */
+    pool?: PoolRow;
+    /** swap: its trade row. */
+    trade?: Trade;
+}
+/** A trade row, or null when it is not one. */
+export declare function toTrade(x: unknown): Trade | null;
+/** A stats record (H3), or null when it is not one. */
+export declare function toStats(x: unknown): TokenStats | null;
+/** A `change` event's data, or null when it is not one this client knows. */
+export declare function parseChange(x: unknown): PoolChange | null;
+/**
+ * One `change` applied to a held P2 answer (D7) → the new answer, or null when it cannot be applied
+ * (the caller reads the route again): `swap` — the row of `trade.lpPubKey` replaced by `pool` (its
+ * outpoint moved); `deploy` — `pool` added; `close` / `rescind` — the row at `outpoint` removed.
+ * The market and the validators are kept (a change of either comes as a whole `pools` answer).
+ */
+export declare function applyPoolChange(held: PoolsAnswer, x: unknown): PoolsAnswer | null;
+/** H1: `GET <base>/trades?from=&to=&limit=&before=&lp=` → the page, newest first. */
+export declare function readTrades(base: string, o?: {
+    from?: number;
+    to?: number;
+    limit?: number;
+    before?: string;
+    lp?: string;
+}, fetchFn?: FetchFn): Promise<TradesPage>;
+/** H1 with `txid`: one Swap's trade row; null when the transaction has none (404). */
+export declare function readTrade(base: string, txid: string, fetchFn?: FetchFn): Promise<Trade | null>;
+/** H2: `GET <base>/candles?tf=&from=&to=` → one candle per non-empty bucket, oldest first. */
+export declare function readCandles(base: string, o: {
+    tf: CandleTf;
+    from: number;
+    to: number;
+}, fetchFn?: FetchFn): Promise<Candle[]>;
+/** H3: `GET <base>/stats`. */
+export declare function readStats(base: string, fetchFn?: FetchFn): Promise<TokenStats>;
+/** H4: `GET <swap base>/stats` (`ids`: those enabled tokens only, in that order) → every enabled token's stats. */
+export declare function readAllStats(swapBase: string, ids?: string[], fetchFn?: FetchFn): Promise<TokenStats[]>;
+/** H6: `GET <token base>/color/<token>/holders?limit=&skip=` → the count and the rows, largest first. */
+export declare function readHolders(base: string, tokenId: string, o?: {
+    limit?: number;
+    skip?: number;
+}, fetchFn?: FetchFn): Promise<Holders>;
+/** H5: `GET <swap base>/positions?lp=k1,k2` → every enabled token's rows for the keys, each with its token. */
+export declare function readAllPositions(swapBase: string, lpPubKeys: string[], fetchFn?: FetchFn): Promise<TokenPosition[]>;
 export {};

package/dist/lib/overlay.js

@@ -25,6 +25,16 @@
  * | P15 | `GET /@discovery/1color/<token>/icon` | the icon's bytes |
  * | P16 | `GET /@discovery/1color/<token>/deploy` | the deploy's BEEF (bytes) |
  * | P17 | `GET <origin>/.well-known/skein`, `/skeins?key=`, `/amm/admin`, `/amm/defaults`, `/amm/discovery` | as before |
+ * | H1 | `GET /@<token>/amm/trades?from=&to=&limit=&before=&lp=` (or `?txid=`) | `{trades: [Trade], next}` newest first (one txid: the row) |
+ * | H2 | `GET /@<token>/amm/candles?tf=&from=&to=` | `[{t, o, h, l, c, volumeSats, volumeTokens, n}]`, one per non-empty bucket |
+ * | H3 | `GET /@<token>/amm/stats` | `{tokenId, price, change1h, change24h, volume24hSats, volume24hTokens, buys24h, sells24h, lastTradeAt, tvlSats, tvlTokens, pools}` |
+ * | H4 | `GET <origin>/amm/stats?ids=` | `[H3]`, every enabled token's (the host's) |
+ * | H5 | `GET <origin>/amm/positions?lp=` | `[{tokenId, …P4 row}]`, every enabled token's (the host's) |
+ * | H6 | `GET /@<token>/amm/color/<token>/holders?limit=&skip=` | `{count, rows: [{address, balance}]}` largest first |
+ *
+ * 0.39.0 (agent-env plans/history-api-2026-11-05.md D7): P2's stream sends the whole answer once
+ * (`pools`), then ONE `change` per pool change (`{kind, outpoint, pool?, trade?}`); the host-wide
+ * stream is gone (P1, H4 and H5 are plain reads).
  *
  * Writes stay what they were: `POST <origin>/submit` (BRC-22, plain), `/call` and `/sendMessage`
  * (signed, the wallet's BRC-104 client).
@@ -140,10 +150,15 @@ function eventSourceCtor() {
     return typeof g.EventSource === "function" ? g.EventSource : null;
 }
 /**
- * Holds a pools route (P1 or P2) as an event stream (D16, D22): `GET <url>` with `Accept:
- * text/event-stream` (the browser's EventSource sends it), the event `pools` carrying the answer,
- * first the current one, then again each time it changes; `onAnswer` gets each. Without an
- * EventSource (an old browser, a test): ONE plain GET, no poll. → the unsubscribe.
+ * Holds a pools route as an event stream (D16; 0.39.0, D7): `GET <url>` with `Accept:
+ * text/event-stream` (the browser's EventSource sends it). The event `pools` carries the whole
+ * answer (first the current one; again when the host cannot say what changed): it replaces the held
+ * answer. With `change` (P2), the event `change` carries one pool change: `change(held, x)` applies
+ * it to the held answer (null: it cannot); one it cannot apply (no answer held yet, an unknown
+ * kind, a row it names not held) → the route is read again ONCE (a plain GET) and that answer is
+ * held (changes arriving while it is read are dropped: the answer read is the newer state). Each
+ * new held answer goes to `onAnswer`. Without an EventSource (an old browser, a test): ONE plain
+ * GET, no poll. → the unsubscribe.
  */
 export function watchPools(url, parse, onAnswer, o = {}) {
     const ES = o.EventSource === undefined ? eventSourceCtor() : o.EventSource;
@@ -160,17 +175,53 @@ export function watchPools(url, parse, onAnswer, o = {}) {
             stopped = true;
         };
     }
+    let held = null;
+    let rereading = false;
+    const hold = (a) => {
+        held = a;
+        onAnswer(a);
+    };
+    const reread = () => {
+        rereading = true;
+        getJson(url, o.fetch).then((x) => {
+            rereading = false;
+            if (!stopped)
+                hold(parse(x));
+        }, (e) => {
+            rereading = false;
+            if (!stopped)
+                o.onError?.(e);
+        });
+    };
     const es = new ES(url);
     es.addEventListener("pools", (e) => {
         if (stopped)
             return;
         try {
-            onAnswer(parse(JSON.parse(String(e.data))));
+            hold(parse(JSON.parse(String(e.data))));
         }
         catch (err) {
             o.onError?.(err);
         }
     });
+    const apply = o.change;
+    if (apply) {
+        es.addEventListener("change", (e) => {
+            if (stopped || rereading)
+                return;
+            let next = null;
+            try {
+                next = held === null ? null : apply(held, JSON.parse(String(e.data)));
+            }
+            catch {
+                next = null;
+            }
+            if (next === null)
+                reread();
+            else
+                hold(next);
+        });
+    }
     es.onopen = () => o.onOpen?.();
     es.onerror = (e) => o.onError?.(e);
     return () => {
@@ -300,3 +351,172 @@ export async function readDiscoveryList(discovery, fetchFn) {
 export async function readDiscoveryDeploy(discovery, tokenId, fetchFn) {
     return getBytes(`${trim(discovery)}/${encodeURIComponent(tokenId)}/deploy`, fetchFn);
 }
+const intOrNull = (x) => (typeof x === "number" && Number.isFinite(x) ? x : null);
+const int = (x) => intOrNull(x) ?? 0;
+function toPrice(x) {
+    const p = x;
+    if (!p || typeof p !== "object" || p.sats === undefined || p.tokens === undefined)
+        return null;
+    return { sats: wireBig(p.sats), tokens: wireBig(p.tokens) };
+}
+/** A trade row, or null when it is not one. */
+export function toTrade(x) {
+    const r = x;
+    if (!r || typeof r !== "object" || typeof r.txid !== "string" || typeof r.lpPubKey !== "string" || (r.side !== "buy" && r.side !== "sell"))
+        return null;
+    return {
+        txid: r.txid.toLowerCase(),
+        lpPubKey: r.lpPubKey.toLowerCase(),
+        side: r.side,
+        amountIn: wireBig(r.amountIn),
+        amountOut: wireBig(r.amountOut),
+        feeLp: wireBig(r.feeLp),
+        feeValidator: wireBig(r.feeValidator),
+        feeCommission: wireBig(r.feeCommission),
+        bsvReserve: wireBig(r.bsvReserve),
+        tokenReserve: wireBig(r.tokenReserve),
+        at: int(r.at),
+        height: intOrNull(r.height),
+    };
+}
+function toCandle(x) {
+    const r = x;
+    if (!r || typeof r !== "object")
+        return null;
+    const [o, h, l, c] = [toPrice(r.o), toPrice(r.h), toPrice(r.l), toPrice(r.c)];
+    if (!o || !h || !l || !c || typeof r.t !== "number")
+        return null;
+    return { t: r.t, o, h, l, c, volumeSats: wireBig(r.volumeSats), volumeTokens: wireBig(r.volumeTokens), n: int(r.n) };
+}
+/** A stats record (H3), or null when it is not one. */
+export function toStats(x) {
+    const r = x;
+    if (!r || typeof r !== "object" || typeof r.tokenId !== "string")
+        return null;
+    return {
+        tokenId: r.tokenId,
+        price: toPrice(r.price),
+        change1h: intOrNull(r.change1h),
+        change24h: intOrNull(r.change24h),
+        volume24hSats: wireBig(r.volume24hSats),
+        volume24hTokens: wireBig(r.volume24hTokens),
+        buys24h: int(r.buys24h),
+        sells24h: int(r.sells24h),
+        lastTradeAt: intOrNull(r.lastTradeAt),
+        tvlSats: wireBig(r.tvlSats),
+        tvlTokens: wireBig(r.tvlTokens),
+        pools: int(r.pools),
+    };
+}
+/** A `change` event's data, or null when it is not one this client knows. */
+export function parseChange(x) {
+    const r = x;
+    if (!r || typeof r !== "object" || typeof r.outpoint !== "string")
+        return null;
+    if (r.kind !== "deploy" && r.kind !== "swap" && r.kind !== "close" && r.kind !== "rescind")
+        return null;
+    const pool = r.pool === undefined ? null : toPoolRow(r.pool);
+    const trade = r.trade === undefined ? null : toTrade(r.trade);
+    return { kind: r.kind, outpoint: r.outpoint, ...(pool ? { pool } : {}), ...(trade ? { trade } : {}) };
+}
+const sameOutpoint = (a, b) => a.toLowerCase().replace(".", "_") === b.toLowerCase().replace(".", "_");
+/**
+ * One `change` applied to a held P2 answer (D7) → the new answer, or null when it cannot be applied
+ * (the caller reads the route again): `swap` — the row of `trade.lpPubKey` replaced by `pool` (its
+ * outpoint moved); `deploy` — `pool` added; `close` / `rescind` — the row at `outpoint` removed.
+ * The market and the validators are kept (a change of either comes as a whole `pools` answer).
+ */
+export function applyPoolChange(held, x) {
+    const ch = parseChange(x);
+    if (!ch)
+        return null;
+    switch (ch.kind) {
+        case "swap": {
+            if (!ch.pool || !ch.trade)
+                return null;
+            const i = held.pools.findIndex((p) => p.lpPubKey === ch.trade.lpPubKey);
+            if (i < 0)
+                return null;
+            const pools = held.pools.slice();
+            pools[i] = ch.pool;
+            return { ...held, pools };
+        }
+        case "deploy":
+            if (!ch.pool)
+                return null;
+            return { ...held, pools: [...held.pools, ch.pool] };
+        case "close":
+        case "rescind": {
+            const pools = held.pools.filter((p) => !sameOutpoint(p.outpoint, ch.outpoint));
+            if (pools.length === held.pools.length)
+                return null;
+            return { ...held, pools };
+        }
+    }
+}
+const query = (q) => {
+    const kv = Object.entries(q).filter(([, x]) => x !== undefined).map(([k, x]) => `${k}=${encodeURIComponent(String(x))}`);
+    return kv.length ? `?${kv.join("&")}` : "";
+};
+/** H1: `GET <base>/trades?from=&to=&limit=&before=&lp=` → the page, newest first. */
+export async function readTrades(base, o = {}, fetchFn) {
+    const a = (await getJson(`${trim(base)}/trades${query({ from: o.from, to: o.to, limit: o.limit, before: o.before, lp: o.lp })}`, fetchFn));
+    return {
+        trades: (Array.isArray(a?.trades) ? a.trades : []).map(toTrade).filter((t) => t !== null),
+        next: typeof a?.next === "string" ? a.next : null,
+    };
+}
+/** H1 with `txid`: one Swap's trade row; null when the transaction has none (404). */
+export async function readTrade(base, txid, fetchFn) {
+    const url = `${trim(base)}/trades?txid=${encodeURIComponent(txid)}`;
+    const res = await (fetchFn ?? plain)(url, { headers: { accept: "application/json" } });
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`GET ${url}: ${res.status} ${(await res.text()).slice(0, 200)}`);
+    return toTrade(await res.json());
+}
+/** H2: `GET <base>/candles?tf=&from=&to=` → one candle per non-empty bucket, oldest first. */
+export async function readCandles(base, o, fetchFn) {
+    const a = await getJson(`${trim(base)}/candles${query({ tf: o.tf, from: o.from, to: o.to })}`, fetchFn);
+    return (Array.isArray(a) ? a : []).map(toCandle).filter((c) => c !== null);
+}
+/** H3: `GET <base>/stats`. */
+export async function readStats(base, fetchFn) {
+    const url = `${trim(base)}/stats`;
+    const s = toStats(await getJson(url, fetchFn));
+    if (!s)
+        throw new Error(`GET ${url}: not a stats record`);
+    return s;
+}
+/** H4: `GET <swap base>/stats` (`ids`: those enabled tokens only, in that order) → every enabled token's stats. */
+export async function readAllStats(swapBase, ids, fetchFn) {
+    const a = await getJson(`${trim(swapBase)}/stats${ids ? `?ids=${list(ids)}` : ""}`, fetchFn);
+    return (Array.isArray(a) ? a : []).map(toStats).filter((s) => s !== null);
+}
+/** H6: `GET <token base>/color/<token>/holders?limit=&skip=` → the count and the rows, largest first. */
+export async function readHolders(base, tokenId, o = {}, fetchFn) {
+    const a = (await getJson(`${trim(base)}/color/${encodeURIComponent(tokenId)}/holders${query({ limit: o.limit, skip: o.skip })}`, fetchFn));
+    return {
+        count: int(a?.count),
+        rows: (Array.isArray(a?.rows) ? a.rows : []).filter((r) => r && typeof r.address === "string").map((r) => ({ address: String(r.address), balance: wireBig(r.balance) })),
+    };
+}
+/** H5: `GET <swap base>/positions?lp=k1,k2` → every enabled token's rows for the keys, each with its token. */
+export async function readAllPositions(swapBase, lpPubKeys, fetchFn) {
+    if (lpPubKeys.length === 0)
+        return [];
+    const a = await getJson(`${trim(swapBase)}/positions?lp=${list(lpPubKeys)}`, fetchFn);
+    return (Array.isArray(a) ? a : [])
+        .filter((r) => r && typeof r.tokenId === "string" && typeof r.lpPubKey === "string")
+        .map((r) => ({
+        tokenId: String(r.tokenId),
+        lpPubKey: String(r.lpPubKey),
+        status: r.status === "live" || r.status === "rescinded" ? r.status : "closed",
+        outpoint: typeof r.outpoint === "string" ? r.outpoint : null,
+        current: isWirePool(r.current) ? toPoolState(r.current) : null,
+        sats: wireBig(r.sats),
+        tokens: wireBig(r.tokens),
+        swaps: Number(r.swaps ?? 0),
+    }));
+}

package/dist/market/prices.d.ts

@@ -1,8 +1,8 @@
 /**
- * Prices (0.34.0, D6, David Case 2026-11-04: one source for prices): a token's price comes from
- * its pool list — the pools route the host answers (`GET <origin>/amm/pools`, held as an event
- * stream on every page) — Σsats / Σtokens over the pools listed there (the host lists only pools
- * whose validator is beating). No price is derived from beats (the 0.9.0 beat prices are gone);
+ * Prices (0.34.0, D6, David Case 2026-11-04: one source for prices; 0.39.0, D3, D7): a token's
+ * listed price comes from the host-wide stats (`GET <origin>/amm/stats`, read once per load and
+ * every 30 s while the tab is visible; no host-wide stream), the Swap page's quote from the pools
+ * its token's pools route lists. No price is derived from beats (the 0.9.0 beat prices are gone);
  * the depth is the sats a buy needs to move the price up by 2%, x·(√1.02 − 1), over the summed
  * sats.
  */

package/dist/market/prices.js

@@ -1,8 +1,8 @@
 /**
- * Prices (0.34.0, D6, David Case 2026-11-04: one source for prices): a token's price comes from
- * its pool list — the pools route the host answers (`GET <origin>/amm/pools`, held as an event
- * stream on every page) — Σsats / Σtokens over the pools listed there (the host lists only pools
- * whose validator is beating). No price is derived from beats (the 0.9.0 beat prices are gone);
+ * Prices (0.34.0, D6, David Case 2026-11-04: one source for prices; 0.39.0, D3, D7): a token's
+ * listed price comes from the host-wide stats (`GET <origin>/amm/stats`, read once per load and
+ * every 30 s while the tab is visible; no host-wide stream), the Swap page's quote from the pools
+ * its token's pools route lists. No price is derived from beats (the 0.9.0 beat prices are gone);
  * the depth is the sats a buy needs to move the price up by 2%, x·(√1.02 − 1), over the summed
  * sats.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcasegr/amm-client",
-  "version": "0.38.1",
+  "version": "0.39.0",
   "type": "module",
   "description": "The Open Exchange client (skein-amm): reads, swap, pool deploy / close / rebalance, move back and positions over a BRC-100 wallet, bound to one exchange by createClient. No React, no styles, no wallet provider.",
   "repository": {
@@ -29,8 +29,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@1sat/actions": "0.1.2",
-    "@dcasegr/amm-engine": "0.38.1",
+    "@1sat/actions": "0.1.3",
+    "@dcasegr/amm-engine": "0.39.0",
     "cbor2": "^2.3.0"
   },
   "peerDependencies": {