tapimo 0.0.0 → 0.0.2

package/dist/apps/exchanges.js

@@ -0,0 +1,3570 @@
+import { Hono } from 'hono';
+import { AbiEvent } from 'ox';
+import { BaseError, ContractFunctionRevertedError, decodeFunctionData, parseAbi, } from 'viem';
+import { Actions, Addresses, Tick } from 'viem/tempo';
+import * as z from 'zod/mini';
+import * as Auth from '../internal/Auth.js';
+import * as Cache from '../internal/Cache.js';
+import * as Cursor from '../internal/Cursor.js';
+import * as OpenApi from '../internal/OpenApi.js';
+import * as Response from '../internal/Response.js';
+import * as Schema from '../internal/Schema.js';
+import * as Store from '../internal/Store.js';
+import * as Timing from '../internal/Timing.js';
+import * as Ttl from '../internal/Ttl.js';
+import * as Value from '../internal/Value.js';
+import * as VerifiedTokens from '../internal/VerifiedTokens.js';
+import * as Tokens from './tokens.js';
+// Stablecoin DEX precompile. Pair lifecycle is announced by `PairCreated` from
+// this address; the indexer pre-decodes those into the `dex_pairs` table.
+const stablecoinDex = Addresses.stablecoinDex.toLowerCase();
+// `OrderCancelled(uint128 orderId)` — emitted when a maker cancels a resting
+// order. Used by the orders endpoint to exclude cancelled orders from the
+// resting set.
+const orderCancelledSignature = 'event OrderCancelled(uint128 indexed orderId)';
+// Topic0 hashes of the DEX order-state events. The swap feed resolves each
+// fill's `(token, isBid, tick)` point-in-time from the raw `logs` event
+// stream instead of the decoded `dex_orders` table: T5+ flip orders keep
+// their `orderId`, mutate `(isBid, tick)` on every flip, and emit only
+// `OrderFlipped` (no `OrderPlaced`), so `dex_orders` is both incomplete and
+// stale for them.
+const orderPlacedTopic = AbiEvent.getSelector('event OrderPlaced(uint128 indexed orderId, address indexed maker, address indexed token, uint128 amount, bool isBid, int16 tick, bool isFlipOrder, int16 flipTick)');
+const orderFlippedTopic = AbiEvent.getSelector('event OrderFlipped(uint128 indexed orderId, address indexed maker, address indexed token, uint128 amount, bool isBid, int16 tick, int16 flipTick)');
+// Block-range window for every `dex_fills` GROUP BY batch in the swaps feed.
+// An unbounded grouped scan aggregates the entire fill history just to emit the
+// top `limit + 1` groups, which TIDX rejects outright (HTTP 422) once the table
+// grows large enough — so the scan is *always* bounded to a block window and
+// the loop slides the window across batches until the page fills or the feed is
+// exhausted. The window must comfortably hold a max-`limit` page (200 groups):
+// 100k blocks (~28h) holds ~180k fills on Moderato. A group is keyed by
+// `(block_num, tx_hash, taker)`, so a block-range bound never splits one group
+// across windows; the value only tunes how many round-trips the sweep takes.
+const swapWindowBlocks = 100_000;
+// Swap entrypoints of the stablecoin DEX. A swap's `mode` (exact-source vs
+// exact-destination) is not in the events — it is recovered by decoding the
+// transaction calldata (direct calls and AA type-`0x76` inner calls) against
+// these signatures.
+const swapAbi = parseAbi([
+    'function swapExactAmountIn(address tokenIn, address tokenOut, uint128 amountIn, uint128 minAmountOut) returns (uint128)',
+    'function swapExactAmountOut(address tokenIn, address tokenOut, uint128 amountOut, uint128 maxAmountIn) returns (uint128)',
+]);
+// Example pair base token used by the OpenAPI route examples. Picked so the
+// rendered URL addresses a realistic, well-known pair (USDC.e, quoted in
+// pathUSD on-chain). Uses a fresh `Schema.tokenAddress(...)` so the example
+// reaches the pipe input that path-param OpenAPI generation reads from.
+const exampleBase = '0x20c000000000000000000000b9537d11c60e8b50';
+/**
+ * Tick spacing enforced by the stablecoin DEX precompile: orders must be
+ * placed at ticks divisible by 10 (a 1 bp price grid). Walking the depth at
+ * this stride probes every valid level without wasting RPC calls on slots the
+ * DEX rejects at order placement. Not currently exported by `ox/tempo`; the
+ * upstream invariant is documented in the Tempo DEX spec.
+ */
+const tickSpacing = 10;
+/**
+ * Default number of non-empty price levels returned per side when callers
+ * omit `levels`. Wide enough to cover a typical depth chart's foreground while
+ * keeping the payload compact; well-traded pairs that cluster liquidity near
+ * peg fit comfortably inside this cap.
+ */
+const defaultDepthLevels = 50;
+/**
+ * Hard ceiling on `levels`. The DEX tick range (`Tick.minTick`..`Tick.maxTick`)
+ * exposes at most 201 valid positions per side at `tickSpacing=10`, so 200 is
+ * an effective full-book cap and bounds the per-request multicall payload.
+ */
+const maxDepthLevels = 200;
+/**
+ * Maximum number of buckets a single OHLC request may produce. Combined with
+ * the OHLC `Interval` and `Window` enums this bounds the aggregation work
+ * and the response size: e.g. `interval=1m, window=24h` produces 1440
+ * buckets and is rejected as `query_invalid`. Hoisted above the schema
+ * namespace because the OHLC `Query` refine references it at validation time.
+ */
+const maxBuckets = 500;
+/** Converts the OHLC `interval` enum to a millisecond duration. */
+function intervalMs(interval) {
+    switch (interval) {
+        case '1m':
+            return 60 * 1000;
+        case '5m':
+            return 5 * 60 * 1000;
+        case '15m':
+            return 15 * 60 * 1000;
+        case '1h':
+            return 60 * 60 * 1000;
+        case '4h':
+            return 4 * 60 * 60 * 1000;
+        case '1d':
+            return 24 * 60 * 60 * 1000;
+    }
+}
+/**
+ * Formats an ISO-8601 datetime string (e.g. `2026-06-04T12:00:00Z`) into the
+ * `YYYY-MM-DD HH:MM:SS` form ClickHouse accepts for `DateTime64(3, 'UTC')`
+ * comparisons. The ISO-Z form rejects with a conversion error on ClickHouse
+ * `DateTime64`. Input is trusted (validated upstream by Zod / produced by
+ * `Date.toISOString()` internally).
+ */
+function formatClickHouseDateTime(value) {
+    return value
+        .replace('T', ' ')
+        .replace(/\.\d+Z$/, '')
+        .replace(/Z$/, '');
+}
+/** Converts the OHLC `window` enum to a millisecond duration. */
+function windowMs(window) {
+    switch (window) {
+        case '1h':
+            return 60 * 60 * 1000;
+        case '24h':
+            return 24 * 60 * 60 * 1000;
+        case '7d':
+            return 7 * 24 * 60 * 60 * 1000;
+        case '30d':
+            return 30 * 24 * 60 * 60 * 1000;
+    }
+}
+/** Zod schemas owned by the exchange handlers. */
+export var schema;
+(function (schema) {
+    /**
+     * A token in a trading pair: its contract address, plus the trimmed token
+     * reference spread in when requested via `include=tokens`. Reference fields
+     * are absent on the base (no-`include`) response and best-effort when
+     * requested (a token whose metadata is unavailable keeps just `address`).
+     */
+    schema.PairToken = Schema.describe(z.object({
+        address: Schema.TokenAddress.check(z.describe('TIP-20 token contract address — the `0x`-prefixed 20-byte identifier for this token.'), z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] })),
+        currency: z
+            .optional(z.string())
+            .check(z.describe('Human-readable currency code for the token, when known.'), z.meta({ examples: ['USD'] })),
+        decimals: z
+            .optional(z.number().check(z.int(), z.nonnegative()))
+            .check(z.describe('Number of decimal places the token uses; stablecoins on Tempo typically use 6.'), z.meta({ examples: [6] })),
+        logoUri: z.optional(z.string()).check(z.describe('URL for the token logo SVG, when one is available.'), z.meta({
+            examples: [
+                'https://api.tempo.xyz/data/4217/icons/0x20c0000000000000000000008f5425160ebe5525.svg',
+            ],
+        })),
+        name: z
+            .optional(z.string())
+            .check(z.describe('Human-readable token name, such as `USD Coin`.'), z.meta({ examples: ['USD Coin'] })),
+        symbol: z
+            .optional(z.string())
+            .check(z.describe('Short token ticker symbol, such as `USDC`.'), z.meta({ examples: ['USDC'] })),
+        verified: z
+            .optional(z.boolean())
+            .check(z.describe('Whether Tempo has verified this token metadata.'), z.meta({ examples: [true] })),
+    }), 'One side of a trading pair (with metadata when requested via `include=tokens`).');
+    /** Schemas for the getPairs operation. */
+    let getPairs;
+    (function (getPairs) {
+        /**
+         * Optional resources for the pair list: the per-row `tokens` embed plus the
+         * response-wide capped `totalCount`. The detail route keeps its own
+         * `tokens`-only {@link getPair.Include}.
+         */
+        getPairs.Include = z
+            .enum(['tokens', 'totalCount'])
+            .check(z.describe('Extra resources you can request with `include`, such as token metadata or a total count.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed. Extra lookups (e.g. token metadata) only run when
+         * explicitly requested, keeping the base pair page fast.
+         */
+        getPairs.includeQuery = Schema.includeQuery(getPairs.Include, 'Comma-separated optional resources to embed, e.g. `tokens,totalCount`.');
+        /** Query parameters for trading pair list requests. */
+        getPairs.Query = z
+            .strictObject({
+            chainId: Schema.ChainIdQuery,
+            cursor: Schema.Cursor,
+            include: getPairs.includeQuery,
+            limit: Schema.Limit,
+            order: Schema.Order,
+            page: Schema.Page,
+            sort: z
+                ._default(z.enum(['created', 'liquidity']), 'created')
+                .check(z.describe('Sort key: `created` orders by when the pair was created, while `liquidity` ranks by the DEX-held base-token balance as a practical liquidity signal.'), z.meta({ examples: ['created'] })),
+        })
+            .check(...Schema.pageChecks(), z.describe('Filters, pagination, and sorting options for listing exchange trading pairs.'));
+        /** A single trading pair on the stablecoin DEX. */
+        getPairs.Pair = z
+            .object({
+            base: schema.PairToken.check(z.describe('Base token — the asset whose price is quoted in the pair.')),
+            blockNumber: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Block number where the pair was created.'), z.meta({ examples: [23456789] })),
+            id: Schema.Hash.check(z.describe('Stable API id for this pair; it is the same value as the onchain pair key.')),
+            key: Schema.Hash.check(z.describe('Stable onchain pair identifier returned by the DEX precompile as `pairKey`.')),
+            liquidity: z
+                .optional(z
+                .string()
+                .check(z.regex(/^\d+$/), z.describe('Liquidity signal for the pair: the base-token balance held by the DEX, returned as a decimal integer string in the token’s smallest units. Present only when `sort=liquidity`.')))
+                .check(z.describe('Liquidity signal for the pair, present only when you request `sort=liquidity`.'), z.meta({ examples: ['1000000'] })),
+            quote: schema.PairToken.check(z.describe('Quote token — the asset used to price the base token.')),
+            timestamp: z.iso
+                .datetime()
+                .check(z.describe('Block timestamp when the pair was created.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+            transactionHash: Schema.Hash.check(z.describe('Transaction hash for the transaction that created the pair.')),
+        })
+            .check(z.describe('One trading pair on Tempo’s built-in stablecoin exchange.'));
+        /** Page of trading pairs on the stablecoin DEX, ordered by creation. */
+        getPairs.Response = z
+            .object({
+            data: z.array(getPairs.Pair).check(z.describe('Trading pairs returned on this page.')),
+            meta: z
+                .optional(Schema.CountMeta)
+                .check(z.describe('Response-level resources requested with `include`, such as `totalCount`.')),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A paginated list of trading pairs on Tempo’s built-in stablecoin exchange.'));
+    })(getPairs = schema.getPairs || (schema.getPairs = {}));
+    /** Schemas for the getPair operation (single trading pair detail). */
+    let getPair;
+    (function (getPair) {
+        /**
+         * Path parameter for pair detail requests. On-chain, a pair's quote is
+         * intrinsic to its base token (the precompile resolves it from the TIP-20's
+         * `quote_token()`), so the base address alone identifies the pair.
+         */
+        getPair.Params = z
+            .object({
+            base: Schema.tokenAddress(exampleBase).check(z.describe('Base token address for the trading pair.')),
+        })
+            .check(z.describe('Path parameters for looking up a trading pair.'));
+        /** Optional related resource that callers opt into via `include`. */
+        getPair.Include = z
+            .enum(['tokens'])
+            .check(z.describe('Related resource you can opt into with `include`.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed.
+         */
+        getPair.includeQuery = Schema.includeQuery(getPair.Include, 'Comma-separated optional resources to embed, e.g. `tokens`.');
+        /** Query parameters for pair detail requests. */
+        getPair.Query = z
+            .strictObject({
+            chainId: Schema.ChainIdQuery,
+            include: getPair.includeQuery,
+        })
+            .check(z.describe('Query options for fetching one trading pair.'));
+        /** A single trading pair, identical in shape to `GET /exchange/pairs` rows. */
+        getPair.Response = getPairs.Pair;
+    })(getPair = schema.getPair || (schema.getPair = {}));
+    /** Schemas for the getSwaps operation (the swap feed, optionally pair-scoped). */
+    let getSwaps;
+    (function (getSwaps) {
+        /**
+         * Optional related resource that callers opt into via `include`. Currently
+         * only `tokens` (embeds metadata for both pair tokens on each row's
+         * `sourceToken`/`destinationToken`).
+         */
+        getSwaps.Include = z
+            .enum(['tokens'])
+            .check(z.describe('Related resource you can opt into with `include`.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed. Extra lookups (e.g. token metadata) only run when
+         * explicitly requested, keeping the base swap feed fast.
+         */
+        getSwaps.includeQuery = Schema.includeQuery(getSwaps.Include, 'Comma-separated optional resources to embed, e.g. `tokens`.');
+        /** Query parameters for swap feed requests. */
+        getSwaps.Query = z
+            .strictObject({
+            'blockNumber.from': Schema.blockNumberBound('swaps', 'from'),
+            'blockNumber.to': Schema.blockNumberBound('swaps', 'to'),
+            chainId: Schema.ChainIdQuery,
+            cursor: Schema.Cursor,
+            include: getSwaps.includeQuery,
+            limit: Schema.Limit,
+            maker: z
+                .optional(Schema.Address)
+                .check(z.describe('Only include swaps that filled against an order owned by this maker address.')),
+            order: Schema.Order,
+            participant: z
+                .optional(Schema.Address)
+                .check(z.describe('Only include swaps where this address participated as the taker or as a maker whose order was filled.')),
+            taker: z
+                .optional(Schema.Address)
+                .check(z.describe('Only include swaps initiated by this taker address.')),
+            'timestamp.from': Schema.timestampBound('swaps', 'from'),
+            'timestamp.to': Schema.timestampBound('swaps', 'to'),
+            transactionHash: z
+                .optional(Schema.Hash)
+                .check(z.describe('Only include swaps included in this transaction hash.')),
+        })
+            .check(z.describe('Query parameters for swap feed requests. Cursor-paginated only — a batched ' +
+            'transaction expands one fill group into a variable number of swap rows, so a ' +
+            'positional `page` has no stable meaning on this feed.'));
+        /**
+         * One side of a swap: a `PairToken` (address plus optional metadata when
+         * requested via `include=tokens`) annotated with the `amount` that moved
+         * on this side, as a decimal integer string in base units.
+         */
+        getSwaps.SwapSide = z
+            .extend(schema.PairToken, {
+            amount: Schema.DecimalString.check(z.describe('Amount moved on this side, returned as a decimal integer string in the token’s smallest units.'), z.meta({ examples: ['1000000'] })),
+        })
+            .check(z.describe('One side of a swap: the token and amount that moved.'));
+        /** A single maker-order fill within a swap, framed from the taker's perspective. */
+        getSwaps.Fill = z
+            .object({
+            destinationToken: getSwaps.SwapSide.check(z.describe('Token and amount the taker received in this fill, with token metadata when requested via `include=tokens`.')),
+            logIndex: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Log index of this fill within its block.'), z.meta({ examples: [0] })),
+            maker: Schema.Address.check(z.describe('Maker address whose resting order was filled.')),
+            orderId: Schema.DecimalString.check(z.describe('On-chain maker order id, returned as a decimal string.')),
+            partialFill: z
+                .boolean()
+                .check(z.describe('Whether this fill used only part of the maker order.'), z.meta({ examples: [false] })),
+            price: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Quote-per-base price at fill time, returned as a fixed-decimal string with 5 decimal places. This value is direction-independent and works well for charts.'), z.meta({ examples: ['1.00000'] })),
+            sourceToken: getSwaps.SwapSide.check(z.describe('Token and amount the taker sent in this fill, with token metadata when requested via `include=tokens`.')),
+        })
+            .check(z.describe('One maker-order fill within a swap, described from the taker’s perspective.'));
+        /**
+         * A single logical taker swap on the stablecoin DEX: every maker-order
+         * fill one taker's swap produced in one transaction, assembled into a
+         * source → destination row. Multi-hop swaps (routed through an
+         * intermediate token, e.g. pathUSD) are one row; the intermediate hops
+         * are visible via `route` and `fills`.
+         */
+        getSwaps.Swap = z
+            .object({
+            blockNumber: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Block number where the swap was included.'), z.meta({ examples: [23456789] })),
+            destinationToken: getSwaps.SwapSide.check(z.describe('Destination side of the swap: what the taker received, summed across the final hop.')),
+            filledAt: z.iso
+                .datetime()
+                .check(z.describe('Block timestamp when the swap was filled onchain.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+            fills: z
+                .array(getSwaps.Fill)
+                .check(z.describe('Maker-order fills that make up this swap, ordered by execution `logIndex`. Exact-destination swaps can execute hops in reverse, so use `route` for the source-to-destination path.')),
+            id: z.string().check(z.describe('Stable API id built from the lowercase transaction hash and the first fill log index.'), z.meta({
+                examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-0'],
+            })),
+            logIndex: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Block-wide log index for the swap, taken from its first fill.'), z.meta({ examples: [0] })),
+            mode: z
+                .nullable(z.enum(['exactSource', 'exactDestination']))
+                .check(z.describe('The amount type fixed by the swap call: `exactSource` for `swapExactAmountIn` or `exactDestination` for `swapExactAmountOut`. This is recovered from transaction calldata and is `null` when the swap did not come from a decodable swap call.'), z.meta({ examples: ['exactSource'] })),
+            rate: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Swap-level effective rate, calculated as destination amount divided by source amount from the taker’s perspective and returned with 5 decimal places. Compare it with `1` to see distance from peg.'), z.meta({ examples: ['1.00000'] })),
+            route: z
+                .array(Schema.TokenAddress)
+                .check(z.describe('Token path for the swap, from source through any intermediate tokens to destination. `route.length - 1` is the hop count; two entries means a direct swap.')),
+            sourceToken: getSwaps.SwapSide.check(z.describe('Source side of the swap: what the taker sent, summed across the first hop.')),
+            taker: Schema.Address.check(z.describe('Taker address that initiated the swap.')),
+            transactionHash: Schema.Hash.check(z.describe('Transaction hash for the transaction containing the swap.')),
+        })
+            .check(z.describe('One logical taker swap on Tempo’s built-in stablecoin exchange.'));
+        /**
+         * Page of swaps. A row is one logical taker swap — the fills of one
+         * `(transaction, taker)` group chained source → destination — so the
+         * unscoped and token-filtered feeds share one shape. `limit` caps the
+         * rows per page; a transaction batching several unrelated swaps by one
+         * taker may have its rows split across consecutive pages.
+         */
+        getSwaps.Response = z
+            .object({
+            data: z.array(getSwaps.Swap).check(z.describe('Swaps returned on this page.')),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A paginated list of swaps on Tempo’s built-in stablecoin exchange.'));
+    })(getSwaps = schema.getSwaps || (schema.getSwaps = {}));
+    /** Schemas for the getPairOhlc operation (candlestick aggregations). */
+    let getPairOhlc;
+    (function (getPairOhlc) {
+        /**
+         * Path parameter mirrors `getPair.Params`: the base address alone
+         * identifies the pair (its quote is intrinsic to the base token on-chain).
+         */
+        getPairOhlc.Params = z
+            .object({
+            base: Schema.tokenAddress(exampleBase).check(z.describe('Base token address for the trading pair.')),
+        })
+            .check(z.describe('Path parameters for fetching OHLC candles for a pair.'));
+        /** Bucket size for the candlestick aggregation. */
+        getPairOhlc.Interval = z
+            .enum(['1m', '5m', '15m', '1h', '4h', '1d'])
+            .check(z.describe('Time size for each OHLC candle bucket.'), z.meta({ examples: ['1h'] }));
+        /** Rolling lookback window for the candlestick aggregation. */
+        getPairOhlc.Window = z
+            .enum(['1h', '24h', '7d', '30d'])
+            .check(z.describe('Rolling time window covered by the OHLC candles.'), z.meta({ examples: ['24h'] }));
+        /**
+         * Optional related resource that callers opt into via `include`. Currently
+         * only `tokens` (embeds metadata onto `base`/`quote` instead of returning
+         * just the addresses).
+         */
+        getPairOhlc.Include = z
+            .enum(['tokens'])
+            .check(z.describe('Related resource you can opt into with `include`.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed.
+         */
+        getPairOhlc.includeQuery = Schema.includeQuery(getPairOhlc.Include, 'Comma-separated optional resources to embed, e.g. `tokens`.');
+        /** Query parameters for pair OHLC requests. */
+        getPairOhlc.Query = z
+            .strictObject({
+            chainId: Schema.ChainIdQuery,
+            include: getPairOhlc.includeQuery,
+            interval: z._default(getPairOhlc.Interval, '1h').check(z.meta({ examples: ['1h'] })),
+            window: z._default(getPairOhlc.Window, '24h').check(z.meta({ examples: ['24h'] })),
+        })
+            .check(z.refine((query) => windowMs(query.window) / intervalMs(query.interval) <= maxBuckets, {
+            error: `Requested \`window\` / \`interval\` produces more than ${maxBuckets} buckets. Pick a longer \`interval\` or a shorter \`window\`.`,
+            path: ['interval'],
+        }))
+            .check(z.describe('Query options for fetching OHLC candles for a pair.'));
+        /**
+         * A single candlestick bucket. Open/close are picked from the earliest
+         * and latest fill in the bucket (ordered by `(block_num, log_idx)`); high
+         * and low are the extrema across all fills in the bucket. Volumes are
+         * the sum of per-fill base- and quote-side amounts in base units.
+         */
+        getPairOhlc.Bucket = z
+            .object({
+            close: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Close price for the bucket: the latest fill rate, returned with 5 decimal places.'), z.meta({ examples: ['1.00000'] })),
+            fillCount: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Number of fills included in this bucket.'), z.meta({ examples: [5] })),
+            high: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('High price for the bucket: the highest fill rate, returned with 5 decimal places.'), z.meta({ examples: ['1.01000'] })),
+            id: z.string().check(z.describe('Stable API id built from the pair key, candle interval, and bucket start time in Unix seconds.'), z.meta({
+                examples: [
+                    '0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-1h-1704067200',
+                ],
+            })),
+            low: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Low price for the bucket: the lowest fill rate, returned with 5 decimal places.'), z.meta({ examples: ['0.99000'] })),
+            open: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Open price for the bucket: the earliest fill rate, returned with 5 decimal places.'), z.meta({ examples: ['1.00000'] })),
+            timestamp: z.iso
+                .datetime()
+                .check(z.describe('ISO 8601 timestamp for the start of this candle bucket.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+            volume: z
+                .object({
+                base: Schema.DecimalString.check(z.describe('Total base-side amount filled in this bucket, in the token’s smallest units.')),
+                quote: Schema.DecimalString.check(z.describe('Total quote-side amount filled in this bucket, reconstructed from each fill’s tick and returned in the token’s smallest units.')),
+            })
+                .check(z.describe('Total filled volume in this bucket, split by pair side.')),
+        })
+            .check(z.describe('One OHLC candle bucket for charting a trading pair.'));
+        /** Page of candlestick buckets for a single trading pair. */
+        getPairOhlc.Response = z
+            .object({
+            base: schema.PairToken.check(z.describe('Base side of the trading pair.')),
+            data: z
+                .array(getPairOhlc.Bucket)
+                .check(z.describe('OHLC candle buckets ordered oldest to newest; empty buckets are omitted.')),
+            interval: getPairOhlc.Interval,
+            quote: schema.PairToken.check(z.describe('Quote side of the trading pair.')),
+            truncated: z
+                .boolean()
+                .check(z.describe('`true` when the fill scan hit its hard cap, meaning OHLC values were computed from only the most recent fills.'), z.meta({ examples: [false] })),
+            window: getPairOhlc.Window,
+        })
+            .check(z.describe('OHLC candle data for one trading pair over a rolling time window.'));
+    })(getPairOhlc = schema.getPairOhlc || (schema.getPairOhlc = {}));
+    /** Schemas shared by the order detail and order fills handlers. */
+    let order;
+    (function (order) {
+        /** Path parameters for any single-order route (`/orders/:orderId`). */
+        order.Params = z
+            .object({
+            orderId: Schema.DecimalString.check(z.describe('On-chain order id, returned as a decimal string.'), z.meta({ examples: ['1'] })),
+        })
+            .check(z.describe('Path parameters for routes that look up one order.'));
+        /** The pair the order is placed against. */
+        order.Pair = Schema.describe(z.object({
+            base: schema.PairToken.check(z.describe('Base side of the pair; the order trades this token.')),
+            key: Schema.Hash.check(z.describe('On-chain key for this `(base, quote)` trading pair.')),
+            quote: schema.PairToken.check(z.describe('Quote side of the trading pair.')),
+        }), 'The trading pair the order belongs to.');
+    })(order = schema.order || (schema.order = {}));
+    /** Schemas for the getOrder operation. */
+    let getOrder;
+    (function (getOrder) {
+        /** Path parameters for single-order requests. */
+        getOrder.Params = order.Params;
+        /**
+         * Optional related resource that callers opt into via `include`. Currently
+         * only `tokens` (embeds metadata for both pair tokens on `pair.base` and
+         * `pair.quote`).
+         */
+        getOrder.Include = z
+            .enum(['tokens'])
+            .check(z.describe('Related resource you can opt into with `include`.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed. Extra lookups (e.g. pair-token metadata) only run
+         * when explicitly requested, keeping the base order response fast.
+         */
+        getOrder.includeQuery = Schema.includeQuery(getOrder.Include, 'Comma-separated optional resources to embed, e.g. `tokens`.');
+        /** Query parameters for single-order requests. */
+        getOrder.Query = z
+            .strictObject({
+            chainId: Schema.ChainIdQuery,
+            include: getOrder.includeQuery,
+        })
+            .check(z.describe('Query options for fetching one order.'));
+        /**
+         * A single DEX order. Placement parameters and current state are sourced
+         * directly from the on-chain `dex.getOrder` view, so `remaining` reflects
+         * live state (not indexer lag) and the response is a single fast RPC.
+         *
+         * Fills are paginated separately under
+         * `GET /exchange/orders/{orderId}/fills`; the per-order fills feed grows
+         * over time and would otherwise force this resource to revalidate on
+         * every new fill.
+         */
+        getOrder.Response = Schema.describe(z.object({
+            amount: Schema.DecimalString.check(z.describe('Initial order size, returned as a decimal integer string in base-token smallest units.')),
+            flipTick: z
+                .number()
+                .check(z.int(), z.describe('Replacement `tick` used if this order auto-flips into a counter-order after filling.'), z.meta({ examples: [10] })),
+            id: Schema.DecimalString.check(z.describe('Stable API id for this order; it is the same value as the onchain order id.')),
+            isBid: z
+                .boolean()
+                .check(z.describe('Order side as a boolean: `true` means the maker buys base, and `false` means the maker sells base.'), z.meta({ examples: [true] })),
+            isFlipOrder: z
+                .boolean()
+                .check(z.describe('Whether this order automatically becomes a counter-order after it fills.'), z.meta({ examples: [false] })),
+            maker: Schema.Address.check(z.describe('Maker address that owns the order.')),
+            mode: z
+                .enum(['exactSource', 'exactDestination'])
+                .check(z.describe('Taker-perspective mode for the order. `exactSource` applies to maker bids where the taker sells base; `exactDestination` applies to maker asks where the taker buys base.'), z.meta({ examples: ['exactSource'] })),
+            orderId: Schema.DecimalString.check(z.describe('On-chain order id, returned as a decimal string.')),
+            pair: order.Pair,
+            price: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Quote-per-base price implied by `tick`, returned as a fixed-decimal string with 5 decimal places.'), z.meta({ examples: ['1.00000'] })),
+            rate: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Destination-to-source price ratio, returned as a fixed-decimal string with 5 decimal places.'), z.meta({ examples: ['1.00000'] })),
+            remaining: Schema.DecimalString.check(z.describe('Unfilled base-side amount still resting on the orderbook, returned as a decimal integer string.')),
+            tick: z
+                .number()
+                .check(z.int(), z.describe('On-chain signed tick, scaled by `1/priceScale`; use `price` for the decoded ratio.'), z.meta({ examples: [0] })),
+        }), 'A single DEX order with live onchain state.');
+    })(getOrder = schema.getOrder || (schema.getOrder = {}));
+    /** Schemas for the getOrders operation (the resting-order feed, optionally pair-scoped). */
+    let getOrders;
+    (function (getOrders) {
+        /**
+         * Optional resources for the order feed: the per-row `tokens` embed plus
+         * the response-wide capped `totalCount` (the number of matching resting
+         * orders, a lower bound when `truncated`).
+         */
+        getOrders.Include = z
+            .enum(['tokens', 'totalCount'])
+            .check(z.describe('Extra resources you can request with `include`, such as token metadata or a total count.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed.
+         */
+        getOrders.includeQuery = Schema.includeQuery(getOrders.Include, 'Comma-separated optional resources to embed, e.g. `tokens,totalCount`.');
+        /** Query parameters for resting-order feed requests. */
+        getOrders.Query = z
+            .strictObject({
+            base: z
+                // The shared `TokenAddress` example is pathUSD — the universal
+                // *quote* — which is never a valid base; use a real base instead.
+                .optional(Schema.tokenAddress(exampleBase))
+                .check(z.describe('Only include orders for the pair with this base token. The quote token is determined onchain from the base token, so `base` alone selects the pair; returns 404 if no pair exists.')),
+            chainId: Schema.ChainIdQuery,
+            cursor: Schema.Cursor,
+            include: getOrders.includeQuery,
+            limit: Schema.Limit,
+            maker: z
+                .optional(Schema.Address)
+                .check(z.describe('Only include orders placed by this maker address.')),
+            order: Schema.Order,
+            page: Schema.Page,
+            side: z
+                .optional(z.enum(['bid', 'ask']))
+                .check(z.describe('Limit results to one side of the orderbook: `bid` orders pay quote for base, while `ask` orders sell base for quote.'), z.meta({ examples: ['bid'] })),
+            sort: z
+                ._default(z.enum(['tick', 'time']), 'tick')
+                .check(z.describe('Sort key: `tick` orders by price in standard book order, while `time` orders by block number and log index.'), z.meta({ examples: ['tick'] })),
+        })
+            .check(z.describe('Filters, pagination, and sorting options for listing resting orders.'));
+        /**
+         * A single resting maker order, sans its pair (rows are shaped here and
+         * then annotated with their pair). `amount` is the originally-placed base
+         * amount and `remaining` is what's still on the book (`amount` minus the
+         * sum of `OrderFilled.amountFilled` over all fills for this order).
+         * Orders for which `remaining <= 0` or that have an `OrderCancelled`
+         * event are excluded from the response.
+         */
+        getOrders.RestingOrder = z
+            .object({
+            amount: Schema.DecimalString.check(z.describe('Original placed amount, returned as a decimal integer string in base-token smallest units.')),
+            blockNumber: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Block number where the order was placed.'), z.meta({ examples: [23456789] })),
+            id: Schema.DecimalString.check(z.describe('Stable API id for this order; it is the same value as the onchain order id.')),
+            logIndex: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Log index of the order placement within its block.'), z.meta({ examples: [0] })),
+            maker: Schema.Address.check(z.describe('Maker address that owns the order.')),
+            orderId: Schema.DecimalString.check(z.describe('On-chain order id, returned as a decimal string.')),
+            placedAt: z.iso
+                .datetime()
+                .check(z.describe('Block timestamp when the order was placed.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+            price: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Quote-per-base limit price implied by `tick`, returned with 5 decimal places. This value is direction-independent; use `rate` for the taker-perspective ratio.'), z.meta({ examples: ['1.00000'] })),
+            rate: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Order limit price as a destination/source ratio from the taker’s perspective, returned with 5 decimal places. Use `price` for orderbook displays.'), z.meta({ examples: ['1.00000'] })),
+            remaining: Schema.DecimalString.check(z.describe('Unfilled remainder of `amount`, returned as a decimal integer string in base-token smallest units. This is always positive for rows in this response.')),
+            side: z
+                .enum(['bid', 'ask'])
+                .check(z.describe('Orderbook side: `bid` pays quote for base, and `ask` sells base for quote.'), z.meta({ examples: ['bid'] })),
+            tick: z
+                .number()
+                .check(z.int(), z.describe('Order tick as a signed offset from peg; one tick equals `1/priceScale`.'), z.meta({ examples: [0] })),
+            transactionHash: Schema.Hash.check(z.describe('Transaction hash for the transaction that placed the order.')),
+        })
+            .check(z.describe('One resting maker order on Tempo’s built-in stablecoin exchange.'));
+        /** A resting maker order annotated with the trading pair it belongs to. */
+        getOrders.Order = z
+            .extend(getOrders.RestingOrder, {
+            pair: order.Pair,
+        })
+            .check(z.describe('A resting maker order plus its trading pair.'));
+        /** Page of resting maker orders, each annotated with its trading pair. */
+        getOrders.Response = z
+            .object({
+            data: z.array(getOrders.Order).check(z.describe('Resting orders returned on this page.')),
+            meta: z
+                .optional(Schema.CountMeta)
+                .check(z.describe('Response-level resources requested with `include`, such as `totalCount`.')),
+            nextCursor: Schema.NextCursor,
+            truncated: z
+                .boolean()
+                .check(z.describe('`true` when the `OrderPlaced` scan hit its hard cap, meaning the resting set was computed from only the most recent placements.'), z.meta({ examples: [false] })),
+        })
+            .check(z.describe('A paginated list of resting maker orders on Tempo’s built-in stablecoin exchange.'));
+    })(getOrders = schema.getOrders || (schema.getOrders = {}));
+    /** Schemas for the getOrderFills operation. */
+    let getOrderFills;
+    (function (getOrderFills) {
+        /** Path parameters: inherits the canonical `/orders/:orderId` shape. */
+        getOrderFills.Params = order.Params;
+        /** Query parameters for paginated order-fill requests. */
+        getOrderFills.Query = z
+            .strictObject({
+            chainId: Schema.ChainIdQuery,
+            cursor: Schema.Cursor,
+            include: Schema.totalCountInclude,
+            limit: Schema.Limit,
+            order: Schema.Order,
+            page: Schema.Page,
+        })
+            .check(...Schema.pageChecks(), z.describe('Pagination and sorting options for listing fills for one order.'));
+        /**
+         * A single fill against the order. The order's pair, maker, side, and
+         * rate are constant across all fills, so they live on the `Order`
+         * resource rather than being repeated per row.
+         */
+        getOrderFills.Fill = z
+            .object({
+            amountFilled: Schema.DecimalString.check(z.describe('Base-side amount filled by this event, returned as a decimal integer string in base-token smallest units.')),
+            blockNumber: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Block number where the fill was included.'), z.meta({ examples: [23456789] })),
+            filledAt: z.iso
+                .datetime()
+                .check(z.describe('Block timestamp when the fill landed onchain.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+            id: z.string().check(z.describe('Stable API id built from the lowercase transaction hash and log index.'), z.meta({
+                examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-0'],
+            })),
+            logIndex: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('Log index of this fill within its block.'), z.meta({ examples: [0] })),
+            orderId: Schema.DecimalString.check(z.describe('On-chain order id, returned as a decimal string.')),
+            partialFill: z
+                .boolean()
+                .check(z.describe('Whether this fill used only part of the maker order.'), z.meta({ examples: [false] })),
+            taker: Schema.Address.check(z.describe('Taker address that submitted the incoming order.')),
+            transactionHash: Schema.Hash.check(z.describe('Transaction hash for the transaction containing the fill.')),
+        })
+            .check(z.describe('One `OrderFilled` event against this order.'));
+        /** Paginated page of fills for one order. */
+        getOrderFills.Response = z
+            .object({
+            data: z.array(getOrderFills.Fill).check(z.describe('Fills returned on this page.')),
+            meta: z
+                .optional(Schema.CountMeta)
+                .check(z.describe('Response-level resources requested with `include`.')),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A paginated list of fill events for one DEX order.'));
+    })(getOrderFills = schema.getOrderFills || (schema.getOrderFills = {}));
+    /** Schemas for the getPairDepth operation (orderbook depth aggregation). */
+    let getPairDepth;
+    (function (getPairDepth) {
+        /**
+         * Path parameter mirrors `getPair.Params`: the base address alone
+         * identifies the pair (its quote is intrinsic to the base token on-chain).
+         */
+        getPairDepth.Params = z
+            .object({
+            base: Schema.tokenAddress(exampleBase).check(z.describe('Base token address for the trading pair.')),
+        })
+            .check(z.describe('Path parameters for fetching orderbook depth for a pair.'));
+        /**
+         * Optional related resource that callers opt into via `include`. Currently
+         * only `tokens` (embeds metadata onto `base`/`quote` instead of returning
+         * just the addresses).
+         */
+        getPairDepth.Include = z
+            .enum(['tokens'])
+            .check(z.describe('Related resource you can opt into with `include`.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed.
+         */
+        getPairDepth.includeQuery = Schema.includeQuery(getPairDepth.Include, 'Comma-separated optional resources to embed, e.g. `tokens`.');
+        /** Query parameters for pair depth requests. */
+        getPairDepth.Query = z
+            .strictObject({
+            chainId: Schema.ChainIdQuery,
+            include: getPairDepth.includeQuery,
+            levels: z
+                ._default(z.coerce.number().check(z.int(), z.gte(1), z.lte(maxDepthLevels)), defaultDepthLevels)
+                .check(z.describe(`Maximum number of non-empty price levels to return per side (1-${maxDepthLevels}).`), z.meta({ examples: [50] })),
+        })
+            .check(z.describe('Query options for fetching orderbook depth for a pair.'));
+        /**
+         * A single price-level entry in the orderbook depth. `size` is the raw
+         * `totalLiquidity` reported by the DEX precompile for the level (resting
+         * base-token amount); `cumulativeSize` is the running sum across the same
+         * side, starting from the best (peg-adjacent) populated tick and walking
+         * outward.
+         */
+        getPairDepth.Level = z
+            .object({
+            cumulativeSize: Schema.DecimalString.check(z.describe('Running sum of `size` from the best populated tick outward to this level, in base-token smallest units.')),
+            id: z.string().check(z.describe('Stable API id built from the pair key, orderbook side, and tick.'), z.meta({
+                examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-bid-0'],
+            })),
+            price: z
+                .string()
+                .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Tick converted to a price ratio with 5 decimal places.'), z.meta({ examples: ['1.00000'] })),
+            size: Schema.DecimalString.check(z.describe('Resting liquidity at this tick level, in base-token smallest units.')),
+            tick: z
+                .number()
+                .check(z.int(), z.describe('Signed price tick (`int16`), always a multiple of the DEX tick spacing.'), z.meta({ examples: [0] })),
+        })
+            .check(z.describe('One price level in the orderbook depth response.'));
+        /** Orderbook depth (cumulative size per tick) for a single trading pair. */
+        getPairDepth.Response = z
+            .object({
+            asks: z
+                .array(getPairDepth.Level)
+                .check(z.describe('Ask-side levels, where makers sell base and takers buy it, ordered from best lowest ask outward.')),
+            base: schema.PairToken.check(z.describe('Base side of the trading pair.')),
+            bids: z
+                .array(getPairDepth.Level)
+                .check(z.describe('Bid-side levels, where makers buy base and takers sell it, ordered from best highest bid outward.')),
+            quote: schema.PairToken.check(z.describe('Quote side of the trading pair.')),
+        })
+            .check(z.describe('Orderbook depth for one trading pair, with cumulative size at each tick.'));
+    })(getPairDepth = schema.getPairDepth || (schema.getPairDepth = {}));
+})(schema || (schema = {}));
+/**
+ * Creates exchange handlers. The first endpoint is `GET /pairs`, which lists
+ * trading pairs on the stablecoin DEX precompile by replaying its `PairCreated`
+ * events through the indexer.
+ *
+ * Two sort orders are supported:
+ * - `sort=created` (default): order by pair creation `(block_num, log_idx)`.
+ * - `sort=liquidity`: rank by the DEX precompile's escrow balance of the pair's
+ *   base token, a per-pair liquidity proxy. Each base address participates in
+ *   exactly one pair (the on-chain DEX keys orderbooks by base, so the same
+ *   base never appears in two pairs), which lets a single
+ *   `token_balances_snapshot` row attribute cleanly to one pair. Pairs whose
+ *   DEX-escrow balance is zero are excluded from the liquidity ranking.
+ */
+export function exchanges() {
+    return new Hono()
+        .get('/swaps', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('query', schema.getSwaps.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'List recent swaps on Tempo’s built-in stablecoin exchange. A swap trades one token for another and may contain multiple maker-order fills.',
+        operationId: 'getSwaps',
+        responses: OpenApi.responses({
+            errors: {
+                502: 'The indexer could not serve the exchange data right now.',
+            },
+            success: {
+                description: 'A page of swaps from Tempo’s built-in stablecoin exchange.',
+                schema: schema.getSwaps.Response,
+            },
+        }),
+        summary: 'List swaps',
+        tags: ['Exchange'],
+    }), Cache.response({
+        // Exchanges are a newest-first feed; refresh quickly. The `v2` cache
+        // segment isolates the swap-level row shape from previously cached
+        // per-fill pages (cursor pages cache as `immutable`).
+        cacheControl: Cache.policies.feed,
+        name: 'tempo-api:exchange:v2:swaps',
+        key: (c) => Cache.urlKey(c, schema.getSwaps.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid query parameters',
+            });
+        const options = c.req.valid('query');
+        const chainId = options.chainId ?? c.get('chainId');
+        // Cursor pages anchor below the head and are effectively immutable, so
+        // upgrade their cache policy; the head page keeps the route's `feed`
+        // default.
+        if (options.cursor !== undefined)
+            Cache.setPolicy(c, Cache.policies.immutable);
+        try {
+            // The pair index (base address → pair) resolves each fill's book
+            // orientation (the order events only carry the base-side `token`;
+            // the quote is intrinsic to it).
+            const pairIndex = await getPairIndex(c, { chainId });
+            const page = await getSwaps(c, {
+                chainId,
+                cursor: options.cursor,
+                fromBlock: options['blockNumber.from'],
+                fromTimestamp: options['timestamp.from'],
+                limit: options.limit,
+                maker: options.maker,
+                order: options.order,
+                pairIndex,
+                participant: options.participant,
+                taker: options.taker,
+                toBlock: options['blockNumber.to'],
+                toTimestamp: options['timestamp.to'],
+                transactionHash: options.transactionHash,
+            });
+            // Token metadata is opt-in. Collect every token address across the
+            // page (`route` spans each swap's source, intermediates, and
+            // destination — a superset of every fill side) and resolve each
+            // once, then spread it onto the swap-level sides and every fill
+            // side. Resolution is best-effort: a token whose metadata is
+            // unavailable keeps just `address`/`amount`.
+            let data = page.data;
+            if (options.include.includes('tokens') && data.length > 0) {
+                const tokensByAddress = await resolveTokensByAddress(c, {
+                    addresses: data.flatMap((swap) => swap.route),
+                    chainId,
+                });
+                const spread = (side) => {
+                    const token = tokensByAddress.get(side.address);
+                    return token ? { ...side, ...token } : side;
+                };
+                data = data.map((swap) => ({
+                    ...swap,
+                    destinationToken: spread(swap.destinationToken),
+                    fills: swap.fills.map((fill) => ({
+                        ...fill,
+                        destinationToken: spread(fill.destinationToken),
+                        sourceToken: spread(fill.sourceToken),
+                    })),
+                    sourceToken: spread(swap.sourceToken),
+                }));
+            }
+            return c.json(Response.validated(schema.getSwaps.Response, {
+                data,
+                nextCursor: page.nextCursor,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get('/pairs', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('query', schema.getPairs.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'List trading pairs available on Tempo’s built-in stablecoin exchange.',
+        operationId: 'getPairs',
+        responses: OpenApi.responses({
+            errors: { 502: 'The indexer could not serve the exchange data right now.' },
+            success: {
+                description: 'A page of exchange trading pairs.',
+                schema: schema.getPairs.Response,
+            },
+        }),
+        summary: 'List pairs',
+        tags: ['Exchange'],
+    }), Cache.response({
+        // Pair creation is rare and append-only; `metadata` matches token-listing
+        // volatility and amortizes the indexer round-trip well.
+        cacheControl: Cache.policies.metadata,
+        name: 'tempo-api:exchange:v1',
+        key: (c) => Cache.urlKey(c, schema.getPairs.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid query parameters',
+            });
+        const options = c.req.valid('query');
+        const chainId = options.chainId ?? c.get('chainId');
+        // Cursor pages are anchored below the head and effectively immutable, so
+        // cache them aggressively; the head page keeps the route's `metadata`
+        // default.
+        if (options.cursor !== undefined)
+            Cache.setPolicy(c, Cache.policies.immutable);
+        try {
+            // `totalCount` is opt-in: the pair total is independent of `sort`
+            // (both orderings page the same set), so count `dex_pairs` directly.
+            // Best-effort: a count failure omits `meta` rather than failing.
+            const countPromise = options.include.includes('totalCount')
+                ? countPairs(c, { chainId }).catch(() => undefined)
+                : undefined;
+            const page = await getPairs(c, {
+                chainId,
+                cursor: options.cursor,
+                limit: options.limit,
+                order: options.order,
+                page: options.page,
+                sort: options.sort,
+            });
+            // Token metadata is opt-in. When requested, resolve each unique pair
+            // token's metadata concurrently (sharing one verified-token fetch) and
+            // spread it into both the `base` and `quote` row fields. Resolution is
+            // best-effort: a token whose metadata is unavailable keeps the row's
+            // `base`/`quote` as just `address` rather than failing the whole page.
+            let data = page.data.map((pair) => ({
+                base: { address: pair.base },
+                blockNumber: pair.blockNumber,
+                id: pair.key,
+                key: pair.key,
+                ...(pair.liquidity !== undefined && { liquidity: pair.liquidity }),
+                quote: { address: pair.quote },
+                timestamp: pair.timestamp,
+                transactionHash: pair.transactionHash,
+            }));
+            if (options.include.includes('tokens') && data.length > 0) {
+                const tokensByAddress = await resolveTokensByAddress(c, {
+                    addresses: data.flatMap((pair) => [pair.base.address, pair.quote.address]),
+                    chainId,
+                });
+                data = data.map((pair) => {
+                    const base = tokensByAddress.get(pair.base.address);
+                    const quote = tokensByAddress.get(pair.quote.address);
+                    return {
+                        ...pair,
+                        base: base ? { ...pair.base, ...base } : pair.base,
+                        quote: quote ? { ...pair.quote, ...quote } : pair.quote,
+                    };
+                });
+            }
+            const meta = countPromise ? await countPromise : undefined;
+            return c.json(Response.validated(schema.getPairs.Response, {
+                data,
+                ...(meta ? { meta } : {}),
+                nextCursor: page.nextCursor,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get(
+    // Single trading pair detail. The base address alone identifies the
+    // pair (its quote is intrinsic to the base token on-chain).
+    '/pairs/:base', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getPair.Params, {
+        code: 'pair_invalid',
+        message: 'Invalid base token',
+    }), OpenApi.validate('query', schema.getPair.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Get one trading pair by its base token address. On Tempo, the quote token for a pair is determined from the base token onchain.',
+        operationId: 'getPair',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No exchange pair was found for that base token.',
+                    codes: ['pair_not_found'],
+                },
+                502: 'The indexer could not serve the exchange data right now.',
+            },
+            success: {
+                description: 'Details for one exchange trading pair.',
+                schema: schema.getPair.Response,
+            },
+        }),
+        summary: 'Get pair',
+        tags: ['Exchange'],
+    }), Cache.response({
+        // Pair creation context is immutable once created; `metadata` matches
+        // the pairs listing.
+        cacheControl: Cache.policies.metadata,
+        name: 'tempo-api:exchange:v1:pair',
+        key: (c) => Cache.urlKey(c, schema.getPair.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'pair_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { base } = c.req.valid('param');
+        const options = c.req.valid('query');
+        const chainId = options.chainId ?? c.get('chainId');
+        try {
+            const pairs = await getPairIndex(c, { chainId });
+            const target = pairs.get(base);
+            if (!target)
+                return pairNotFoundError(c, { base, pairIndex: pairs });
+            // Token metadata is opt-in: resolve both pair tokens once and spread
+            // onto the `base`/`quote` PairToken slots.
+            let baseToken = { address: target.base };
+            let quoteToken = { address: target.quote };
+            if (options.include.includes('tokens')) {
+                const tokensByAddress = await resolveTokensByAddress(c, {
+                    addresses: [target.base, target.quote],
+                    chainId,
+                });
+                const baseMeta = tokensByAddress.get(target.base);
+                const quoteMeta = tokensByAddress.get(target.quote);
+                if (baseMeta)
+                    baseToken = { ...baseToken, ...baseMeta };
+                if (quoteMeta)
+                    quoteToken = { ...quoteToken, ...quoteMeta };
+            }
+            return c.json(Response.validated(schema.getPair.Response, {
+                base: baseToken,
+                blockNumber: target.blockNumber,
+                id: target.key,
+                key: target.key,
+                quote: quoteToken,
+                timestamp: target.timestamp,
+                transactionHash: target.transactionHash,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get(
+    // Resting-order feed, optionally scoped to one pair via `base`.
+    '/orders', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('query', schema.getOrders.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'List resting maker orders on Tempo’s built-in stablecoin exchange. These are open orders waiting in the orderbook.',
+        operationId: 'getOrders',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No exchange pair was found for the requested `base` filter.',
+                    codes: ['pair_not_found'],
+                },
+                502: 'The indexer could not serve the exchange data right now.',
+            },
+            success: {
+                description: 'A page of resting maker orders.',
+                schema: schema.getOrders.Response,
+            },
+        }),
+        summary: 'List orders',
+        tags: ['Exchange'],
+    }), Cache.response({
+        // Order book changes second-to-second; refresh quickly. The handler
+        // memoizes the underlying OrderPlaced scan internally for ~15s.
+        cacheControl: Cache.policies.state,
+        name: 'tempo-api:exchange:v1:all-orders',
+        key: (c) => Cache.urlKey(c, schema.getOrders.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid query parameters',
+            });
+        const options = c.req.valid('query');
+        const chainId = options.chainId ?? c.get('chainId');
+        try {
+            // The pair index (base address → pair) resolves the `base` selector
+            // and each order's pair; the OrderPlaced scan only carries the
+            // base-side `token`.
+            const pairIndex = await getPairIndex(c, { chainId });
+            // `base` selects the single pair it identifies — a pair's quote is
+            // intrinsic to its base token on-chain, so the base address alone
+            // is a complete selector.
+            let pair;
+            if (options.base !== undefined) {
+                const target = pairIndex.get(options.base);
+                if (!target)
+                    return pairNotFoundError(c, { base: options.base, pairIndex });
+                pair = target;
+            }
+            const page = await getOrders(c, {
+                chainId,
+                cursor: options.cursor,
+                limit: options.limit,
+                maker: options.maker,
+                order: options.order,
+                page: options.page,
+                pair,
+                pairIndex,
+                side: options.side,
+                sort: options.sort,
+            });
+            // Token metadata is opt-in. Collect every pair-token address across
+            // the page, resolve each once, then spread it onto whichever pair
+            // side carries that address. Best-effort: a token whose metadata is
+            // unavailable keeps just `address`.
+            let data = page.data;
+            if (options.include.includes('tokens') && data.length > 0) {
+                const tokensByAddress = await resolveTokensByAddress(c, {
+                    addresses: data.flatMap((o) => [o.pair.base.address, o.pair.quote.address]),
+                    chainId,
+                });
+                data = data.map((o) => {
+                    const base = tokensByAddress.get(o.pair.base.address);
+                    const quote = tokensByAddress.get(o.pair.quote.address);
+                    return {
+                        ...o,
+                        pair: {
+                            ...o.pair,
+                            base: base ? { ...o.pair.base, ...base } : o.pair.base,
+                            quote: quote ? { ...o.pair.quote, ...quote } : o.pair.quote,
+                        },
+                    };
+                });
+            }
+            // `totalCount` is opt-in and computed in-memory from the resting-order
+            // snapshot (no extra query): the matching-order total, capped when the
+            // placement scan was truncated (a lower bound).
+            const meta = options.include.includes('totalCount')
+                ? {
+                    // `totalCountCapped` when the placement scan was truncated OR the matching
+                    // set itself reaches the cap — either way the total is a lower bound.
+                    totalCountCapped: page.truncated || page.total >= Schema.countCap,
+                    totalCount: Math.min(page.total, Schema.countCap),
+                }
+                : undefined;
+            return c.json(Response.validated(schema.getOrders.Response, {
+                data,
+                ...(meta ? { meta } : {}),
+                nextCursor: page.nextCursor,
+                truncated: page.truncated,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get(
+    // Single-order detail. The path-param schema rejects non-decimal
+    // `orderId` values, surfacing the canonical `order_invalid` error.
+    '/orders/:orderId', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getOrder.Params, {
+        code: 'order_invalid',
+        message: 'Invalid order id',
+    }), OpenApi.validate('query', schema.getOrder.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Get one order by id, using live onchain state for fields such as the remaining amount.',
+        operationId: 'getOrder',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No exchange order was found for that id.',
+                    codes: ['order_not_found'],
+                },
+                502: 'The Tempo RPC node could not serve the exchange data right now.',
+            },
+            success: {
+                description: 'Details for one exchange order.',
+                schema: schema.getOrder.Response,
+            },
+        }),
+        summary: 'Get order',
+        tags: ['Exchange'],
+    }), Cache.response({
+        // `dex.getOrder` returns live state (`remaining` decreases as fills
+        // land), so cache as `state`. The handler upgrades to `immutable` when
+        // `remaining === '0'`, since a fully-filled order is terminal — every
+        // field this resource exposes is then immutable.
+        cacheControl: Cache.policies.state,
+        name: 'tempo-api:exchange:v1:order',
+        key: (c) => Cache.urlKey(c, schema.getOrder.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'order_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { orderId } = c.req.valid('param');
+        const query = c.req.valid('query');
+        const chainId = query.chainId ?? c.get('chainId');
+        try {
+            const order = await getOrder(c, { chainId, orderId });
+            if (!order)
+                return Response.error(c, {
+                    code: 'order_not_found',
+                    message: 'Order not found',
+                    status: 404,
+                });
+            // Fully-filled orders are terminal — `remaining`/`amount`/everything
+            // else is fixed forever, so they can be cached aggressively.
+            if (order.remaining === '0')
+                Cache.setPolicy(c, Cache.policies.immutable);
+            // Pair-token metadata is opt-in. The pair only has two tokens so we
+            // resolve both concurrently behind a single verified-tokens fetch and
+            // one batched `IN (...)` `tokens_created_at` query, matching the
+            // pair-swap include path. Resolution is best-effort: a token whose
+            // metadata is unavailable keeps just `address`.
+            let pair = order.pair;
+            if (query.include.includes('tokens')) {
+                const uniqueTokens = [pair.base.address, pair.quote.address];
+                const snapshot = await VerifiedTokens.snapshot(c, chainId);
+                const resolved = await Timing.time(c, 'tokens', () => Promise.all(uniqueTokens.map((token) => Tokens.resolveToken(c, {
+                    address: token,
+                    chainId,
+                    snapshot,
+                })
+                    .then((metadata) => [token, metadata])
+                    .catch(() => [token, undefined]))));
+                const tokensByAddress = new Map(resolved);
+                const base = tokensByAddress.get(pair.base.address);
+                const quote = tokensByAddress.get(pair.quote.address);
+                pair = {
+                    ...pair,
+                    base: base ? { ...pair.base, ...base } : pair.base,
+                    quote: quote ? { ...pair.quote, ...quote } : pair.quote,
+                };
+            }
+            return c.json(Response.validated(schema.getOrder.Response, { ...order, pair }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get(
+    // Paginated fill history for a single order.
+    '/orders/:orderId/fills', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getOrderFills.Params, {
+        code: 'order_invalid',
+        message: 'Invalid order id',
+    }), OpenApi.validate('query', schema.getOrderFills.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'List fills for one order. A fill records an execution against the maker order.',
+        operationId: 'getOrderFills',
+        responses: OpenApi.responses({
+            errors: { 502: 'The indexer could not serve the exchange data right now.' },
+            success: {
+                description: 'A page of fills for one order.',
+                schema: schema.getOrderFills.Response,
+            },
+        }),
+        summary: 'List order fills',
+        tags: ['Exchange'],
+    }), Cache.response({
+        // Newest-first fill feed — refresh quickly so newly-landed fills appear
+        // on the head page. Cursor pages anchor below the head and are
+        // effectively immutable; upgraded below.
+        cacheControl: Cache.policies.feed,
+        name: 'tempo-api:exchange:v1:order:fills',
+        key: (c) => Cache.urlKey(c, schema.getOrderFills.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'order_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { orderId } = c.req.valid('param');
+        const options = c.req.valid('query');
+        const chainId = options.chainId ?? c.get('chainId');
+        // Cursor pages anchor below the head on a stable `(block_num, log_idx)`
+        // tuple, so they are effectively immutable across requests; only the
+        // head page tracks the live tail.
+        if (options.cursor !== undefined)
+            Cache.setPolicy(c, Cache.policies.immutable);
+        try {
+            // `totalCount` (the order's fill total) is opt-in and shares the
+            // page's `orderId` filter; run it concurrently with the page.
+            // Best-effort: a count failure omits `meta` rather than failing the page.
+            const countPromise = options.include.includes('totalCount')
+                ? countOrderFills(c, { chainId, orderId }).catch(() => undefined)
+                : undefined;
+            const page = await getOrderFills(c, {
+                chainId,
+                cursor: options.cursor,
+                limit: options.limit,
+                order: options.order,
+                page: options.page,
+                orderId,
+            });
+            const meta = countPromise ? await countPromise : undefined;
+            return c.json(Response.validated(schema.getOrderFills.Response, {
+                data: page.data,
+                ...(meta ? { meta } : {}),
+                nextCursor: page.nextCursor,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get(
+    // OHLC (candlestick) aggregations for a single pair, addressed by its
+    // base token.
+    '/pairs/:base/ohlc', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getPairOhlc.Params, {
+        code: 'pair_invalid',
+        message: 'Invalid pair tokens',
+    }), OpenApi.validate('query', schema.getPairOhlc.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Get OHLC price candles for one trading pair. OHLC means open, high, low, and close over each time bucket for charting.',
+        operationId: 'getPairOhlc',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No exchange pair was found for that base token.',
+                    codes: ['pair_not_found'],
+                },
+                502: 'The indexer could not serve the exchange data right now.',
+            },
+            success: {
+                description: 'OHLC candle data for the pair.',
+                schema: schema.getPairOhlc.Response,
+            },
+        }),
+        summary: 'Get pair OHLC',
+        tags: ['Exchange'],
+    }), Cache.response({
+        // Short-interval candles change second-to-second so the latest bucket
+        // is volatile; the per-route handler upgrades the policy for longer
+        // intervals where staleness is cheaper.
+        cacheControl: Cache.policies.feed,
+        name: 'tempo-api:exchange:v1:ohlc',
+        key: (c) => Cache.urlKey(c, schema.getPairOhlc.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'pair_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { base: baseAddress } = c.req.valid('param');
+        const options = c.req.valid('query');
+        const chainId = options.chainId ?? c.get('chainId');
+        // Hour+ candles change slowly; upgrade them to the `state` tier so we
+        // amortize the per-fill scan more aggressively. The 1m/5m/15m tiers
+        // keep the route's `feed` default.
+        if (options.interval === '1h' || options.interval === '4h' || options.interval === '1d')
+            Cache.setPolicy(c, Cache.policies.state);
+        try {
+            const pairs = await getPairIndex(c, { chainId });
+            const target = pairs.get(baseAddress);
+            if (!target)
+                return pairNotFoundError(c, { base: baseAddress, pairIndex: pairs });
+            const result = await getPairOhlc(c, {
+                chainId,
+                interval: options.interval,
+                pair: target,
+                window: options.window,
+            });
+            // Token metadata is opt-in. Resolve once per pair and spread onto the
+            // top-level `base`/`quote` PairToken slots (the inner bucket rows
+            // carry no token references, so no per-row enrichment is needed).
+            let base = { address: target.base };
+            let quote = { address: target.quote };
+            if (options.include.includes('tokens')) {
+                const tokensByAddress = await resolveTokensByAddress(c, {
+                    addresses: [target.base, target.quote],
+                    chainId,
+                });
+                const baseMeta = tokensByAddress.get(target.base);
+                const quoteMeta = tokensByAddress.get(target.quote);
+                if (baseMeta)
+                    base = { ...base, ...baseMeta };
+                if (quoteMeta)
+                    quote = { ...quote, ...quoteMeta };
+            }
+            return c.json(Response.validated(schema.getPairOhlc.Response, {
+                base,
+                data: result.data,
+                interval: options.interval,
+                quote,
+                truncated: result.truncated,
+                window: options.window,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get(
+    // Orderbook depth (cumulative size per tick) for a single pair,
+    // addressed by its base token.
+    '/pairs/:base/depth', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getPairDepth.Params, {
+        code: 'pair_invalid',
+        message: 'Invalid pair tokens',
+    }), OpenApi.validate('query', schema.getPairDepth.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Get orderbook depth for one trading pair. Depth shows resting liquidity at price ticks on both sides of the book.',
+        operationId: 'getPairDepth',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No exchange pair was found for that base token.',
+                    codes: ['pair_not_found'],
+                },
+                502: 'The Tempo RPC node could not serve the exchange data right now.',
+            },
+            success: {
+                description: 'Orderbook depth data for the pair.',
+                schema: schema.getPairDepth.Response,
+            },
+        }),
+        summary: 'Get pair depth',
+        tags: ['Exchange'],
+    }), Cache.response({
+        // Depth shifts on every order placement, fill, or cancellation; `feed`
+        // matches the order-of-magnitude staleness traders tolerate on a
+        // depth chart while still amortizing concurrent dashboard loads.
+        cacheControl: Cache.policies.feed,
+        name: 'tempo-api:exchange:v1:depth',
+        key: (c) => Cache.urlKey(c, schema.getPairDepth.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'pair_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { base: baseAddress } = c.req.valid('param');
+        const options = c.req.valid('query');
+        const chainId = options.chainId ?? c.get('chainId');
+        try {
+            const pairs = await getPairIndex(c, { chainId });
+            const target = pairs.get(baseAddress);
+            if (!target)
+                return pairNotFoundError(c, { base: baseAddress, pairIndex: pairs });
+            const { asks, bids } = await getPairDepth(c, {
+                chainId,
+                levels: options.levels,
+                pair: target,
+            });
+            // Token metadata is opt-in. Resolve once per pair and spread onto the
+            // top-level `base`/`quote` PairToken slots. The Level rows carry no
+            // token references so no per-row enrichment is needed.
+            let base = { address: target.base };
+            let quote = { address: target.quote };
+            if (options.include.includes('tokens')) {
+                const tokensByAddress = await resolveTokensByAddress(c, {
+                    addresses: [target.base, target.quote],
+                    chainId,
+                });
+                const baseMeta = tokensByAddress.get(target.base);
+                const quoteMeta = tokensByAddress.get(target.quote);
+                if (baseMeta)
+                    base = { ...base, ...baseMeta };
+                if (quoteMeta)
+                    quote = { ...quote, ...quoteMeta };
+            }
+            return c.json(Response.validated(schema.getPairDepth.Response, { asks, base, bids, quote }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    });
+}
+// Hard cap on the curated pair index. Pair creation is rare (one event per
+// pair lifetime), so a few thousand bounds today's set comfortably; raise this
+// if the index ever exhausts.
+const pairIndexLimit = 5000;
+/**
+ * Builds the 404 for a failed pair lookup. The most common mistake is passing
+ * the *quote* side of the pair (usually pathUSD) as `base` — every pair quotes
+ * in pathUSD directly or transitively, so its address is never a base. Detect
+ * that case and point the caller at the right selector instead of returning a
+ * bare "not found".
+ */
+function pairNotFoundError(c, options) {
+    const { base, pairIndex } = options;
+    const message = [...pairIndex.values()].some((pair) => pair.quote === base)
+        ? 'Pair not found: the address is a quote token; address the pair by its base token (see `GET /exchange/pairs`)'
+        : 'Pair not found';
+    return Response.error(c, { code: 'pair_not_found', message, status: 404 });
+}
+/**
+ * Batch-resolves token metadata for a set of addresses, sharing one
+ * verified-token snapshot and one created-at lookup across the whole set.
+ * Best-effort: addresses whose metadata cannot be resolved are absent from
+ * the returned map, so callers keep their bare `{ address }` shapes. Shared
+ * by every `include=tokens` embed in this module.
+ */
+async function resolveTokensByAddress(c, options) {
+    const { addresses, chainId } = options;
+    const tokensByAddress = new Map();
+    const uniqueTokens = [...new Set(addresses)];
+    if (uniqueTokens.length === 0)
+        return tokensByAddress;
+    const snapshot = await VerifiedTokens.snapshot(c, chainId);
+    const resolved = await Timing.time(c, 'tokens', () => Promise.all(uniqueTokens.map((token) => Tokens.resolveToken(c, { address: token, chainId, snapshot })
+        .then((metadata) => [token, metadata])
+        .catch(() => [token, undefined]))));
+    for (const [token, metadata] of resolved)
+        if (metadata)
+            tokensByAddress.set(token, metadata);
+    return tokensByAddress;
+}
+async function getPairs(c, options) {
+    if (options.sort === 'liquidity')
+        return getPairsByLiquidity(c, options);
+    return getPairsByCreation(c, options);
+}
+/**
+ * Exact total count of trading pairs on the stablecoin DEX. Reads the
+ * `dex_pairs` materialized table (one row per `PairCreated`) on ClickHouse,
+ * pruning on the DEX `address` — the same engine/key the page uses. Because the
+ * `address` predicate aligns with the table's sort key, ClickHouse counts via
+ * the sparse primary index (no row scan), so the count is exact and cheap with
+ * no cap (`totalCountCapped` is always `false`). The total is independent of the
+ * page's `sort` (both orderings page the same pair set).
+ */
+function countPairs(c, options) {
+    const { chainId } = options;
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(chainId);
+    return Timing.time(c, 'pairs_count', () => Store.memoize(async () => {
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `SELECT count(*) AS total FROM dex_pairs WHERE address = '${stablecoinDex}'`,
+        });
+        const totalCount = Value.toNumber(result.rows[0]?.['total']) ?? 0;
+        return { totalCountCapped: false, totalCount };
+    }, { key: `exchange:v1:${chainId}:pairs-count`, store, ttl: Ttl.seconds(60) }));
+}
+async function getPairsByCreation(c, options) {
+    const { chainId, limit, order } = options;
+    const direction = order === 'asc' ? 'ASC' : 'DESC';
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(chainId);
+    // Keyset pagination on `(block_num, log_idx)`: a pair is created exactly
+    // once, so this tuple is a stable, unique sort key. A malformed cursor falls
+    // back to the head page.
+    const cursor = options.cursor ? Cursor.decode(options.cursor, ['int', 'int']) : undefined;
+    // Bounded positional lane (exclusive with `cursor` at the schema): page 1 is
+    // the head page, so it shares the head's SQL and cache entries; deeper pages
+    // translate to a SQL OFFSET of `(page - 1) * limit` rows.
+    const offset = options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : undefined;
+    return Timing.time(c, 'pairs', () => Store.memoize(async () => {
+        // Pre-decoded pair rows from the stablecoin DEX precompile. Read the
+        // `dex_pairs` materialized table (one row per `PairCreated`, sorted on
+        // `(block_num, log_idx)`) instead of decoding the `PairCreated` event
+        // signature over `logs` per request, so this is a sort-key read that
+        // matches the keyset directly. Filtering by `address` keeps unrelated
+        // `PairCreated`-named events (if any) out of the page. Fetch one extra
+        // row to detect `hasMore` without a separate count query. The inline
+        // query is cast to `string` so TIDX treats it as a dynamic ClickHouse
+        // query that needs no event signature for the `dex_pairs` table.
+        const filters = [`address = '${stablecoinDex}'`];
+        if (cursor !== undefined)
+            filters.push(Cursor.keyset([
+                { literal: Cursor.literal(cursor[0], 'int'), name: 'block_num', order },
+                { literal: Cursor.literal(cursor[1], 'int'), name: 'log_idx', order },
+            ]));
+        const where = `WHERE ${filters.join(' AND ')}`;
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `
+            SELECT key, base, quote, tx_hash, block_num, log_idx, block_timestamp
+            FROM dex_pairs
+            ${where}
+            ORDER BY block_num ${direction}, log_idx ${direction}
+            LIMIT ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
+          `,
+        });
+        // The next page anchors below the last fetched row's `(block, log_idx)`.
+        const page = Cursor.paginate({
+            rows: result.rows,
+            limit,
+            key: (row) => {
+                const block = Value.toNumber(row['block_num']);
+                const index = Value.toNumber(row['log_idx']);
+                return block !== undefined && index !== undefined ? [block, index] : undefined;
+            },
+        });
+        const data = [];
+        for (const row of page.rows) {
+            const parsed = parsePairRow(row);
+            if (parsed)
+                data.push(parsed);
+        }
+        return { data, nextCursor: page.nextCursor };
+    }, {
+        key: `exchange:v1:${chainId}:pairs:created:${order}:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : offset !== undefined ? `page:${options.page}` : 'head'}:${limit}`,
+        store,
+        ttl: Ttl.seconds(60),
+    }));
+}
+async function getPairsByLiquidity(c, options) {
+    const { chainId, limit, order } = options;
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(chainId);
+    // Keyset pagination on `(balance, token)`: balance ranks the page (mutable,
+    // so this is best-effort across balance changes — the inherent limit of
+    // ranking feeds), and `token` is a stable tiebreaker. A malformed cursor
+    // falls back to the head page.
+    const cursor = options.cursor ? Cursor.decode(options.cursor, ['uint', 'address']) : undefined;
+    // Bounded positional lane (exclusive with `cursor` at the schema): page 1 is
+    // the head page, so it shares the head's SQL and cache entries; deeper pages
+    // translate to a SQL OFFSET of `(page - 1) * limit` rows.
+    const offset = options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : undefined;
+    const balanceOrder = order === 'asc' ? 'ASC' : 'DESC';
+    return Timing.time(c, 'pairs', async () => Store.memoize(async () => {
+        // One ranked read from `dex_pair_liquidity`, which joins each pair's
+        // base to its DEX-escrow balance in ClickHouse — replacing the previous
+        // 3× over-fetch of escrow balances + in-memory intersection with the
+        // pair index. The cursor keyset keeps the previous `(balance, token)`
+        // value semantics under the view's `(liquidity, base)` column names, so
+        // pre-existing cursors stay valid. Cast the inline query to `string`
+        // (dynamic ClickHouse view, no event signature).
+        const keyset = cursor !== undefined
+            ? ` WHERE ${Cursor.keyset([
+                { literal: Cursor.literal(cursor[0], 'uint'), name: 'liquidity', order },
+                { literal: Cursor.literal(cursor[1], 'address'), name: 'base', order: 'asc' },
+            ])}`
+            : '';
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            // `liquidity` is UInt256; SELECT it as a string so values > 2^53
+            // survive JSON (the cursor encodes the exact value). Alias avoids
+            // shadowing the source column, which TIDX rejects (422).
+            query: `
+            SELECT key, base, quote, block_num, block_timestamp, tx_hash,
+                   toString(liquidity) AS liquidity_str
+            FROM dex_pair_liquidity${keyset}
+            ORDER BY liquidity ${balanceOrder}, base ASC
+            LIMIT ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
+          `,
+        });
+        const page = Cursor.paginate({
+            rows: result.rows,
+            limit,
+            key: (row) => {
+                const liquidity = Value.toIntegerString(row['liquidity_str']);
+                const base = Schema.Address.safeParse(row['base']);
+                return liquidity !== undefined && base.success ? [liquidity, base.data] : undefined;
+            },
+        });
+        const data = [];
+        for (const row of page.rows) {
+            const pair = parsePairRow(row);
+            const liquidity = Value.toIntegerString(row['liquidity_str']);
+            if (pair && liquidity !== undefined)
+                data.push({ ...pair, liquidity });
+        }
+        return { data, nextCursor: page.nextCursor };
+    }, {
+        key: `exchange:v1:${chainId}:pairs:liquidity:v2:${order}:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : offset !== undefined ? `page:${options.page}` : 'head'}:${limit}`,
+        store,
+        ttl: Ttl.seconds(30),
+    }));
+}
+/**
+ * Loads the curated pair index: a map from each pair's base address to its
+ * pair info (key, quote, creation context). The index is bounded by
+ * `pairIndexLimit` and memoized for several minutes since pair creation is
+ * rare and append-only. Reused across liquidity-ranking pages.
+ */
+async function getPairIndex(c, options) {
+    const { chainId } = options;
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(chainId);
+    return Timing.time(c, 'pair_index', () => Store.memoize(async () => {
+        // Read the pre-decoded `dex_pairs` materialized table instead of decoding
+        // the `PairCreated` event signature over `logs` per request. The inline
+        // query is cast to `string` so TIDX treats it as a dynamic ClickHouse
+        // query that needs no event signature for the `dex_pairs` table.
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `
+          SELECT key, base, quote, tx_hash, block_num, log_idx, block_timestamp
+          FROM dex_pairs
+          WHERE address = '${stablecoinDex}'
+          ORDER BY block_num DESC, log_idx DESC
+          LIMIT ${pairIndexLimit}
+        `,
+        });
+        // Serialize as `[base, pair]` entries so the cache layer round-trips
+        // them through JSON cleanly (a `Map` would not survive serialization-
+        // backed stores).
+        const entries = [];
+        for (const row of result.rows) {
+            const parsed = parsePairRow(row);
+            if (parsed)
+                entries.push([parsed.base, parsed]);
+        }
+        return entries;
+    }, {
+        key: `exchange:v1:${chainId}:pair-index:v1`,
+        store,
+        ttl: Ttl.minutes(5),
+    })).then((entries) => new Map(entries));
+}
+/**
+ * Validates and shapes one `PairCreated` row into the internal pair shape.
+ * Returns `undefined` for malformed rows so the caller can drop them without
+ * failing the whole page.
+ */
+function parsePairRow(row) {
+    const key = Schema.Hash.safeParse(row['key']);
+    const base = Schema.TokenAddress.safeParse(row['base']);
+    const quote = Schema.TokenAddress.safeParse(row['quote']);
+    const transactionHash = Schema.Hash.safeParse(row['tx_hash']);
+    const blockNumber = Value.toNumber(row['block_num']);
+    const timestamp = Value.toIsoDateTime(row['block_timestamp']);
+    if (!key.success ||
+        !base.success ||
+        !quote.success ||
+        !transactionHash.success ||
+        blockNumber === undefined ||
+        timestamp === undefined)
+        return undefined;
+    return {
+        base: base.data,
+        blockNumber,
+        key: key.data,
+        quote: quote.data,
+        timestamp,
+        transactionHash: transactionHash.data,
+    };
+}
+/**
+ * Resolves a page of logical taker swaps.
+ *
+ * A swap row aggregates the `OrderFilled` events of one
+ * `(block, transaction, taker)` group into one or more leg chains (§ multi-hop
+ * swaps route through intermediate books; batched transactions can carry
+ * several swaps). Each candidate batch is a grouped ClickHouse query over
+ * `dex_fills`; each fill's `(token, isBid, tick)` is then resolved
+ * point-in-time from the raw `OrderPlaced`/`OrderFlipped` event stream
+ * ({@link resolveOrderStates}), since the fill event itself carries none of
+ * it. The swap-level `mode` (transaction calldata, {@link resolveSwapCalls})
+ * is deferred to the final page so the candidate scan never pays it for rows
+ * that don't make the page.
+ *
+ * Every filter is pushed into the ClickHouse query — row predicates (`taker`,
+ * `transactionHash`, block/timestamp bounds) in `WHERE`, and the
+ * complete-fill-set filters (`maker`, `participant`) as HAVING aggregates — so
+ * `LIMIT` counts matching groups exactly and no row is dropped after
+ * pagination. A batched transaction can still expand one group into several
+ * swap rows, so the page is capped at row granularity: the cursor carries
+ * `(block, group first_idx, row first logIndex)`, the anchor group is
+ * re-fetched on the next page, and its already-returned rows are dropped
+ * row-wise — `data` never exceeds `limit`, and a group split across a page
+ * boundary resumes mid-group.
+ *
+ * Because a group expands into one *or more* rows (and the rare un-orientable
+ * group into zero), the scan accumulates rows across SQL batches (advancing
+ * an internal cursor by whole groups) until it has `limit + 1` (more remain)
+ * or the feed is exhausted; `nextCursor` then anchors at the last *included*
+ * row. This is a row-count top-up over the group→row fan-out, not a filter —
+ * no candidate is discarded after the query runs.
+ */
+async function getSwaps(c, options) {
+    const { chainId, cursor: cursorToken, fromBlock, fromTimestamp, limit, maker, order, pairIndex, participant, taker, toBlock, toTimestamp, transactionHash, } = options;
+    const tidx = c.get('getTidx')(chainId);
+    const direction = order === 'asc' ? 'ASC' : 'DESC';
+    // Keyset cursor on `(block_num, group first_idx, row first log_idx)`: the
+    // group key scopes the SQL re-fetch, the row key resumes inside a group
+    // that was split across a page boundary. A malformed cursor falls back to
+    // the head page.
+    const cursor = cursorToken ? Cursor.decode(cursorToken, ['int', 'int', 'int']) : undefined;
+    // Row-level predicates (constant within a group) prune before aggregation.
+    // These are batch-invariant; the cursor's per-batch block bound is added in
+    // `withCursorSql` below so the internal scan loop can advance it.
+    const baseFilters = [`f.address = '${stablecoinDex}'`];
+    if (taker !== undefined)
+        baseFilters.push(`f.taker = '${taker}'`);
+    // `tx_hash` is bloom-indexed on `dex_fills`, so this prunes granules.
+    if (transactionHash !== undefined)
+        baseFilters.push(`f.tx_hash = '${transactionHash}'`);
+    if (fromBlock !== undefined)
+        baseFilters.push(`f.block_num >= ${fromBlock}`);
+    if (toBlock !== undefined)
+        baseFilters.push(`f.block_num <= ${toBlock}`);
+    // Normalize to ClickHouse's `YYYY-MM-DD HH:MM:SS` form — the ISO-Z form
+    // rejects against `DateTime64(3, 'UTC')` with a conversion error.
+    if (fromTimestamp !== undefined)
+        baseFilters.push(`f.block_timestamp >= '${formatClickHouseDateTime(fromTimestamp)}'`);
+    if (toTimestamp !== undefined)
+        baseFilters.push(`f.block_timestamp <= '${formatClickHouseDateTime(toTimestamp)}'`);
+    // Group-level predicates: evaluated over each group's complete fill set, so
+    // "any fill matches" semantics stay exact under SQL pagination. Like
+    // `baseFilters`, these are batch-invariant; the cursor's group/row bound is
+    // added per batch in `withCursorSql`.
+    const baseGroupFilters = [];
+    if (maker !== undefined)
+        baseGroupFilters.push(`max(f.maker = '${maker}') = 1`);
+    if (participant !== undefined)
+        baseGroupFilters.push(`max(f.taker = '${participant}' OR f.maker = '${participant}') = 1`);
+    // Per-batch SQL: the internal scan loop advances `activeCursor` across SQL
+    // batches, so the cursor's bounds (row-level block bound in WHERE, group/row
+    // refinement in HAVING) are rebuilt for each batch rather than baked into the
+    // base predicates.
+    const withCursorSql = (activeCursor) => {
+        const where = [...baseFilters];
+        const group = [...baseGroupFilters];
+        if (activeCursor !== undefined) {
+            // The cursor's block bound is row-level; its `(block, first_idx)` tuple
+            // refinement needs the aggregate and lives in HAVING.
+            where.push(`f.block_num ${order === 'asc' ? '>=' : '<='} ${Cursor.literal(activeCursor[0], 'int')}`);
+            // Inclusive at the anchor group: a batch may end mid-group (a batched
+            // transaction expands one group into several rows), so the anchor group
+            // is re-fetched and its already-returned rows are dropped row-wise after
+            // assembly.
+            const op = order === 'asc' ? '>' : '<';
+            const anchorBlock = Cursor.literal(activeCursor[0], 'int');
+            const anchorGroup = Cursor.literal(activeCursor[1], 'int');
+            group.push(`((block_num ${op} ${anchorBlock}) OR (block_num = ${anchorBlock} AND first_idx ${op}= ${anchorGroup}))`);
+        }
+        return { having: group.length > 0 ? `HAVING ${group.join(' AND ')}` : '', where };
+    };
+    return Timing.time(c, 'swaps', async () => {
+        // One grouped query returns complete groups with their fills inline.
+        // `toString(...)` forces `uint128`/`uint256` tuple members through
+        // ClickHouse's JSON output as strings — raw numbers in tuples lose
+        // precision past 2^53. `block_timestamp` is per-block, so `min(...)` is
+        // the group timestamp.
+        const fetchGroups = (activeCursor, batchLimit, window) => {
+            const { having, where } = withCursorSql(activeCursor);
+            return tidx.fetch({
+                chainId,
+                engine: 'clickhouse',
+                query: `
+        SELECT f.block_num AS block_num, f.tx_hash AS tx_hash, f.taker AS taker,
+               min(f.log_idx) AS first_idx, min(f.block_timestamp) AS ts,
+               groupArray(tuple(f.log_idx, toString(f."orderId"), f.maker,
+                                toString(f."amountFilled"), f."partialFill")) AS fills
+        FROM dex_fills f
+        WHERE ${[...where, `f.block_num >= ${window.lo}`, `f.block_num <= ${window.hi}`].join(' AND ')}
+        GROUP BY f.block_num, f.tx_hash, f.taker
+        ${having}
+        ORDER BY block_num ${direction}, first_idx ${direction}
+        LIMIT ${batchLimit}
+      `,
+            });
+        };
+        // A row's keyset position is `(block, group first_idx, its first fill
+        // logIndex)`; rows at or before the active cursor's row anchor were already
+        // returned (the anchor group is re-fetched whole) and are dropped here.
+        // The drop is purely positional.
+        const past = (activeCursor, blockNumber, logIndex) => {
+            if (activeCursor === undefined)
+                return true;
+            // Decode validated both fields as `int`, so they are plain numbers.
+            const anchorBlock = Number(activeCursor[0]);
+            const anchorIndex = Number(activeCursor[2]);
+            if (blockNumber !== anchorBlock)
+                return order === 'asc' ? blockNumber > anchorBlock : blockNumber < anchorBlock;
+            return order === 'asc' ? logIndex > anchorIndex : logIndex < anchorIndex;
+        };
+        // Advance the internal cursor past a whole fetched group so the next batch
+        // re-fetches that group and `past()` drops all of its rows. The row anchor
+        // is direction-aware: `asc` drops rows `<=` the group's max fill logIndex,
+        // `desc` drops rows `>=` its min (`first_idx`). `group.fills` is sorted
+        // ascending by `parseGroupRow`.
+        const cursorAfterWholeGroup = (group) => [
+            group.blockNumber,
+            group.firstIndex,
+            order === 'asc' ? group.fills.at(-1).logIndex : group.firstIndex,
+        ];
+        // Resolve one fetched batch of groups into assembled, ordered candidate
+        // rows. Only the state + quote lookups are needed to assemble; `mode`
+        // (calldata) is deferred to the final page.
+        const resolveBatch = async (groups, activeCursor) => {
+            // Point-in-time order state (token/isBid/tick) for this batch's fills —
+            // required to orient fills and assemble each swap's route ends.
+            const blocks = [...new Set(groups.map((group) => group.blockNumber))];
+            const states = await Timing.time(c, 'swap_states', () => resolveOrderStates(c, {
+                chainId,
+                maxBlock: Math.max(...blocks),
+                minBlock: Math.min(...blocks),
+                orderIds: [
+                    ...new Set(groups.flatMap((group) => group.fills.map((fill) => fill.orderId))),
+                ],
+            }));
+            // Each fill's book quote: from the `dex_pairs` index when present, else
+            // the base token's on-chain `quoteToken()` — some books predate the
+            // indexer's `PairCreated` decode (genesis system books) and have no
+            // `dex_pairs` row.
+            const bases = [
+                ...new Set([...states.values()].flatMap((events) => events.map((event) => event.token))),
+            ];
+            const quoteByBase = new Map();
+            for (const bookBase of bases) {
+                const indexed = pairIndex.get(bookBase);
+                if (indexed)
+                    quoteByBase.set(bookBase, indexed.quote);
+            }
+            const fallback = await Timing.time(c, 'swap_quotes', () => resolveBookQuotes(c, {
+                bases: bases.filter((bookBase) => !quoteByBase.has(bookBase)),
+                chainId,
+            }));
+            for (const [bookBase, quote] of fallback)
+                quoteByBase.set(bookBase, quote);
+            // Assemble each group into swap rows — a batched transaction expands one
+            // group into several rows — then drop already-returned rows of the
+            // re-fetched anchor group (cursor resume); every surviving row is kept.
+            const candidates = [];
+            for (const group of groups)
+                for (const swap of buildSwapRows(group, { order, quoteByBase, states })) {
+                    if (!past(activeCursor, group.blockNumber, swap.fills[0].logIndex))
+                        continue;
+                    // The `maker`/`participant` HAVING filters are group-level
+                    // (`(block, tx, taker)`), but a batched transaction expands one group
+                    // into several swap rows — only the rows whose own fills involve the
+                    // address satisfy the per-swap contract, so refine to row granularity
+                    // here. The accumulation loop tops the page back up to `limit`.
+                    if (maker !== undefined && !swap.fills.some((fill) => fill.maker === maker))
+                        continue;
+                    if (participant !== undefined &&
+                        swap.taker !== participant &&
+                        !swap.fills.some((fill) => fill.maker === participant))
+                        continue;
+                    candidates.push({ group, swap });
+                }
+            candidates.sort((a, b) => {
+                const delta = a.group.blockNumber - b.group.blockNumber ||
+                    a.swap.fills[0].logIndex - b.swap.fills[0].logIndex;
+                return order === 'asc' ? delta : -delta;
+            });
+            return candidates;
+        };
+        // A selective row predicate (`taker`/`maker`/`participant`/`transactionHash`)
+        // makes matching fills sparse across a wide block range, so enumerate the
+        // exact blocks holding a matching fill up front: it is cheap (bloom-indexed,
+        // no `GROUP BY`/`groupArray`) and lets the window sweep jump straight to the
+        // next populated block instead of paying a full grouped round-trip for every
+        // empty `swapWindowBlocks` gap between clusters. The block list also yields
+        // the scan bounds, so no separate `min`/`max` query is needed.
+        //
+        // The discovery predicate must be a *superset* of the grouped page query's
+        // matches. The page query applies `maker`/`participant` as existential
+        // HAVING aggregates over each `(block, tx, taker)` group, so a single group
+        // can satisfy `maker` and `participant` via *different* fills. A row-level
+        // conjunction would wrongly require one fill to satisfy both; OR the
+        // group-level witnesses together instead — every block with a matching group
+        // has at least one witness fill, and a group's fills share its block.
+        const selective = taker !== undefined ||
+            maker !== undefined ||
+            participant !== undefined ||
+            transactionHash !== undefined;
+        const blockFilters = [...baseFilters];
+        {
+            const witnesses = [];
+            if (maker !== undefined)
+                witnesses.push(`f.maker = '${maker}'`);
+            if (participant !== undefined) {
+                witnesses.push(`f.taker = '${participant}'`);
+                witnesses.push(`f.maker = '${participant}'`);
+            }
+            if (witnesses.length > 0)
+                blockFilters.push(`(${witnesses.join(' OR ')})`);
+        }
+        // Distinct matching blocks, ascending (binary-searched in `windowFrom`).
+        // Only populated for selective queries; the unfiltered feed would match
+        // nearly every block, so it keeps the `min`/`max` bound + fixed-stride sweep.
+        let matchingBlocks;
+        const bounds = await Timing.time(c, 'swap_bounds', async () => {
+            if (selective) {
+                const result = await tidx.fetch({
+                    chainId,
+                    engine: 'clickhouse',
+                    query: `SELECT DISTINCT f.block_num AS block_num FROM dex_fills f WHERE ${blockFilters.join(' AND ')} ORDER BY block_num ASC`,
+                });
+                matchingBlocks = result.rows
+                    .map((row) => Value.toNumber(row['block_num']))
+                    .filter((block) => block !== undefined);
+                const lo = matchingBlocks[0];
+                const hi = matchingBlocks.at(-1);
+                return lo !== undefined && hi !== undefined ? { hi, lo } : undefined;
+            }
+            const result = await tidx.fetch({
+                chainId,
+                engine: 'clickhouse',
+                query: `SELECT min(f.block_num) AS lo, max(f.block_num) AS hi FROM dex_fills f WHERE ${blockFilters.join(' AND ')}`,
+            });
+            const row = result.rows[0];
+            const lo = row ? Value.toNumber(row['lo']) : undefined;
+            const hi = row ? Value.toNumber(row['hi']) : undefined;
+            return lo !== undefined && hi !== undefined ? { hi, lo } : undefined;
+        });
+        const accumulated = [];
+        if (bounds) {
+            const lowerBound = Math.max(fromBlock ?? bounds.lo, bounds.lo);
+            const upperBound = Math.min(toBlock ?? bounds.hi, bounds.hi);
+            // Window sweep: every grouped batch is bounded to one block window, since
+            // an unbounded `dex_fills` GROUP BY is rejected by TIDX (HTTP 422) once the
+            // table is large. `desc` walks windows downward from the cursor/head block;
+            // `asc` upward. Within a window the keyset cursor advances by whole groups
+            // (a full batch may leave more groups in the same window); a short batch
+            // exhausts the window and slides the sweep to the next disjoint range.
+            const batchLimit = limit + 1;
+            let activeCursor = cursor;
+            const cursorBlock = cursor !== undefined ? Number(cursor[0]) : undefined;
+            // Snap an anchor block onto the matching-block list (selective queries):
+            // the largest matching block `<= value` (desc) / smallest `>= value`
+            // (asc). This collapses the empty gaps between fill clusters — `slideWindow`
+            // jumps straight to the next populated block. `undefined` when no matching
+            // block remains in range. `matchingBlocks` is ascending.
+            const lastAtMost = (value) => {
+                if (matchingBlocks === undefined)
+                    return value;
+                let lo = 0;
+                let hi = matchingBlocks.length;
+                while (lo < hi) {
+                    const mid = (lo + hi) >> 1;
+                    if (matchingBlocks[mid] <= value)
+                        lo = mid + 1;
+                    else
+                        hi = mid;
+                }
+                return lo === 0 ? undefined : matchingBlocks[lo - 1];
+            };
+            const firstAtLeast = (value) => {
+                if (matchingBlocks === undefined)
+                    return value;
+                let lo = 0;
+                let hi = matchingBlocks.length;
+                while (lo < hi) {
+                    const mid = (lo + hi) >> 1;
+                    if (matchingBlocks[mid] < value)
+                        lo = mid + 1;
+                    else
+                        hi = mid;
+                }
+                return lo === matchingBlocks.length ? undefined : matchingBlocks[lo];
+            };
+            const windowFrom = (anchor) => {
+                if (order === 'desc') {
+                    const hi = lastAtMost(Math.min(upperBound, anchor ?? upperBound));
+                    return hi !== undefined && hi >= lowerBound
+                        ? { hi, lo: Math.max(lowerBound, hi - swapWindowBlocks + 1) }
+                        : undefined;
+                }
+                const lo = firstAtLeast(Math.max(lowerBound, anchor ?? lowerBound));
+                return lo !== undefined && lo <= upperBound
+                    ? { hi: Math.min(upperBound, lo + swapWindowBlocks - 1), lo }
+                    : undefined;
+            };
+            let window = windowFrom(cursorBlock);
+            // Slide to the next disjoint window away from the newest block and reset
+            // the cursor: every row in the next window is already past the cursor
+            // anchor in the requested order, so no anchor refinement is needed.
+            const slideWindow = () => {
+                activeCursor = undefined;
+                window =
+                    window === undefined
+                        ? undefined
+                        : windowFrom(order === 'desc' ? window.lo - 1 : window.hi + 1);
+            };
+            while (accumulated.length <= limit && window !== undefined) {
+                const result = await fetchGroups(activeCursor, batchLimit, window);
+                const fetchedFull = result.rows.length >= batchLimit;
+                const groups = [];
+                for (const row of result.rows) {
+                    const group = parseGroupRow(row);
+                    if (group)
+                        groups.push(group);
+                }
+                for (const candidate of await resolveBatch(groups, activeCursor)) {
+                    accumulated.push(candidate);
+                    if (accumulated.length > limit)
+                        break;
+                }
+                if (accumulated.length > limit)
+                    break;
+                // No parsable groups: a full batch cannot advance, so stop rather than
+                // risk skipping lower groups in the same window; a short batch just
+                // exhausts the window.
+                const tail = groups.at(-1);
+                if (tail === undefined) {
+                    if (fetchedFull)
+                        break;
+                    slideWindow();
+                    continue;
+                }
+                // A short batch exhausts this window; a full one may leave more groups
+                // in it, so advance the keyset cursor and re-query the same window.
+                if (!fetchedFull) {
+                    slideWindow();
+                    continue;
+                }
+                const next = cursorAfterWholeGroup(tail);
+                // Progress guard: if the cursor cannot advance, slide instead of looping.
+                if (activeCursor !== undefined &&
+                    Number(activeCursor[0]) === next[0] &&
+                    Number(activeCursor[1]) === next[1] &&
+                    Number(activeCursor[2]) === next[2]) {
+                    slideWindow();
+                    continue;
+                }
+                activeCursor = [next[0], next[1], next[2]];
+            }
+        }
+        // Cut to `limit`; the external cursor anchors at the last INCLUDED row so
+        // the next call resumes exactly after it (the anchor group is re-fetched
+        // and dropped row-wise). `> limit` means at least one more matching row
+        // exists, so the page continues; otherwise the feed is exhausted.
+        const pageRows = accumulated.slice(0, limit);
+        const last = pageRows.at(-1);
+        const nextCursor = accumulated.length > limit && last !== undefined
+            ? Cursor.encode([
+                last.group.blockNumber,
+                last.group.firstIndex,
+                last.swap.fills[0].logIndex,
+            ])
+            : null;
+        const data = pageRows.map((candidate) => candidate.swap);
+        // Recover each swap's `mode` from transaction calldata — deferred to here
+        // so the candidate scan never pays the `txs` lookup for rows beyond the
+        // page. Best-effort: a failed lookup leaves `mode: null`.
+        await resolveSwapModes(c, { chainId, swaps: data });
+        return { data, nextCursor };
+    });
+}
+/**
+ * Validates and shapes one grouped page row — the `(block, tx, taker)` key
+ * plus its `groupArray` fill tuples — into a typed group. Fills are deduped
+ * by `log_idx` (ReplacingMergeTree can surface unmerged duplicate rows) and
+ * sorted into execution order. Returns undefined for malformed rows so the
+ * caller can drop them without failing the page.
+ */
+function parseGroupRow(row) {
+    const blockNumber = Value.toNumber(row['block_num']);
+    const firstIndex = Value.toNumber(row['first_idx']);
+    const taker = Schema.Address.safeParse(row['taker']);
+    const timestamp = Value.toIsoDateTime(row['ts']);
+    const transactionHash = Schema.Hash.safeParse(row['tx_hash']);
+    const tuples = row['fills'];
+    if (blockNumber === undefined ||
+        firstIndex === undefined ||
+        !taker.success ||
+        timestamp === undefined ||
+        !transactionHash.success ||
+        !Array.isArray(tuples))
+        return undefined;
+    const fills = new Map();
+    for (const tuple of tuples) {
+        if (!Array.isArray(tuple))
+            continue;
+        const logIndex = Value.toNumber(tuple[0]);
+        const orderId = Value.toIntegerString(tuple[1]);
+        const maker = Schema.Address.safeParse(tuple[2]);
+        const amountFilled = Value.toIntegerString(tuple[3]);
+        if (logIndex === undefined ||
+            orderId === undefined ||
+            !maker.success ||
+            amountFilled === undefined)
+            continue;
+        fills.set(logIndex, {
+            amountFilled,
+            logIndex,
+            maker: maker.data,
+            orderId,
+            // ClickHouse surfaces booleans as `0`/`1`.
+            partialFill: tuple[4] === true || tuple[4] === 1,
+        });
+    }
+    if (fills.size === 0)
+        return undefined;
+    return {
+        blockNumber,
+        fills: [...fills.values()].sort((a, b) => a.logIndex - b.logIndex),
+        firstIndex,
+        taker: taker.data,
+        timestamp,
+        transactionHash: transactionHash.data,
+    };
+}
+/**
+ * Resolves the point-in-time order-state streams for a set of `orderId`s
+ * from the raw `OrderPlaced`/`OrderFlipped` logs.
+ *
+ * A T5+ flip order keeps its `orderId` while `(isBid, tick)` swap sides on
+ * every flip, so a fill's state is the latest event *before* the fill — not
+ * the original `OrderPlaced`. One query returns, per order, its pre-page
+ * history compressed to the latest event (`argMax`, sentinel position
+ * `(-1, -1)` so it sorts first) plus every raw in-page event, so an order
+ * that flips between two of its page fills resolves each fill correctly.
+ * `logs` is sorted by `(address, selector, block_num, log_idx)` with a
+ * `topic1` bloom index, so both halves are pruned range reads. Returned
+ * per-order event lists are position-sorted.
+ */
+export async function resolveOrderStates(c, options) {
+    const { chainId, maxBlock, minBlock, orderIds } = options;
+    const map = new Map();
+    if (orderIds.length === 0)
+        return map;
+    const tidx = c.get('getTidx')(chainId);
+    const topics = orderIds.map((id) => `'0x${BigInt(id).toString(16).padStart(64, '0')}'`);
+    const eventFilter = `address = '${stablecoinDex}'
+          AND selector IN ('${orderPlacedTopic}', '${orderFlippedTopic}')
+          AND topic1 IN (${topics.join(', ')})`;
+    // Aliases must not shadow the source columns (`t3`, not `topic3`) —
+    // ClickHouse rejects self-shadowing aliases in queries that also filter on
+    // the shadowed column.
+    const result = await tidx.fetch({
+        chainId,
+        engine: 'clickhouse',
+        query: `
+      SELECT topic1, argMax(topic3, (block_num, log_idx)) AS t3,
+             argMax(data, (block_num, log_idx)) AS payload,
+             toInt64(-1) AS bn, toInt32(-1) AS li
+      FROM logs
+      WHERE ${eventFilter} AND block_num < ${minBlock}
+      GROUP BY topic1
+      UNION ALL
+      SELECT topic1, topic3 AS t3, data AS payload, block_num AS bn, log_idx AS li
+      FROM logs
+      WHERE ${eventFilter} AND block_num >= ${minBlock} AND block_num <= ${maxBlock}
+    `,
+    });
+    for (const row of result.rows) {
+        const parsed = parseStateRow(row);
+        if (!parsed)
+            continue;
+        const events = map.get(parsed.orderId);
+        if (events)
+            events.push(parsed.state);
+        else
+            map.set(parsed.orderId, [parsed.state]);
+    }
+    for (const events of map.values())
+        events.sort((a, b) => a.blockNumber - b.blockNumber || a.logIndex - b.logIndex);
+    return map;
+}
+/**
+ * Decodes one order-state row (raw log topics/data) into a positioned
+ * `(token, isBid, tick)` state. `OrderPlaced` and `OrderFlipped` share the
+ * layout of the words read here: `data` word 1 is `isBid`, word 2 is `tick`
+ * (int16, sign-extended); the book base token is `topic3`.
+ */
+function parseStateRow(row) {
+    const topic1 = Value.toText(row['topic1']);
+    const topic3 = Value.toText(row['t3']);
+    const payload = Value.toText(row['payload']);
+    const blockNumber = Value.toNumber(row['bn']);
+    const logIndex = Value.toNumber(row['li']);
+    if (topic1 === undefined ||
+        !/^0x[0-9a-fA-F]{64}$/.test(topic1) ||
+        topic3 === undefined ||
+        !/^0x[0-9a-fA-F]{64}$/.test(topic3) ||
+        payload === undefined ||
+        payload.length < 2 + 64 * 3 ||
+        blockNumber === undefined ||
+        logIndex === undefined)
+        return undefined;
+    const isBid = BigInt(`0x${payload.slice(66, 130)}`) !== 0n;
+    // int16 sign-extended across the 32-byte word: values ≥ 2^255 are negative.
+    const tickWord = BigInt(`0x${payload.slice(130, 194)}`);
+    const tick = Number(tickWord >= 2n ** 255n ? tickWord - 2n ** 256n : tickWord);
+    return {
+        orderId: BigInt(topic1).toString(),
+        state: {
+            blockNumber,
+            isBid,
+            logIndex,
+            tick,
+            token: `0x${topic3.slice(26).toLowerCase()}`,
+        },
+    };
+}
+/**
+ * Recovers the decoded swap calls of a page's transactions from calldata,
+ * keyed by transaction hash — the source of the swap-level `mode`. Direct
+ * calls decode from `txs.input`; AA (type `0x76`) transactions use the
+ * indexer's pre-decoded `calls` JSON column (`[{to, value, input}]`), so no
+ * envelope parsing is needed.
+ *
+ * The `block_num IN (...)` bound is required: `txs` is sorted by
+ * `(block_num, idx)` with no hash index, so a bare `hash IN` lookup
+ * full-scans the table and times out upstream.
+ */
+async function resolveSwapCalls(c, options) {
+    const { blocks, chainId, hashes } = options;
+    const map = new Map();
+    if (hashes.length === 0)
+        return map;
+    const tidx = c.get('getTidx')(chainId);
+    const result = await tidx.fetch({
+        chainId,
+        engine: 'clickhouse',
+        query: `
+      SELECT hash, "type", "to", input, calls
+      FROM txs
+      WHERE block_num IN (${blocks.join(', ')})
+        AND hash IN (${hashes.map((hash) => `'${hash}'`).join(', ')})
+    `,
+    });
+    for (const row of result.rows) {
+        const hash = Value.toText(row['hash']);
+        if (hash === undefined)
+            continue;
+        const inner = (() => {
+            if (Value.toNumber(row['type']) !== 0x76)
+                return [{ input: row['input'], to: row['to'] }];
+            try {
+                const raw = row['calls'];
+                const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                return Array.isArray(parsed) ? parsed : [];
+            }
+            catch {
+                return [];
+            }
+        })();
+        const calls = [];
+        for (const call of inner) {
+            const to = Value.toText(call.to);
+            const data = Value.toText(call.input) ?? Value.toText(call.data);
+            if (to?.toLowerCase() !== stablecoinDex || data === undefined)
+                continue;
+            try {
+                const decoded = decodeFunctionData({ abi: swapAbi, data: data });
+                calls.push({
+                    mode: decoded.functionName === 'swapExactAmountIn' ? 'exactSource' : 'exactDestination',
+                    tokenIn: decoded.args[0].toLowerCase(),
+                    tokenOut: decoded.args[1].toLowerCase(),
+                });
+            }
+            catch {
+                // Not a swap call (place/cancel/withdraw/...); skip.
+            }
+        }
+        if (calls.length > 0)
+            map.set(hash, calls);
+    }
+    return map;
+}
+/**
+ * Attaches the swap-level `mode` (exact-source vs exact-destination) to each
+ * row in place, recovered from the decoded transaction calldata
+ * ({@link resolveSwapCalls}). A row's mode is pinned when one or more matching
+ * calls (`tokenIn = route start`, `tokenOut = route end`) all agree; otherwise
+ * it stays `null` (a resting order that crossed on placement, undecodable
+ * calldata, or a failed lookup). Mutates `swaps`; runs only on the final page,
+ * so the candidate scan never pays this `txs` lookup for filtered-out rows.
+ */
+async function resolveSwapModes(c, options) {
+    const { chainId, swaps } = options;
+    if (swaps.length === 0)
+        return;
+    const calls = await Timing.time(c, 'swap_calls', () => resolveSwapCalls(c, {
+        blocks: [...new Set(swaps.map((swap) => swap.blockNumber))],
+        chainId,
+        hashes: [...new Set(swaps.map((swap) => swap.transactionHash))],
+    })).catch(() => new Map());
+    for (const swap of swaps) {
+        const matched = (calls.get(swap.transactionHash) ?? []).filter((call) => call.tokenIn === swap.sourceToken.address &&
+            call.tokenOut === swap.destinationToken.address);
+        swap.mode =
+            matched.length > 0 && matched.every((call) => call.mode === matched[0].mode)
+                ? matched[0].mode
+                : null;
+    }
+}
+/**
+ * Resolves the quote token of order books missing from the `dex_pairs` index
+ * (books created without a `PairCreated` event, e.g. genesis system books)
+ * by reading the base token's on-chain `quoteToken()` — the quote is
+ * intrinsic and immutable for a TIP-20, so results memoize long. `undefined`
+ * from the RPC means the default quote (pathUSD). Best-effort: a base whose
+ * quote cannot be resolved is absent from the returned map, and its fills
+ * are dropped downstream.
+ */
+export async function resolveBookQuotes(c, options) {
+    const { bases, chainId } = options;
+    const getClient = c.get('getClient');
+    const store = c.get('store');
+    const map = new Map();
+    if (bases.length === 0)
+        return map;
+    await Promise.all(bases.map(async (base) => {
+        try {
+            const quote = await Store.memoize(async () => {
+                const metadata = await getClient(chainId).token.getMetadata({
+                    token: base,
+                });
+                return metadata.quoteToken?.toLowerCase() ?? Addresses.pathUsd;
+            }, { key: `exchange:v1:${chainId}:book-quote:${base}`, store, ttl: Ttl.minutes(60) });
+            const parsed = Schema.TokenAddress.safeParse(quote);
+            if (parsed.success)
+                map.set(base, parsed.data);
+        }
+        catch {
+            // Best-effort: unresolvable books drop their fills downstream.
+        }
+    }));
+    return map;
+}
+/**
+ * Assembles one group's fills into public swap rows.
+ *
+ * Each fill is oriented from the taker's perspective using its point-in-time
+ * order state (maker bid → the taker sold the book base; maker ask → bought
+ * it; the quote side is reconstructed from the tick: `1 base =
+ * (priceScale + tick) / priceScale quote`). Oriented fills bucket into legs
+ * (one book + direction), and legs chain source → destination into rows:
+ *
+ * - one (possibly multi-hop) swap → one chain → one row;
+ * - unrelated swaps batched in one transaction → separate rows;
+ * - a token-wise chaining batch is indistinguishable from one multi-hop swap
+ *   and merges (documented trade-off);
+ * - cyclic batches that fit no linear chain degrade to one row per leg.
+ *
+ * Fills with no resolvable state (historical `orderId = 0` ghost fills) or an
+ * unknown book are dropped; a group may therefore produce no rows.
+ */
+function buildSwapRows(group, options) {
+    const { order, quoteByBase, states } = options;
+    const priceScale = BigInt(Tick.priceScale);
+    const oriented = [];
+    for (const fill of group.fills) {
+        // Latest state event strictly before the fill position. The flip a fill
+        // itself triggers logs *after* the fill, so it never applies to its own
+        // fill; the baseline (argMax) event carries position `(-1, -1)`.
+        const events = states.get(fill.orderId);
+        if (!events)
+            continue;
+        let state;
+        for (let i = events.length - 1; i >= 0; i--) {
+            const event = events[i];
+            if (event.blockNumber < group.blockNumber ||
+                (event.blockNumber === group.blockNumber && event.logIndex < fill.logIndex)) {
+                state = event;
+                break;
+            }
+        }
+        if (!state)
+            continue;
+        const baseAddress = Schema.TokenAddress.safeParse(state.token);
+        const quoteAddress = quoteByBase.get(state.token);
+        if (!baseAddress.success || quoteAddress === undefined)
+            continue;
+        // `amountFilled` is denominated in the book base; reconstruct the quote
+        // side from the tick.
+        const baseAmount = BigInt(fill.amountFilled);
+        const quoteAmount = (baseAmount * (priceScale + BigInt(state.tick))) / priceScale;
+        const base = { address: baseAddress.data, amount: baseAmount };
+        const quote = { address: quoteAddress, amount: quoteAmount };
+        const source = state.isBid ? base : quote;
+        const destination = state.isBid ? quote : base;
+        oriented.push({
+            destination,
+            fill: {
+                destinationToken: { address: destination.address, amount: destination.amount.toString() },
+                logIndex: fill.logIndex,
+                maker: fill.maker,
+                orderId: fill.orderId,
+                partialFill: fill.partialFill,
+                price: Tick.toPrice(state.tick),
+                sourceToken: { address: source.address, amount: source.amount.toString() },
+            },
+            source,
+        });
+    }
+    if (oriented.length === 0)
+        return [];
+    // Bucket fills into legs: one (source → destination) edge per book +
+    // direction, amounts summed.
+    const legs = new Map();
+    for (const item of oriented) {
+        const key = `${item.source.address}>${item.destination.address}`;
+        const leg = legs.get(key);
+        if (leg) {
+            leg.destinationAmount += item.destination.amount;
+            leg.fills.push(item.fill);
+            leg.sourceAmount += item.source.amount;
+        }
+        else
+            legs.set(key, {
+                destination: item.destination.address,
+                destinationAmount: item.destination.amount,
+                fills: [item.fill],
+                source: item.source.address,
+                sourceAmount: item.source.amount,
+            });
+    }
+    // Chain legs source → destination; each maximal chain is one swap row.
+    // When no chain head exists (a cyclic batch), fall back to one row per leg.
+    const remaining = new Set(legs.values());
+    const chains = [];
+    while (remaining.size > 0) {
+        const pool = [...remaining];
+        const head = pool.find((leg) => !pool.some((other) => other !== leg && other.destination === leg.source));
+        if (!head) {
+            for (const leg of pool)
+                chains.push([leg]);
+            break;
+        }
+        const chain = [head];
+        remaining.delete(head);
+        let current = head;
+        while (true) {
+            const next = [...remaining].find((leg) => leg.source === current.destination);
+            if (!next)
+                break;
+            chain.push(next);
+            remaining.delete(next);
+            current = next;
+        }
+        chains.push(chain);
+    }
+    const rows = chains.map((chain) => {
+        const first = chain[0];
+        const last = chain.at(-1);
+        const fills = chain.flatMap((leg) => leg.fills).sort((a, b) => a.logIndex - b.logIndex);
+        const logIndex = fills[0].logIndex;
+        // `mode` is recovered from transaction calldata and attached later
+        // ({@link resolveSwapModes}), only for the rows that make the final page —
+        // so the calldata lookup stays off the candidate scan's hot path.
+        return {
+            blockNumber: group.blockNumber,
+            destinationToken: { address: last.destination, amount: last.destinationAmount.toString() },
+            filledAt: group.timestamp,
+            fills,
+            id: `${group.transactionHash}-${logIndex}`,
+            logIndex,
+            mode: null,
+            rate: formatRate(last.destinationAmount, first.sourceAmount),
+            route: [first.source, ...chain.map((leg) => leg.destination)],
+            sourceToken: { address: first.source, amount: first.sourceAmount.toString() },
+            taker: group.taker,
+            transactionHash: group.transactionHash,
+        };
+    });
+    // Order a multi-row group by each row's first fill, in page direction.
+    const firstIndex = (row) => row.fills[0].logIndex;
+    rows.sort((a, b) => order === 'asc' ? firstIndex(a) - firstIndex(b) : firstIndex(b) - firstIndex(a));
+    return rows;
+}
+/**
+ * Formats a destination/source amount ratio as a fixed-decimal string at the
+ * DEX price scale (5 dp), via bigint math so large amounts don't lose float
+ * precision.
+ */
+function formatRate(destination, source) {
+    const scale = BigInt(Tick.priceScale);
+    const decimals = String(Tick.priceScale).length - 1;
+    if (source === 0n)
+        return `0.${'0'.repeat(decimals)}`;
+    const scaled = (destination * scale) / source;
+    return `${scaled / scale}.${(scaled % scale).toString().padStart(decimals, '0')}`;
+}
+/**
+ * Formats the taker-perspective rate (destination/source) for a fill of an
+ * order at `tick`. For maker bids that is the DEX price (quote per base); for
+ * asks it is its inverse, formatted to the same 5 dp as the price scale.
+ */
+function ohlcRate(order) {
+    if (order.isBid)
+        return Tick.toPrice(order.tick);
+    const priceScale = BigInt(Tick.priceScale);
+    return (Number(priceScale * priceScale) /
+        Number(priceScale + BigInt(order.tick)) /
+        Number(priceScale)).toFixed(5);
+}
+/**
+ * Parses a `(tick, isBid)` tuple returned by a ClickHouse `argMin`/`argMax`
+ * aggregate (JSON renders tuples as arrays; both members are small integers,
+ * so no string forcing is needed).
+ */
+function parseTickSide(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const tick = Value.toNumber(value[0]);
+    if (tick === undefined)
+        return undefined;
+    return { isBid: value[1] === 1 || value[1] === true, tick };
+}
+/**
+ * Resolves a candlestick (OHLC) aggregation for a single pair over a
+ * rolling window.
+ *
+ * The candles are aggregated **in ClickHouse**: each bucket folds server-side
+ * (open/close by fill position, high/low by executed rate, volume sums and
+ * fill counts), so the response covers the entire requested window no matter
+ * how many fills it contains — the previous implementation shipped the newest
+ * raw fills to the app capped at 1,000, which truncated busy pairs' 7d/30d
+ * windows to a few hours. The pair filter still resolves through the
+ * OrderPlaced-only `dex_orders` table, so fills of flipped orders remain
+ * invisible until order state lands at ingest (the `dex_ohlc_1m` plan).
+ *
+ * `OrderFilled` only carries the base-token `amountFilled`; the quote-side
+ * amount is reconstructed per fill from the order's tick using the DEX's
+ * fixed price scale (`quote = base * (priceScale + tick) / priceScale`),
+ * which assumes base and quote share decimals — true for the stablecoin DEX.
+ *
+ * Buckets are anchored against epoch (`intDiv(ts, intervalMs)`), so a `1h`
+ * bucket at `13:00–14:00` aligns to the wall clock regardless of when the
+ * request was made. Empty buckets are dropped; charting UIs that need a
+ * continuous axis can forward-fill from the previous close. `data` is
+ * returned oldest → newest, which is the canonical chart input order.
+ */
+async function getPairOhlc(c, options) {
+    const { chainId, interval, pair, window } = options;
+    const tidx = c.get('getTidx')(chainId);
+    // ClickHouse `DateTime64(3, 'UTC')` rejects ISO-Z; normalize to space form.
+    const fromTimestamp = formatClickHouseDateTime(new Date(Date.now() - windowMs(window)).toISOString());
+    const bucketMs = intervalMs(interval);
+    return Timing.time(c, 'pair_ohlc', async () => {
+        // Taker-perspective rate used only to *select* the high/low fill; the
+        // formatted rate string is recomputed in JS from the winning `(tick,
+        // isBid)` so it goes through the exact same formatting as open/close.
+        const scale = Tick.priceScale;
+        const rate = `if(p."isBid" = 1, (${scale} + p.tick) / ${scale}, ${scale} / (${scale} + p.tick))`;
+        // UInt256 sums are forced through `toString` so values past 2^53 survive
+        // JSON; the `(tick, isBid)` tuples are small integers and need no forcing.
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `
+        SELECT
+          intDiv(toUnixTimestamp64Milli(f.block_timestamp), ${bucketMs}) AS bucket,
+          count() AS fill_count,
+          toString(sum(f."amountFilled")) AS base_volume,
+          toString(sum(intDiv(f."amountFilled" * toUInt256(${scale} + p.tick), ${scale}))) AS quote_volume,
+          argMin(tuple(p.tick, p."isBid"), tuple(f.block_num, f.log_idx)) AS open_t,
+          argMax(tuple(p.tick, p."isBid"), tuple(f.block_num, f.log_idx)) AS close_t,
+          argMax(tuple(p.tick, p."isBid"), ${rate}) AS high_t,
+          argMin(tuple(p.tick, p."isBid"), ${rate}) AS low_t
+        FROM dex_fills f
+        JOIN dex_orders p ON p."orderId" = f."orderId"
+        WHERE f.address = '${stablecoinDex}'
+          AND f.block_timestamp >= '${fromTimestamp}'
+          AND f."orderId" IN (
+            SELECT p2."orderId" FROM dex_orders p2 WHERE p2.token = '${pair.base}'
+          )
+        GROUP BY bucket
+        ORDER BY bucket ASC
+      `,
+        });
+        const data = [];
+        for (const row of result.rows) {
+            const bucket = Value.toNumber(row['bucket']);
+            const fillCount = Value.toNumber(row['fill_count']);
+            const base = Value.toIntegerString(row['base_volume']);
+            const quote = Value.toIntegerString(row['quote_volume']);
+            const open = parseTickSide(row['open_t']);
+            const close = parseTickSide(row['close_t']);
+            const high = parseTickSide(row['high_t']);
+            const low = parseTickSide(row['low_t']);
+            if (bucket === undefined ||
+                fillCount === undefined ||
+                base === undefined ||
+                quote === undefined ||
+                !open ||
+                !close ||
+                !high ||
+                !low)
+                continue;
+            data.push({
+                close: ohlcRate(close),
+                fillCount,
+                high: ohlcRate(high),
+                id: `${pair.key}-${interval}-${bucket}`,
+                low: ohlcRate(low),
+                open: ohlcRate(open),
+                timestamp: new Date(bucket * bucketMs).toISOString(),
+                volume: { base, quote },
+            });
+        }
+        // The full window is always aggregated now; the field stays for contract
+        // stability until the next breaking version.
+        return { data, truncated: false };
+    });
+}
+/**
+ * Hard cap on the per-pair `OrderPlaced` scan that backs a resting-order
+ * snapshot. Bounds the worst-case SQL `LIMIT` and the number of `orderId`s
+ * batched into the cancellation/fill join. When the cap is hit the snapshot
+ * reflects only the most-recent window of placements; the response carries
+ * `truncated: true` so callers know older orders may be missing.
+ */
+const orderScanCap = 5000;
+/**
+ * Scan cap for the global resting-order feed (all pairs). Lower than
+ * {@link orderScanCap} on purpose: the global scan has no `token` predicate to
+ * narrow it, so it both reads more `OrderPlaced` rows and fans out more
+ * `OrderCancelled`/`OrderFilled` IN-batches than any per-pair scan. Each of
+ * those queries is an independent transient-`db error` opportunity under CI
+ * load, and a smaller window keeps the global request to a handful of round
+ * trips. Deep pages still flip `truncated`.
+ */
+const globalOrderScanCap = 2000;
+/**
+ * Batch size for `OrderCancelled` / `OrderFilled` `WHERE "orderId" IN (...)`
+ * lookups. ClickHouse evaluates the IN-list against the `topic1` bloom-filter
+ * index after the TIDX pushdown rewrite re-encodes each literal (see
+ * `tempoxyz/ak47` commit `273d88d`); very large lists still inflate SQL parse
+ * cost, but each batch is also an independent transient-error round trip, so
+ * 1000 balances parse cost against keeping the batch count (and thus the
+ * failure surface) low — a typical pair snapshot still resolves in one trip and
+ * the capped global feed in ~two.
+ */
+const orderInBatchSize = 1000;
+/**
+ * Signed-int16 bias used to encode `tick` in the cursor as a non-negative
+ * uint string. `Cursor.Field === 'int'` is non-negative-only, so signed ticks
+ * (range `[-32768, 32767]`) are shifted into `[0, 65535]` before encoding.
+ */
+const orderCursorTickBias = 32768;
+/**
+ * Resolves a page of resting maker orders, optionally scoped to one pair.
+ *
+ * Strategy: snapshot the resting set in one pass (memoized briefly to
+ * amortize bursty UI polling), then sort, filter, and paginate the snapshot
+ * in memory. The underlying scans target the indexer's ClickHouse OLAP path
+ * (`engine=clickhouse`): `OrderPlaced` is filtered by the pair's base `token`
+ * when scoped (string column with a bloom-filter index on `topic1`), and the
+ * fill / cancellation joins use `WHERE "orderId" IN (...)` against the same
+ * index. The decoded `tick` column has no ClickHouse index, so tick sort is
+ * still applied app-side. Aggregation also runs in the app because
+ * indexer-side `SUM(...)` over decoded columns is currently unreliable.
+ *
+ * `remaining = OrderPlaced.amount - sum(OrderFilled.amountFilled)`; orders
+ * with an `OrderCancelled` event are excluded outright. Each row is annotated
+ * with its pair: the scoped feed reuses the resolved `pair`, the unscoped
+ * feed resolves per row from the supplied pair index (rows whose pair is
+ * unknown are dropped).
+ */
+async function getOrders(c, options) {
+    const { chainId, cursor, limit, maker, order, page, pair, pairIndex, side, sort } = options;
+    const store = c.get('store');
+    return Timing.time(c, 'orders', async () => {
+        // Snapshot is invariant in `(chainId, base?, maker?)`; sort/side/order are
+        // applied app-side so they don't fragment the cache. Short TTL keeps the
+        // resting set fresh against incoming fills/cancellations without making
+        // each request pay the scan cost.
+        const snapshot = await Store.memoize(() => loadRestingOrders(c, pair
+            ? { chainId, base: pair.base, maker }
+            : { chainId, maker, scanCap: globalOrderScanCap }), {
+            key: `exchange:v1:${chainId}:orders:${pair ? pair.base : 'all'}:${maker ?? '*'}:v1`,
+            store,
+            ttl: Ttl.seconds(15),
+        });
+        const { hasMore, nextCursor, pageRows, total } = pageRestingOrders(snapshot.orders, {
+            cursor,
+            limit,
+            order,
+            page,
+            side,
+            sort,
+        });
+        const data = [];
+        for (const row of pageRows) {
+            const rowPair = pair ?? pairIndex.get(row.token);
+            if (!rowPair)
+                continue;
+            const shaped = shapeRestingOrder(row);
+            if (!shaped)
+                continue;
+            data.push({
+                ...shaped,
+                pair: {
+                    base: { address: rowPair.base },
+                    key: rowPair.key,
+                    quote: { address: rowPair.quote },
+                },
+            });
+        }
+        return { data, hasMore, nextCursor, total, truncated: snapshot.truncated };
+    });
+}
+/**
+ * Applies the side filter, sort, and keyset pagination over an in-memory
+ * resting-order snapshot, returning the page rows plus pagination state.
+ * Shared by the per-pair ({@link getPairOrders}) and global ({@link getOrders})
+ * feeds so the sort comparator and cursor walk never drift between them.
+ *
+ * Sort: `tick` ranks by price (canonical orderbook orientation when paired
+ * with `order=asc` for asks / `order=desc` for bids), tie-breaking by newest
+ * placement so callers can always derive a stable cursor. `time` orders by
+ * placement `(block_num, log_idx)`. The cursor encodes the full sort key (not
+ * just `(block, log)`) so pagination stays correct even if the snapshot
+ * rotates between requests and the previous-page row is gone.
+ */
+function pageRestingOrders(orders, options) {
+    const { cursor: cursorToken, limit, order, side, sort } = options;
+    // Bounded positional lane (exclusive with `cursor` at the schema): the
+    // snapshot is in memory, so a positional page is an exact slice of
+    // `(page - 1) * limit` rows.
+    const page = options.page !== undefined && options.page > 1 ? options.page : undefined;
+    const offset = page !== undefined ? (page - 1) * limit : undefined;
+    // Side filter is the cheapest in-memory cut, so apply it first.
+    const sided = side === undefined ? orders : orders.filter((row) => row.isBid === (side === 'bid'));
+    const dir = order === 'asc' ? 1 : -1;
+    const sorted = [...sided].sort((a, b) => {
+        if (sort === 'tick') {
+            if (a.tick !== b.tick)
+                return (a.tick - b.tick) * dir;
+            if (a.blockNumber !== b.blockNumber)
+                return b.blockNumber - a.blockNumber;
+            return b.logIndex - a.logIndex;
+        }
+        if (a.blockNumber !== b.blockNumber)
+            return (a.blockNumber - b.blockNumber) * dir;
+        return (a.logIndex - b.logIndex) * dir;
+    });
+    const cursorFields = sort === 'tick' ? ['uint', 'int', 'int'] : ['int', 'int'];
+    const cursor = cursorToken ? Cursor.decode(cursorToken, cursorFields) : undefined;
+    let startIndex = offset ?? 0;
+    if (cursor) {
+        while (startIndex < sorted.length && !isPastCursor(sorted[startIndex], cursor, sort, dir))
+            startIndex += 1;
+    }
+    const window = sorted.slice(startIndex, startIndex + limit + 1);
+    const hasMore = window.length > limit;
+    const pageRows = window.slice(0, limit);
+    const last = hasMore ? pageRows.at(-1) : undefined;
+    const nextTuple = last ? cursorTupleFromOrder(last, sort) : undefined;
+    const nextCursor = nextTuple ? Cursor.encode(nextTuple) : null;
+    // `total` is the count of side-filtered resting orders before pagination —
+    // the in-memory basis for the opt-in `totalCount` (a lower bound when the
+    // underlying placement scan was truncated).
+    return { hasMore, nextCursor, pageRows, total: sided.length };
+}
+/**
+ * Number of grid ticks probed per side per multicall round while walking the
+ * book outward from its best tick. Real books cluster near peg, so the
+ * default `levels` resolves in one round for a typical book; a sparse book
+ * keeps walking in rounds of this size until the tick range is exhausted
+ * (worst case ~401 positions per side, the old blanket-scan cost).
+ */
+const depthScanChunk = 100;
+/**
+ * Resolves the current orderbook depth for a single pair, denominated in the
+ * base token. The stablecoin DEX precompile exposes per-tick aggregates via
+ * `getTickLevel(base, tick, isBid)`. Rather than blanket-scanning every valid
+ * tick (~401 per side — multiple seconds of serial EVM work per request), we
+ * first read the book head (`books(pairKey)` → `bestBidTick`/`bestAskTick`)
+ * and walk each side outward from its best tick in {@link depthScanChunk}
+ * chunks, stopping as soon as `levels` non-empty levels are collected. Viem's
+ * deployless multicall coalesces each chunk into one `eth_call`. The best
+ * tick is by definition the side's outermost populated tick, so the outward
+ * walk observes every non-empty level in best-first order. A side whose best
+ * tick sits outside the valid range is empty (the precompile signals "no
+ * orders" with the int16 min/max sentinels) and is returned without scanning.
+ *
+ * Memoized briefly via `Store.memoize` so concurrent dashboard requests for
+ * the same pair share one RPC fanout; the route's `Cache.policies.feed`
+ * response cache layers on top of that.
+ */
+async function getPairDepth(c, options) {
+    const { chainId, levels, pair } = options;
+    const client = c.get('getClient')(chainId);
+    const store = c.get('store');
+    /**
+     * Walks one side outward from its best tick, probing `depthScanChunk` grid
+     * positions per round, until `levels` non-empty levels are collected or the
+     * tick range is exhausted. Probed ticks stay in best-first order, so
+     * `collectLevels` builds `cumulativeSize` and applies the cap directly.
+     */
+    const scanSide = async (isBid, bestTick) => {
+        if (bestTick < Tick.minTick || bestTick > Tick.maxTick)
+            return [];
+        const step = isBid ? -tickSpacing : tickSpacing;
+        const boundary = isBid ? Tick.minTick : Tick.maxTick;
+        const inRange = (tick) => (isBid ? tick >= boundary : tick <= boundary);
+        const probedTicks = [];
+        const probedLevels = [];
+        let nonEmpty = 0;
+        let cursor = bestTick;
+        while (nonEmpty < levels && inRange(cursor)) {
+            const chunk = [];
+            while (chunk.length < depthScanChunk && inRange(cursor)) {
+                chunk.push(cursor);
+                cursor += step;
+            }
+            // Each chunk's per-tick reads share one deployless multicall round trip
+            // via viem's auto-batching. Only `totalLiquidity` is needed.
+            const results = await Promise.all(chunk.map((tick) => client.dex.getTickLevel({ base: pair.base, isBid, tick })));
+            for (let i = 0; i < chunk.length; i++) {
+                probedTicks.push(chunk[i]);
+                probedLevels.push(results[i]);
+                if (results[i].totalLiquidity > 0n)
+                    nonEmpty += 1;
+            }
+        }
+        return collectLevels(probedTicks, probedLevels, {
+            limit: levels,
+            pairKey: pair.key,
+            side: isBid ? 'bid' : 'ask',
+        });
+    };
+    return Timing.time(c, 'pair_depth', () => Store.memoize(async () => {
+        const book = await Actions.dex.getOrderbook(client, {
+            base: pair.base,
+            quote: pair.quote,
+        });
+        const [asks, bids] = await Promise.all([
+            scanSide(false, book.bestAskTick),
+            scanSide(true, book.bestBidTick),
+        ]);
+        return { asks, bids };
+    }, {
+        key: `exchange:v1:${chainId}:depth:${pair.base}:${pair.quote}:levels:${levels}`,
+        store,
+        // The response cache (10s) already absorbs concurrent reads at the
+        // edge; this in-process memo just dedupes overlapping in-flight
+        // multicalls within a single instance.
+        ttl: Ttl.seconds(5),
+    }));
+}
+/**
+ * Returns `true` when `row` falls strictly after the position the cursor was
+ * issued at, under the active sort. Mirrors the comparator in `getPairOrders`
+ * so the cursor walk and the sort agree on row order.
+ */
+function isPastCursor(row, cursor, sort, dir) {
+    if (sort === 'tick') {
+        const cursorTick = Number(cursor[0]) - orderCursorTickBias;
+        const cursorBlock = cursor[1];
+        const cursorLog = cursor[2];
+        if (row.tick !== cursorTick)
+            return (row.tick - cursorTick) * dir > 0;
+        if (row.blockNumber !== cursorBlock)
+            return row.blockNumber < cursorBlock;
+        return row.logIndex < cursorLog;
+    }
+    const cursorBlock = cursor[0];
+    const cursorLog = cursor[1];
+    if (row.blockNumber !== cursorBlock)
+        return (row.blockNumber - cursorBlock) * dir > 0;
+    return (row.logIndex - cursorLog) * dir > 0;
+}
+/** Builds the cursor tuple for the last row of a page, matching the active sort. */
+function cursorTupleFromOrder(row, sort) {
+    if (sort === 'tick')
+        return [String(row.tick + orderCursorTickBias), row.blockNumber, row.logIndex];
+    return [row.blockNumber, row.logIndex];
+}
+/**
+ * Loads every resting maker order for a pair: scan `OrderPlaced` filtered by
+ * the pair's base token (and optional `maker`), then subtract fills and drop
+ * cancelled orders using batched `WHERE "orderId" IN (...)` joins.
+ *
+ * Returns the resting set along with a `truncated` flag set when the
+ * `OrderPlaced` scan hit `orderScanCap`. Callers surface the flag so
+ * pagination consumers can detect a partial view of the book.
+ */
+async function loadRestingOrders(c, options) {
+    const { base, chainId, maker, scanCap = orderScanCap } = options;
+    const tidx = c.get('getTidx')(chainId);
+    // Scan window is intentionally newest-first so a `truncated` snapshot still
+    // reflects current market activity rather than ancient placements.
+    const filters = [`address = '${stablecoinDex}'`];
+    if (base !== undefined)
+        filters.push(`token = '${base}'`);
+    if (maker !== undefined)
+        filters.push(`maker = '${maker}'`);
+    const where = `WHERE ${filters.join(' AND ')}`;
+    // ClickHouse OLAP path: bloom-filter index on `topic1` (and the `token`
+    // string column) handles `WHERE token = '<base>'` and the downstream
+    // `"orderId" IN (...)` joins natively, without the per-row decode cost of
+    // the Postgres `abi_uint(topic1)` fallback.
+    //
+    // `"isBid"` is aliased to a name that is *not* in the OrderPlaced event
+    // signature so tidx.ts's signature-driven result decoder skips it. ClickHouse
+    // serializes booleans as `1`/`0`, but tidx.ts validates `bool` columns with a
+    // strict `z.boolean()` derived from the signature and rejects integer
+    // representations. Aliasing dodges that decoder and lets us coerce
+    // numerically in `parsePlacedRow`.
+    const result = await tidx.fetch({
+        chainId,
+        engine: 'clickhouse',
+        query: `
+      SELECT "orderId", maker, amount, token, "isBid" AS is_bid_int, tick, tx_hash, block_num, log_idx, block_timestamp
+      FROM dex_orders
+      ${where}
+      ORDER BY block_num DESC, log_idx DESC
+      LIMIT ${scanCap + 1}
+    `,
+    });
+    const truncated = result.rows.length > scanCap;
+    const placedRows = result.rows.slice(0, scanCap);
+    const placed = [];
+    for (const row of placedRows) {
+        const parsed = parsePlacedRow(row);
+        if (parsed)
+            placed.push(parsed);
+    }
+    if (placed.length === 0)
+        return { orders: [], truncated };
+    const orderIds = placed.map((row) => row.orderId);
+    const [cancelled, fillSums] = await Promise.all([
+        fetchCancelledByIds(c, { chainId, orderIds }),
+        fetchFillSumsByIds(c, { chainId, orderIds }),
+    ]);
+    const orders = [];
+    for (const row of placed) {
+        if (cancelled.has(row.orderId))
+            continue;
+        const filled = fillSums.get(row.orderId) ?? 0n;
+        const remaining = BigInt(row.amount) - filled;
+        if (remaining <= 0n)
+            continue;
+        orders.push({ ...row, remaining: remaining.toString() });
+    }
+    return { orders, truncated };
+}
+/**
+ * Base-token chunk size for the multi-book `WHERE token IN (...)` scan in
+ * {@link resolveBookReserves}. `tidx.fetch` transmits queries as GET, so a
+ * single `IN (...)` of every base in a wide page overflows the request URI;
+ * 200 lowercase 20-byte literals stay comfortably under the indexer's ~60 KB
+ * SQL ceiling. Chunks resolve serially and merge.
+ */
+const reserveBaseInBatchSize = 200;
+/**
+ * Computes per-book resting-order reserves for a set of base tokens, mirroring
+ * the legacy `/gecko` adapter's pool-liquidity semantics: scan `OrderPlaced`
+ * scoped to the given bases, subtract fills, drop cancelled orders, then
+ * aggregate each order's `remaining` by side — asks into the base reserve, bids
+ * into the quote reserve.
+ *
+ * The bid leg is added in its placed (base-denominated) units **without** tick
+ * conversion, matching the legacy adapter exactly so GeckoTerminal's per-pool
+ * `reserve_in_usd` stays consistent with the figures it has indexed historically.
+ * (The on-chain `balanceOf` of the DEX settlement account — what the adapter
+ * used previously — is a single shared pool across every book sharing a quote
+ * token, so it cannot express per-book liquidity.)
+ *
+ * Reserves are keyed by **base** token (a book's identity), so two books sharing
+ * a quote token report distinct reserves. The `OrderPlaced` scan uses a fair
+ * per-token cap (`LIMIT ... BY token`) so one active book can't starve the
+ * others' newest placements under a shared budget; `truncated` is set when any
+ * book hits the cap. Like {@link loadRestingOrders}, this reads only
+ * `OrderPlaced` (`dex_orders`), so flip orders (which mutate side/tick via
+ * `OrderFlipped` without a new placement) are not reflected — acceptable for
+ * legacy parity, but not an exact economic TVL.
+ */
+export async function resolveBookReserves(c, options) {
+    const { bases, chainId, scanCap = orderScanCap } = options;
+    const reserves = new Map();
+    const unique = [...new Set(bases.map((base) => base.toLowerCase()))];
+    if (unique.length === 0)
+        return { reserves, truncated: false };
+    const tidx = c.get('getTidx')(chainId);
+    // Scan the newest `scanCap` `OrderPlaced` rows per base. `LIMIT ... BY token`
+    // is the ClickHouse fair cap; the app-side `perToken` guard re-applies it
+    // across chunks (a base can't span chunks, but the guard also flips
+    // `truncated` consistently) and against the `scanCap + 1` probe row.
+    let truncated = false;
+    const placed = [];
+    const perToken = new Map();
+    for (let i = 0; i < unique.length; i += reserveBaseInBatchSize) {
+        const group = unique.slice(i, i + reserveBaseInBatchSize);
+        const list = group.map((base) => `'${base}'`).join(', ');
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `
+        SELECT "orderId", maker, amount, token, "isBid" AS is_bid_int, tick, tx_hash, block_num, log_idx, block_timestamp
+        FROM dex_orders
+        WHERE address = '${stablecoinDex}' AND token IN (${list})
+        ORDER BY block_num DESC, log_idx DESC
+        LIMIT ${scanCap + 1} BY token
+      `,
+        });
+        for (const row of result.rows) {
+            const parsed = parsePlacedRow(row);
+            if (!parsed)
+                continue;
+            const count = perToken.get(parsed.token) ?? 0;
+            if (count >= scanCap) {
+                truncated = true;
+                continue;
+            }
+            perToken.set(parsed.token, count + 1);
+            placed.push(parsed);
+        }
+    }
+    if (placed.length === 0)
+        return { reserves, truncated };
+    const orderIds = placed.map((row) => row.orderId);
+    const [cancelled, fillSums] = await Promise.all([
+        fetchCancelledByIds(c, { chainId, orderIds }),
+        fetchFillSumsByIds(c, { chainId, orderIds }),
+    ]);
+    for (const row of placed) {
+        if (cancelled.has(row.orderId))
+            continue;
+        const filled = fillSums.get(row.orderId) ?? 0n;
+        const remaining = BigInt(row.amount) - filled;
+        if (remaining <= 0n)
+            continue;
+        const reserve = reserves.get(row.token) ?? { base: 0n, quote: 0n };
+        if (row.isBid)
+            reserve.quote += remaining;
+        else
+            reserve.base += remaining;
+        reserves.set(row.token, reserve);
+    }
+    return { reserves, truncated };
+}
+/**
+ * Parses one `OrderPlaced` row into the in-memory `RestingOrder` shape, with
+ * `remaining` provisionally set to `amount` (the loader fills it in once fills
+ * are joined). Returns `undefined` for malformed rows so the caller can drop
+ * them without failing the whole snapshot.
+ */
+function parsePlacedRow(row) {
+    const orderId = Value.toIntegerString(row['orderId']);
+    const maker = Schema.Address.safeParse(row['maker']);
+    const amount = Value.toIntegerString(row['amount']);
+    const tick = Value.toNumber(row['tick']);
+    const transactionHash = Schema.Hash.safeParse(row['tx_hash']);
+    const blockNumber = Value.toNumber(row['block_num']);
+    const logIndex = Value.toNumber(row['log_idx']);
+    const timestamp = Value.toIsoDateTime(row['block_timestamp']);
+    const token = Schema.TokenAddress.safeParse(row['token']);
+    if (orderId === undefined ||
+        !maker.success ||
+        amount === undefined ||
+        tick === undefined ||
+        !transactionHash.success ||
+        blockNumber === undefined ||
+        logIndex === undefined ||
+        timestamp === undefined ||
+        !token.success)
+        return undefined;
+    // `is_bid_int` is the aliased `OrderPlaced."isBid"` column; ClickHouse
+    // serializes booleans as `1`/`0`, and Postgres returns native booleans, so
+    // coerce both representations.
+    const isBidRaw = row['is_bid_int'];
+    const isBid = isBidRaw === true || isBidRaw === 1 || isBidRaw === '1';
+    // `amount` is already a decimal string (from `Value.toIntegerString`);
+    // `remaining` is provisionally the same until `loadRestingOrders` subtracts
+    // fills against it.
+    return {
+        amount,
+        blockNumber,
+        isBid,
+        logIndex,
+        maker: maker.data,
+        orderId,
+        remaining: amount,
+        tick,
+        timestamp,
+        token: token.data,
+        transactionHash: transactionHash.data,
+    };
+}
+/**
+ * Resolves the set of cancelled `orderId`s in the snapshot window via batched
+ * `OrderCancelled WHERE "orderId" IN (...)` queries. Empty input short-circuits
+ * without touching the indexer.
+ */
+async function fetchCancelledByIds(c, options) {
+    const { chainId, orderIds } = options;
+    const cancelled = new Set();
+    if (orderIds.length === 0)
+        return cancelled;
+    const tidx = c.get('getTidx')(chainId);
+    for (let i = 0; i < orderIds.length; i += orderInBatchSize) {
+        const batch = orderIds.slice(i, i + orderInBatchSize);
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `
+        SELECT "orderId"
+        FROM OrderCancelled
+        WHERE "orderId" IN (${batch.join(', ')})
+      `,
+            signatures: [orderCancelledSignature],
+        });
+        for (const row of result.rows) {
+            const id = Value.toIntegerString(row['orderId']);
+            if (id !== undefined)
+                cancelled.add(id);
+        }
+    }
+    return cancelled;
+}
+/**
+ * Sums `amountFilled` per `orderId` across all matching `OrderFilled` rows in
+ * the snapshot window via batched `WHERE "orderId" IN (...)` queries. Each
+ * placement may have many partial fills, so the loader sums them in the app
+ * (indexer-side `SUM(...)` over decoded columns is currently unreliable).
+ */
+async function fetchFillSumsByIds(c, options) {
+    const { chainId, orderIds } = options;
+    const sums = new Map();
+    if (orderIds.length === 0)
+        return sums;
+    const tidx = c.get('getTidx')(chainId);
+    for (let i = 0; i < orderIds.length; i += orderInBatchSize) {
+        const batch = orderIds.slice(i, i + orderInBatchSize);
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `
+        SELECT "orderId", "amountFilled"
+        FROM dex_fills
+        WHERE "orderId" IN (${batch.join(', ')})
+      `,
+        });
+        for (const row of result.rows) {
+            const id = Value.toIntegerString(row['orderId']);
+            const filled = Value.toIntegerString(row['amountFilled']);
+            if (id === undefined || filled === undefined)
+                continue;
+            sums.set(id, (sums.get(id) ?? 0n) + BigInt(filled));
+        }
+    }
+    return sums;
+}
+/**
+ * Validates and shapes one resting order into the public response shape. Rate
+ * is destination/source ratio relative to a taker: `price` for bids,
+ * `1/price` for asks, formatted to the same 5-dp precision as `Tick.toPrice`
+ * uses for `Tick.priceScale`.
+ */
+function shapeRestingOrder(row) {
+    const priceScale = BigInt(Tick.priceScale);
+    const tickOffset = BigInt(row.tick);
+    const price = Tick.toPrice(row.tick);
+    const rate = row.isBid
+        ? price
+        : (Number(priceScale * priceScale) /
+            Number(priceScale + tickOffset) /
+            Number(priceScale)).toFixed(5);
+    return {
+        amount: row.amount,
+        blockNumber: row.blockNumber,
+        id: row.orderId,
+        logIndex: row.logIndex,
+        maker: row.maker,
+        orderId: row.orderId,
+        placedAt: row.timestamp,
+        price,
+        rate,
+        remaining: row.remaining,
+        side: row.isBid ? 'bid' : 'ask',
+        tick: row.tick,
+        transactionHash: row.transactionHash,
+    };
+}
+/**
+ * Builds the per-side levels from a best-first list of `getTickLevel` results.
+ * Filters out empty ticks, accumulates `size` into `cumulativeSize` as we walk
+ * outward, and truncates to `limit` non-empty levels.
+ */
+function collectLevels(ticks, results, options) {
+    const { limit, pairKey, side } = options;
+    const out = [];
+    let running = 0n;
+    for (let i = 0; i < ticks.length && out.length < limit; i++) {
+        const size = results[i]?.totalLiquidity;
+        if (size === undefined || size === 0n)
+            continue;
+        running += size;
+        out.push({
+            cumulativeSize: running.toString(),
+            id: `${pairKey}-${side}-${ticks[i]}`,
+            price: Tick.toPrice(ticks[i]),
+            size: size.toString(),
+            tick: ticks[i],
+        });
+    }
+    return out;
+}
+/**
+ * Resolves a single DEX order's live placement + current state via the
+ * on-chain `dex.getOrder` view. The contract returns `orderId === 0n` when
+ * an order is unknown, which the caller surfaces as a 404. The pair the
+ * order belongs to is resolved from `bookKey` against the cached pair index.
+ *
+ * Memoized briefly so a burst of `/orders/:orderId` requests for the same id
+ * coalesces into a single RPC; the TTL stays short because `remaining`
+ * decreases as fills land.
+ */
+async function getOrder(c, options) {
+    const { chainId, orderId } = options;
+    const store = c.get('store');
+    const client = c.get('getClient')(chainId);
+    return Timing.time(c, 'order', () => Store.memoize(async () => {
+        // The on-chain DEX exposes the full order struct (placement params
+        // plus current `remaining`) in one view call. We resolve the pair
+        // off the returned `bookKey` concurrently with the RPC; on a warm
+        // pair-index cache that's effectively free.
+        const [chainOrder, pairsByKey] = await Promise.all([
+            Timing.time(c, 'order_dex_get', () => 
+            // The DEX reverts with `OrderDoesNotExist()` for ids it no longer
+            // holds (never placed, or filled/cancelled and cleared), rather
+            // than returning the zero struct. Map that revert to not-found so
+            // the route answers 404 instead of bubbling up as a 502.
+            client.dex.getOrder({ orderId: BigInt(orderId) }).catch((cause) => {
+                if (isOrderDoesNotExist(cause))
+                    return undefined;
+                throw cause;
+            })),
+            getPairIndexByKey(c, { chainId }),
+        ]);
+        // The DEX returns the zero struct (or reverts, handled above) when an
+        // order id is unknown.
+        if (!chainOrder || chainOrder.orderId === 0n)
+            return undefined;
+        // Pair index miss is a soft consistency floor (the index is bounded
+        // by `pairIndexLimit`); without `(base, quote)` we cannot frame the
+        // order, so surface as not-found.
+        const pair = pairsByKey.get(chainOrder.bookKey.toLowerCase());
+        if (!pair)
+            return undefined;
+        const tick = chainOrder.tick;
+        const isBid = chainOrder.isBid;
+        const tickOffset = BigInt(tick);
+        const priceScaleBig = BigInt(Tick.priceScale);
+        const price = Tick.toPrice(tick);
+        const mode = isBid ? 'exactSource' : 'exactDestination';
+        // Destination/source rate. Maker bids: taker sells base, receives
+        // quote; rate is `price` (quote per base). Maker asks: taker buys
+        // base; rate is `1/price`, formatted to the same fixed-decimal
+        // precision the DEX price scale supplies.
+        const rate = isBid
+            ? price
+            : (Number(priceScaleBig * priceScaleBig) /
+                Number(priceScaleBig + tickOffset) /
+                Number(priceScaleBig)).toFixed(5);
+        return {
+            amount: chainOrder.amount.toString(),
+            flipTick: chainOrder.flipTick,
+            id: chainOrder.orderId.toString(),
+            isBid,
+            isFlipOrder: chainOrder.isFlip,
+            maker: chainOrder.maker.toLowerCase(),
+            mode,
+            orderId: chainOrder.orderId.toString(),
+            pair: {
+                base: { address: pair.base },
+                key: pair.key,
+                quote: { address: pair.quote },
+            },
+            price,
+            rate,
+            remaining: chainOrder.remaining.toString(),
+            tick,
+        };
+    }, {
+        key: `exchange:v1:${chainId}:order:${orderId}`,
+        store,
+        ttl: Ttl.seconds(15),
+    }));
+}
+/**
+ * Detects the DEX `OrderDoesNotExist()` custom-error revert thrown by
+ * `dex.getOrder` for an unknown order id. Walks viem's wrapped error chain to
+ * the decoded `ContractFunctionRevertedError` and matches its `errorName`, so a
+ * different revert (or a transport failure) still propagates as a 502.
+ */
+function isOrderDoesNotExist(error) {
+    if (!(error instanceof BaseError))
+        return false;
+    const revert = error.walk((e) => e instanceof ContractFunctionRevertedError);
+    return (revert instanceof ContractFunctionRevertedError &&
+        revert.data?.errorName === 'OrderDoesNotExist');
+}
+/**
+ * Resolves a single page of `OrderFilled` events for one order. Pagination is
+ * keyset on `(block_num, log_idx)`, which is unique and append-only for the
+ * stream of fills against any one order — so cursors stay stable across new
+ * fills landing.
+ */
+async function getOrderFills(c, options) {
+    const { chainId, cursor: cursorToken, limit, order, orderId } = options;
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(chainId);
+    const direction = order === 'asc' ? 'ASC' : 'DESC';
+    const cursor = cursorToken ? Cursor.decode(cursorToken, ['int', 'int']) : undefined;
+    // Bounded positional lane (exclusive with `cursor` at the schema): page 1 is
+    // the head page, so it shares the head's SQL and cache entries; deeper pages
+    // translate to a SQL OFFSET of `(page - 1) * limit` rows.
+    const offset = options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : undefined;
+    return Timing.time(c, 'order_fills', () => Store.memoize(async () => {
+        const filters = [`address = '${stablecoinDex}'`, `"orderId" = ${orderId}`];
+        if (cursor !== undefined)
+            filters.push(Cursor.keyset([
+                { literal: Cursor.literal(cursor[0], 'int'), name: 'block_num', order },
+                { literal: Cursor.literal(cursor[1], 'int'), name: 'log_idx', order },
+            ]));
+        const where = `WHERE ${filters.join(' AND ')}`;
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `
+            SELECT "orderId", taker, "amountFilled", "partialFill", tx_hash, block_num, log_idx, block_timestamp
+            FROM dex_fills
+            ${where}
+            ORDER BY block_num ${direction}, log_idx ${direction}
+            LIMIT ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
+          `,
+        });
+        const page = Cursor.paginate({
+            rows: result.rows,
+            limit,
+            key: (row) => {
+                const block = Value.toNumber(row['block_num']);
+                const index = Value.toNumber(row['log_idx']);
+                return block !== undefined && index !== undefined ? [block, index] : undefined;
+            },
+        });
+        const data = [];
+        for (const row of page.rows) {
+            const fill = parseOrderFillRow(row);
+            if (fill)
+                data.push(fill);
+        }
+        return { data, nextCursor: page.nextCursor };
+    }, {
+        key: `exchange:v1:${chainId}:order:${orderId}:fills:${order}:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : offset !== undefined ? `page:${options.page}` : 'head'}:${limit}`,
+        store,
+        ttl: Ttl.seconds(10),
+    }));
+}
+/**
+ * Exact count of an order's fills, sharing {@link getOrderFills}'s
+ * `address`/`orderId` filter (minus pagination) so the count matches the page
+ * it annotates. Fills are 1:1 with `OrderFilled` events for the order; the
+ * `address`/`"orderId"` predicate aligns with the `dex_fills` sort key, so
+ * ClickHouse counts via the sparse primary index and the result is exact and
+ * cheap with no cap (`totalCountCapped` is always `false`). Feeds the opt-in
+ * `meta.totalCount`.
+ */
+async function countOrderFills(c, options) {
+    const { chainId, orderId } = options;
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(chainId);
+    return Timing.time(c, 'order_fills_count', () => Store.memoize(async () => {
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `SELECT count(*) AS total FROM dex_fills WHERE address = '${stablecoinDex}' AND "orderId" = ${orderId}`,
+        });
+        const totalCount = Value.toNumber(result.rows[0]?.['total']) ?? 0;
+        return { totalCountCapped: false, totalCount };
+    }, {
+        key: `exchange:v1:${chainId}:order:${orderId}:fills:count`,
+        store,
+        ttl: Ttl.seconds(10),
+    }));
+}
+/**
+ * Per-key pair index derived from the existing per-base index. Built once
+ * and memoized at the same cadence as the pair index itself so chained
+ * `getOrder` lookups stay an O(1) `Map.get`.
+ */
+async function getPairIndexByKey(c, options) {
+    const pairsByBase = await getPairIndex(c, options);
+    const pairsByKey = new Map();
+    for (const pair of pairsByBase.values())
+        pairsByKey.set(pair.key.toLowerCase(), pair);
+    return pairsByKey;
+}
+/**
+ * Validates and shapes one `OrderFilled` row into the public `Fill` shape.
+ * Drops the row when any required column is malformed so the caller can omit
+ * it from the page without failing the whole response.
+ */
+function parseOrderFillRow(row) {
+    const amountFilled = Value.toIntegerString(row['amountFilled']);
+    const orderId = Value.toIntegerString(row['orderId']);
+    const taker = Schema.Address.safeParse(row['taker']);
+    const transactionHash = Schema.Hash.safeParse(row['tx_hash']);
+    const blockNumber = Value.toNumber(row['block_num']);
+    const logIndex = Value.toNumber(row['log_idx']);
+    const timestamp = Value.toIsoDateTime(row['block_timestamp']);
+    if (amountFilled === undefined ||
+        orderId === undefined ||
+        !taker.success ||
+        !transactionHash.success ||
+        blockNumber === undefined ||
+        logIndex === undefined ||
+        timestamp === undefined)
+        return undefined;
+    return {
+        amountFilled,
+        blockNumber,
+        filledAt: timestamp,
+        id: `${transactionHash.data}-${logIndex}`,
+        logIndex,
+        orderId,
+        partialFill: row['partialFill'] === true,
+        taker: taker.data,
+        transactionHash: transactionHash.data,
+    };
+}
+//# sourceMappingURL=exchanges.js.map