tapimo 0.0.0 → 0.0.2

package/dist/apps/tokens.js

@@ -0,0 +1,1789 @@
+import { Hono } from 'hono';
+import { AbiEvent, AbiParameters } from 'ox';
+import { ContractFunctionExecutionError } from 'viem';
+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 Path from '../internal/Path.js';
+import * as Response from '../internal/Response.js';
+import * as Schema from '../internal/Schema.js';
+import * as Store from '../internal/Store.js';
+import * as Tidx from '../internal/Tidx.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 Transactions from './transactions.js';
+const tokenCreatedSignature = 'event TokenCreated(address indexed token, string name, string symbol, string currency, address quoteToken, address admin, bytes32 salt)';
+// Topic0 of the `TokenCreated` event
+// (= 0x44f7b8011db3e3647a530b4ff635726de5fafc8fa8ad10f0f31c0eb9dd52fc65). The
+// deployed indexer's `tokencreated` event CTE cannot serve the `quoteToken` /
+// `admin` columns (selecting them returns `db error`), so the created-extras
+// lookup reads the raw `logs` table by topic0 and ABI-decodes the data blob
+// instead.
+const tokenCreatedTopic = AbiEvent.getSelector(tokenCreatedSignature);
+// Non-indexed `TokenCreated` data layout, in event-parameter order:
+// `[name, symbol, currency, quoteToken, admin, salt]`.
+const tokenCreatedData = AbiParameters.from([
+    'string',
+    'string',
+    'string',
+    'address',
+    'address',
+    'bytes32',
+]);
+// Topic0 of `Transfer(address,address,uint256)`; lifetime transfer statistics
+// aggregate the raw ClickHouse `logs` stream by emitting token contract.
+const transferTopic = AbiEvent.getSelector('event Transfer(address,address,uint256)');
+/** Zod schemas owned by the token handlers. */
+export var schema;
+(function (schema) {
+    /** Schemas for the getToken operation. */
+    let getToken;
+    (function (getToken) {
+        /** Path parameters for token metadata requests. */
+        getToken.Params = z
+            .object({
+            token: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address on Tempo.')),
+        })
+            .check(z.describe('Path parameters for looking up one token’s metadata.'));
+        /** Optional expensive fields that callers opt into via `include`. */
+        getToken.Include = z
+            .enum(['admin', 'createdAt', 'holderCount', 'quoteToken', 'transferStats'])
+            .check(z.describe('Extra token details to calculate only when you request them with `include`.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * fields. Expensive computations (the `createdAt`/`admin`/`quoteToken`
+         * indexer lookups, holder counts, and transfer statistics) are only run
+         * when explicitly requested, keeping the base response fast.
+         */
+        getToken.includeQuery = Schema.includeQuery(getToken.Include, 'Comma-separated extra token details to include, such as `admin,createdAt,holderCount,quoteToken,transferStats`.');
+        /** Query parameters for token metadata requests. */
+        getToken.Query = z
+            .object({
+            chainId: Schema.ChainIdQuery,
+            include: getToken.includeQuery,
+        })
+            .check(z.describe('Query parameters for looking up one token’s metadata.'));
+        /** TIP-20 token metadata returned by token endpoints. */
+        getToken.Response = Schema.describe(z.object({
+            address: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address on Tempo.')),
+            admin: z
+                .optional(Schema.Address)
+                .check(z.describe('Token admin from the onchain `TokenCreated` event, present when requested ' +
+                'via `include=admin` and indexed data is available.')),
+            currency: z
+                .string()
+                .check(z.describe('The currency label for this token, such as `USD` for USD-denominated stablecoins.'), z.meta({ examples: ['USD'] })),
+            createdAt: z
+                .optional(z.iso.datetime())
+                .check(z.describe('Token creation timestamp, present when requested via `include=createdAt` ' +
+                'and indexed data is available.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+            decimals: z
+                .number()
+                .check(z.int(), z.nonnegative(), z.describe('The number of decimal places the token uses; Tempo stablecoins typically use 6.'), z.meta({ examples: [6] })),
+            holderCount: z
+                .optional(z.number().check(z.int(), z.nonnegative()))
+                .check(z.describe('The number of accounts that currently hold a positive balance of this token, when indexed holder data is available.'), z.meta({ examples: [1234] })),
+            id: z
+                .string()
+                .check(z.describe('A stable resource ID for this token, equal to its contract address.'), z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] })),
+            logoUri: z.optional(z.string()).check(z.describe('A URL for the token’s logo image, when one is available.'), z.meta({
+                examples: [
+                    'https://api.tempo.xyz/data/4217/icons/0x20c0000000000000000000008f5425160ebe5525.svg',
+                ],
+            })),
+            name: z
+                .string()
+                .check(z.describe('The token’s human-readable name.'), z.meta({ examples: ['USD Coin'] })),
+            quoteToken: z
+                .optional(Schema.Address)
+                .check(z.describe('Quote token from the onchain `TokenCreated` event, present when requested ' +
+                'via `include=quoteToken` and indexed data is available.')),
+            symbol: z
+                .string()
+                .check(z.describe('The short ticker symbol wallets and apps show for this token.'), z.meta({ examples: ['USDC'] })),
+            totalSupply: z
+                .optional(z.string().check(z.regex(/^\d+$/)))
+                .check(z.describe('The token’s total supply as a decimal string in the smallest unit, so large values keep full precision.'), z.meta({ examples: ['1000000000000'] })),
+            transferStats: z
+                .optional(z.object({
+                count: z
+                    .number()
+                    .check(z.int(), z.nonnegative(), z.describe('The total number of `Transfer` events emitted by this token.'), z.meta({ examples: [12345] })),
+                firstAt: z
+                    .nullable(z.iso.datetime())
+                    .check(z.describe('The time of this token’s first `Transfer` event, or `null` if no transfers exist.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
+                lastAt: z
+                    .nullable(z.iso.datetime())
+                    .check(z.describe('The time of this token’s most recent `Transfer` event, or `null` if no transfers exist.'), z.meta({ examples: ['2024-06-01T12:00:00Z'] })),
+            }))
+                .check(z.describe('Lifetime `Transfer` event statistics, present when requested via ' +
+                '`include=transferStats` and indexed data is available.')),
+            verified: z
+                .boolean()
+                .check(z.describe('Whether this token is in Tempo’s curated verified token list.'), z.meta({ examples: [true] })),
+        }), 'Token metadata for a TIP-20 token, including name, symbol, decimals, supply, and optional indexed details.');
+    })(getToken = schema.getToken || (schema.getToken = {}));
+    /**
+     * Trimmed TIP-20 token reference embedded in list/feed responses via
+     * `include=token`. Carries identity and display fields only; supply-level and
+     * temporal facts (`totalSupply`, `holderCount`, `createdAt`) belong on the
+     * token detail endpoint, not in feed rows.
+     */
+    schema.Token = Schema.describe(z.pick(getToken.Response, {
+        address: true,
+        currency: true,
+        decimals: true,
+        id: true,
+        logoUri: true,
+        name: true,
+        symbol: true,
+        verified: true,
+    }), 'A compact TIP-20 token reference with identity and display fields only.');
+    /** Schemas for the getTokenBySymbol operation. */
+    let getTokenBySymbol;
+    (function (getTokenBySymbol) {
+        /** Hono route pattern for verified token symbols. */
+        // Symbols must start with a letter so this route cannot claim address-shaped
+        // paths before the address validator gets a chance to report token errors.
+        getTokenBySymbol.routePattern = '[A-Za-z][A-Za-z0-9._]{0,63}';
+        const pattern = new RegExp(`^${getTokenBySymbol.routePattern}$`);
+        /** Path parameters for token symbol metadata requests. */
+        getTokenBySymbol.Params = z
+            .object({
+            symbol: z.string().check(z.regex(pattern), z.describe('The symbol of a token in Tempo’s verified token list.'), z.meta({
+                examples: ['USDC.e'],
+            })),
+        })
+            .check(z.describe('Path parameters for looking up a verified token by symbol.'));
+    })(getTokenBySymbol = schema.getTokenBySymbol || (schema.getTokenBySymbol = {}));
+    /** Schemas for the getTokenLogo operation. */
+    let getTokenLogo;
+    (function (getTokenLogo) {
+        /** Path parameters for token logo image requests. */
+        getTokenLogo.Params = z
+            .object({
+            token: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address on Tempo.')),
+        })
+            .check(z.describe('Path parameters for fetching a token logo image.'));
+        /** Query parameters for token logo image requests. */
+        getTokenLogo.Query = z
+            .object({
+            chainId: Schema.ChainIdQuery,
+        })
+            .check(z.describe('Query parameters for fetching a token logo image.'));
+    })(getTokenLogo = schema.getTokenLogo || (schema.getTokenLogo = {}));
+    /** Schemas for the getTokens operation. */
+    let getTokens;
+    (function (getTokens) {
+        /** Query parameters for token list requests. */
+        getTokens.Query = z
+            .strictObject({
+            addresses: z
+                .optional(z.pipe(
+            // Bare-transform input stage, opaque to JSON-schema generation
+            // (the `meta` below documents the parameter): accepts the comma
+            // form and the repeated form (`?addresses=a&addresses=b`), which
+            // the validator delivers as a `string[]`.
+            z.transform((value) => (Array.isArray(value) ? value : [value])
+                .flatMap((entry) => String(entry).split(','))
+                .map((entry) => entry.trim())
+                .filter(Boolean)), z.array(Schema.TokenAddress).check(z.maxLength(50))))
+                .check(z.meta({
+                type: 'array',
+                items: { type: 'string' },
+                examples: [['0x20c0000000000000000000008f5425160ebe5525']],
+            }), z.describe('Comma-separated token contract addresses to fetch (max 50). Returns a ' +
+                'single page in input order (unresolvable addresses omitted); `cursor`, ' +
+                '`page`, and `order` are inapplicable. Combines with `include`; ' +
+                '`currency` and `verified` further filter the resolved set.')),
+            chainId: Schema.ChainIdQuery,
+            currency: z
+                .optional(z.string())
+                .check(z.meta({ examples: VerifiedTokens.currencies }), z.describe('Only include tokens denominated in this currency (e.g. `USD`). ' +
+                'Case-insensitive. Matched against the `currency` field of the onchain ' +
+                '`TokenCreated` event, so any string a token deployer wrote is acceptable; ' +
+                'the listed examples are the well-known curated currencies.')),
+            cursor: Schema.Cursor,
+            include: getToken.includeQuery,
+            limit: Schema.Limit,
+            order: Schema.Order,
+            page: Schema.Page,
+            verified: z
+                .optional(Schema.booleanQuery())
+                .check(z.describe('When `true`, only return tokens in the curated verified list. ' +
+                '`currency`, `include`, and the pagination parameters (`limit`, ' +
+                '`page`, `cursor`, `order`) all apply; the list is paginated ' +
+                'positionally over its canonical order (`order=asc` reverses it).'), z.meta({ examples: [true] })),
+        })
+            .check(...Schema.pageChecks(), z.describe('Query parameters for listing TIP-20 tokens.'));
+        /** Page of TIP-20 tokens. */
+        getTokens.Response = z
+            .object({
+            data: z.array(getToken.Response).check(z.describe('The tokens in this page.')),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A page of TIP-20 tokens on Tempo.'));
+    })(getTokens = schema.getTokens || (schema.getTokens = {}));
+    /** Schemas for the getTokenHolders operation. */
+    let getTokenHolders;
+    (function (getTokenHolders) {
+        /** Path parameters for token holder requests. */
+        getTokenHolders.Params = z
+            .object({
+            token: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address on Tempo.')),
+        })
+            .check(z.describe('Path parameters for listing a token’s holders.'));
+        /** Optional related resources that callers opt into via `include`. */
+        getTokenHolders.Include = z
+            .enum(['token', 'totalCount'])
+            .check(z.describe('Related resources to include only when you request them with `include`.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed. Extra lookups (token metadata, the holder total) only
+         * run when explicitly requested, keeping the base holder page fast.
+         */
+        getTokenHolders.includeQuery = Schema.includeQuery(getTokenHolders.Include, 'Comma-separated related resources to include, such as `token,totalCount`.');
+        /** Query parameters for token holder requests. */
+        getTokenHolders.Query = z
+            .strictObject({
+            chainId: Schema.ChainIdQuery,
+            cursor: Schema.Cursor,
+            include: getTokenHolders.includeQuery,
+            limit: Schema.Limit,
+            page: Schema.Page,
+        })
+            .check(...Schema.pageChecks(), z.describe('Query parameters for listing a token’s holders.'));
+        /** A single TIP-20 token holder. */
+        getTokenHolders.Holder = z
+            .object({
+            address: Schema.Address.check(z.describe('The account address that holds this token.')),
+            balance: z
+                .string()
+                .check(z.regex(/^\d+$/), z.describe('A non-negative whole number, given as a decimal string so very large token amounts keep full precision. Expressed in the smallest unit of the token.'), z.meta({ examples: ['1000000'] })),
+            id: z
+                .string()
+                .check(z.describe('A stable resource ID for this holder, equal to the holder address.'), z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] })),
+        })
+            .check(z.describe('One account holding a positive balance of this TIP-20 token.'));
+        /** Resources embedded on demand via `include`. */
+        getTokenHolders.Meta = z
+            .object({
+            totalCountCapped: z
+                .optional(Schema.TotalCountCapped)
+                .check(z.describe('Whether `totalCount` reached the API count cap; holder counts are exact here.')),
+            token: z
+                .optional(schema.Token)
+                .check(z.describe('A compact token reference, returned when you request `include=token`.')),
+            totalCount: z
+                .optional(Schema.TotalCount)
+                .check(z.describe('The total number of token holders, returned when you request `include=totalCount`.')),
+        })
+            .check(z.describe('Extra resources included because you requested them with `include`.'));
+        /** Page of TIP-20 token holders, ordered by balance descending. */
+        getTokenHolders.Response = z
+            .object({
+            data: z
+                .array(getTokenHolders.Holder)
+                .check(z.describe('The holders in this page, ordered by balance from highest to lowest.')),
+            meta: z.optional(getTokenHolders.Meta).check(z.describe('Extra resources you requested with `include`.')),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A page of accounts holding this TIP-20 token.'));
+    })(getTokenHolders = schema.getTokenHolders || (schema.getTokenHolders = {}));
+    /** Schemas for the getTokenTransactions operation. */
+    let getTokenTransactions;
+    (function (getTokenTransactions) {
+        /** Path parameters for token transaction requests. */
+        getTokenTransactions.Params = z
+            .object({
+            token: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address on Tempo.')),
+        })
+            .check(z.describe('Path parameters for listing transactions involving this token contract.'));
+        /** Optional related resources that callers opt into via `include`. */
+        getTokenTransactions.Include = z
+            .enum(['feeToken', 'token', 'totalCount'])
+            .check(z.describe('Related resources to include only when you request them with `include`.'));
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed. Extra lookups only run when explicitly requested,
+         * keeping the base transaction page fast.
+         */
+        getTokenTransactions.includeQuery = Schema.includeQuery(getTokenTransactions.Include, 'Comma-separated related resources to include, such as `feeToken,token,totalCount`.');
+        /** Query parameters for token transaction requests. */
+        getTokenTransactions.Query = z
+            .strictObject({
+            'blockNumber.from': Schema.blockNumberBound('transactions', 'from'),
+            'blockNumber.to': Schema.blockNumberBound('transactions', 'to'),
+            chainId: Schema.ChainIdQuery,
+            cursor: Schema.Cursor,
+            feePayer: z
+                .optional(Schema.Address)
+                .check(z.describe('Only include transactions where this account paid the fee.')),
+            feeToken: z
+                .optional(Schema.TokenAddress)
+                .check(z.describe('Only include transactions whose fee was paid in this token. On Tempo, fees are paid in USD stablecoins instead of a separate volatile gas token.')),
+            include: getTokenTransactions.includeQuery,
+            limit: Schema.Limit,
+            order: Schema.Order,
+            page: Schema.Page,
+            'timestamp.from': Schema.timestampBound('transactions', 'from'),
+            'timestamp.to': Schema.timestampBound('transactions', 'to'),
+        })
+            .check(...Schema.pageChecks(), z.describe('Query parameters for listing transactions involving this token contract.'));
+        /** Resources embedded on demand via `include`. */
+        getTokenTransactions.Meta = z
+            .object({
+            totalCountCapped: z
+                .optional(Schema.TotalCountCapped)
+                .check(z.describe('Whether `totalCount` reached the API count cap; when `true`, treat the count as a lower bound.')),
+            token: z
+                .optional(schema.Token)
+                .check(z.describe('A compact token reference, returned when you request `include=token`.')),
+            totalCount: z
+                .optional(Schema.TotalCount)
+                .check(z.describe('The capped total number of matching transactions, returned when you request `include=totalCount`.')),
+        })
+            .check(z.describe('Extra resources included because you requested them with `include`.'));
+        /**
+         * Page of transactions touching the token contract. Each row is the
+         * humanized transaction shape returned by `GET /transactions/:transactionHash`;
+         * the optional `meta.token` embed is the token being scoped to.
+         *
+         * The `data` schema is wrapped in `z.lazy` because `transactions.ts`
+         * already imports `Tokens.schema` at module init; a direct reference
+         * here would close the import cycle and crash during evaluation.
+         */
+        getTokenTransactions.Response = z
+            .object({
+            data: z
+                .array(z.lazy(() => Transactions.schema.getTransaction.Response))
+                .check(z.describe('The transactions in this page.')),
+            meta: z.optional(getTokenTransactions.Meta).check(z.describe('Extra resources you requested with `include`.')),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A page of transactions that interact with this token contract.'));
+    })(getTokenTransactions = schema.getTokenTransactions || (schema.getTokenTransactions = {}));
+})(schema || (schema = {}));
+/** Creates token handlers. */
+export function tokens() {
+    return new Hono()
+        .get('/', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('query', schema.getTokens.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Lists TIP-20 tokens on Tempo. TIP-20 is Tempo’s payments-focused token standard and a superset of ERC-20.',
+        operationId: 'getTokens',
+        responses: OpenApi.responses({
+            success: { description: 'A page of TIP-20 tokens.', schema: schema.getTokens.Response },
+        }),
+        summary: 'List tokens',
+        tags: ['Tokens'],
+    }), Cache.response({
+        cacheControl: Cache.policies.metadata,
+        name: 'tempo-api:tokens:v1',
+        // Verified pages are served from the curated snapshot, not the indexer,
+        // so their cached entry must depend on the snapshot version — otherwise
+        // a publish (create/patch/remove/replace) or reseed never invalidates
+        // the page and a stale list is served indefinitely. Mirrors the
+        // address-balances route. Non-verified pages stay URL-keyed.
+        key: async (c) => {
+            const base = Cache.urlKey(c, schema.getTokens.Query);
+            const query = schema.getTokens.Query.parse(Object.fromEntries(new URL(c.req.url).searchParams));
+            if (!query.verified)
+                return base;
+            const chainId = query.chainId ?? c.get('chainId');
+            const { version } = await VerifiedTokens.snapshot(c, chainId);
+            return `${base}:v:${version}`;
+        },
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid query parameters',
+            });
+        const query = c.req.valid('query');
+        try {
+            const chainId = query.chainId ?? c.get('chainId');
+            return c.json(Response.validated(schema.getTokens.Response, await getTokens(c, {
+                addresses: query.addresses,
+                chainId,
+                currency: query.currency,
+                cursor: query.cursor,
+                include: query.include,
+                limit: query.limit,
+                order: query.order,
+                page: query.page,
+                verified: query.verified,
+            })), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get(`/:symbol{${schema.getTokenBySymbol.routePattern}}`, Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getTokenBySymbol.Params, {
+        code: 'symbol_invalid',
+        message: 'Invalid token symbol',
+    }), OpenApi.validate('query', schema.getToken.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Returns token metadata for a verified TIP-20 token using its symbol, such as `USDC`.',
+        operationId: 'getTokenBySymbol',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No token was found for this address or symbol.',
+                    codes: ['token_not_found'],
+                },
+                502: 'An upstream RPC or indexer request failed while resolving this token.',
+            },
+            success: {
+                description: 'Metadata for one TIP-20 token.',
+                schema: schema.getToken.Response,
+            },
+        }),
+        summary: 'Get token by symbol',
+        tags: ['Tokens'],
+    }), Cache.response({
+        cacheControl: Cache.policies.metadata,
+        name: 'tempo-api:tokens:v1',
+        key: (c) => Cache.urlKey(c, schema.getToken.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'symbol_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { symbol } = c.req.valid('param');
+        const query = c.req.valid('query');
+        const chainId = query.chainId ?? c.get('chainId');
+        try {
+            const snapshot = await VerifiedTokens.snapshot(c, chainId);
+            const token = snapshot.bySymbol.get(symbol.toLowerCase());
+            if (token)
+                return getToken(c, {
+                    address: token.address,
+                    chainId,
+                    include: query.include,
+                    snapshot,
+                });
+            return Response.error(c, {
+                code: 'token_not_found',
+                message: 'Token not found',
+                status: 404,
+            });
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get('/:token', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getToken.Params, {
+        code: 'token_invalid',
+        message: 'Invalid token address',
+    }), OpenApi.validate('query', schema.getToken.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Returns token metadata for a TIP-20 contract address, whether or not the token is in the verified list.',
+        operationId: 'getToken',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    description: 'No token was found for this address or symbol.',
+                    codes: ['token_not_found'],
+                },
+                502: 'An upstream RPC or indexer request failed while resolving this token.',
+            },
+            success: {
+                description: 'Metadata for one TIP-20 token.',
+                schema: schema.getToken.Response,
+            },
+        }),
+        summary: 'Get token by address',
+        tags: ['Tokens'],
+    }), Cache.response({
+        cacheControl: Cache.policies.metadata,
+        name: 'tempo-api:tokens:v1',
+        key: (c) => Cache.urlKey(c, schema.getToken.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'token_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { token: address } = c.req.valid('param');
+        const query = c.req.valid('query');
+        const chainId = query.chainId ?? c.get('chainId');
+        return getToken(c, { address, chainId, include: query.include });
+    })
+        .get('/:token/logo', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getTokenLogo.Params, {
+        code: 'token_invalid',
+        message: 'Invalid token address',
+    }), OpenApi.validate('query', schema.getTokenLogo.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Returns the logo image for a TIP-20 token, using Tempo’s curated asset when available.',
+        operationId: 'getTokenLogo',
+        responses: {
+            200: {
+                content: { 'image/*': {} },
+                description: 'The token logo image.',
+                headers: OpenApi.successHeaders,
+            },
+            400: OpenApi.standardError(400, 'The request parameters were invalid.'),
+            401: OpenApi.standardError(401, 'The API key is missing or invalid.'),
+            404: OpenApi.standardError(404, 'No logo image was found for this token.', [
+                'token_logo_not_found',
+            ]),
+            429: OpenApi.standardError(429, 'Too many requests; wait and try again.'),
+            500: OpenApi.standardError(500, 'The API encountered an internal error.'),
+            502: OpenApi.standardError(502, 'An upstream RPC request failed while fetching the logo.'),
+        },
+        summary: 'Get token logo',
+        tags: ['Tokens'],
+    }), 
+    // Publish the `asset` (forever, public) policy so the pre-auth edge cache
+    // serves logo bytes to every caller without re-running the handler — the
+    // bytes carry no per-principal data. `vary` is `Accept-Encoding` only so a
+    // single shared entry serves authenticated and anonymous callers alike.
+    Cache.response({
+        cacheControl: Cache.policies.asset,
+        name: 'tempo-api:tokens:v1',
+        key: (c) => Cache.urlKey(c, schema.getTokenLogo.Query),
+        vary: ['Accept-Encoding'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'token_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { token: address } = c.req.valid('param');
+        const query = c.req.valid('query');
+        const chainId = query.chainId ?? c.get('chainId');
+        try {
+            const logo = await Timing.time(c, 'token_logo', () => fetchTokenLogo(c, { address, chainId }));
+            if (!logo)
+                return Response.error(c, {
+                    code: 'token_logo_not_found',
+                    message: 'Token logo not found',
+                    status: 404,
+                });
+            // `Cache.response` (above) stamps the `asset` Cache-Control / Vary;
+            // only the content type is set here.
+            return c.body(logo.body, 200, { 'Content-Type': logo.contentType });
+        }
+        catch (cause) {
+            // A token whose on-chain metadata read reverts (unregistered TIP-20)
+            // has no logo to serve — map it to the route's `404`, not a `502`,
+            // mirroring `getToken`. Only genuine upstream failures surface as 502.
+            if (isTokenNotFound(cause))
+                return Response.error(c, {
+                    code: 'token_logo_not_found',
+                    message: 'Token logo not found',
+                    status: 404,
+                });
+            return Response.upstream(c, cause);
+        }
+    })
+        .get('/:token/holders', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getTokenHolders.Params, {
+        code: 'token_invalid',
+        message: 'Invalid token address',
+    }), OpenApi.validate('query', schema.getTokenHolders.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Lists the accounts that hold a TIP-20 token, ordered from largest to smallest balance.',
+        operationId: 'getTokenHolders',
+        responses: OpenApi.responses({
+            errors: { 502: 'The upstream indexer could not serve this request.' },
+            success: {
+                description: 'A page of token holders.',
+                schema: schema.getTokenHolders.Response,
+            },
+        }),
+        summary: 'List token holders',
+        tags: ['Tokens'],
+    }), Cache.response({
+        cacheControl: Cache.policies.state,
+        name: 'tempo-api:tokens:v1',
+        key: (c) => Cache.urlKey(c, schema.getTokenHolders.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'token_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { token: address } = c.req.valid('param');
+        const query = c.req.valid('query');
+        try {
+            const chainId = query.chainId ?? c.get('chainId');
+            // Resolve the holder page and (opt-in) token metadata concurrently so
+            // the token lookup is hidden behind the slower holder aggregation
+            // rather than adding to it.
+            const includeToken = query.include.includes('token');
+            // `totalCount` is the holder total, read exactly from the
+            // pre-aggregated `token_holder_counts` view (not a capped scan), so
+            // `totalCountCapped` is always false. Best-effort: `getHolderCount` returns
+            // null when unavailable, in which case the count is omitted.
+            const includeTotalCount = query.include.includes('totalCount');
+            const [holders, token, holderCount] = await Promise.all([
+                getTokenHolders(c, {
+                    address,
+                    chainId,
+                    cursor: query.cursor,
+                    limit: query.limit,
+                    page: query.page,
+                }),
+                includeToken
+                    ? Timing.time(c, 'token', () => resolveToken(c, { address, chainId }))
+                    : Promise.resolve(undefined),
+                includeTotalCount
+                    ? Timing.time(c, 'token_holders_count', () => getHolderCount(c, { address, chainId }))
+                    : Promise.resolve(null),
+            ]);
+            // Embedded resources requested via `include` live under `meta`,
+            // separate from the holder page (`data`) and pagination fields. `meta`
+            // is omitted entirely when nothing response-wide was requested.
+            const meta = {
+                ...(token ? { token } : {}),
+                ...(holderCount !== null ? { totalCountCapped: false, totalCount: holderCount } : {}),
+            };
+            return c.json(Response.validated(schema.getTokenHolders.Response, {
+                ...holders,
+                meta: Object.keys(meta).length > 0 ? meta : undefined,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get('/:token/transactions', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getTokenTransactions.Params, {
+        code: 'token_invalid',
+        message: 'Invalid token address',
+    }), OpenApi.validate('query', schema.getTokenTransactions.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Lists transactions that interacted with this token contract.',
+        operationId: 'getTokenTransactions',
+        responses: OpenApi.responses({
+            errors: { 502: 'The upstream indexer could not serve this request.' },
+            success: {
+                description: 'A page of transactions involving this token contract.',
+                schema: schema.getTokenTransactions.Response,
+            },
+        }),
+        summary: 'List token transactions',
+        tags: ['Transactions'],
+    }), Cache.response({
+        cacheControl: Cache.policies.feed,
+        name: 'tempo-api:tokens:v1',
+        key: (c) => Cache.urlKey(c, schema.getTokenTransactions.Query),
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'token_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { token: address } = c.req.valid('param');
+        const query = c.req.valid('query');
+        // Cursor pages are anchored below the head and effectively immutable,
+        // so cache them aggressively; the head page keeps the `feed` default.
+        if (query.cursor !== undefined)
+            Cache.setPolicy(c, Cache.policies.immutable);
+        try {
+            const chainId = query.chainId ?? c.get('chainId');
+            // Resolve the transaction page and (opt-in) token metadata
+            // concurrently so the token lookup is hidden behind the
+            // transaction query rather than adding to it. The `feeToken`
+            // include flows through to `listTransactions` for per-row embeds;
+            // `token` is a root-level embed for the token being scoped to.
+            const includeToken = query.include.includes('token');
+            // `totalCount` is opt-in; count transactions touching this token
+            // (address-scoped to the contract) under the same filters as the
+            // page. Best-effort: a count failure omits the count from `meta`.
+            const countPromise = query.include.includes('totalCount')
+                ? Transactions.countTransactions(c, {
+                    address,
+                    chainId,
+                    feePayer: query.feePayer,
+                    feeToken: query.feeToken,
+                    fromBlock: query['blockNumber.from'],
+                    fromTimestamp: query['timestamp.from'],
+                    toBlock: query['blockNumber.to'],
+                    toTimestamp: query['timestamp.to'],
+                }).catch(() => undefined)
+                : undefined;
+            const [transactions, token, count] = await Promise.all([
+                Transactions.listTransactions(c, {
+                    address,
+                    chainId,
+                    cursor: query.cursor,
+                    feePayer: query.feePayer,
+                    feeToken: query.feeToken,
+                    fromBlock: query['blockNumber.from'],
+                    fromTimestamp: query['timestamp.from'],
+                    include: query.include.includes('feeToken') ? ['feeToken'] : [],
+                    limit: query.limit,
+                    order: query.order,
+                    page: query.page,
+                    toBlock: query['blockNumber.to'],
+                    toTimestamp: query['timestamp.to'],
+                }),
+                includeToken
+                    ? Timing.time(c, 'token', () => resolveToken(c, { address, chainId }))
+                    : Promise.resolve(undefined),
+                countPromise,
+            ]);
+            const meta = {
+                ...(token ? { token } : {}),
+                ...(count
+                    ? { totalCountCapped: count.totalCountCapped, totalCount: count.totalCount }
+                    : {}),
+            };
+            return c.json(Response.validated(schema.getTokenTransactions.Response, {
+                ...transactions,
+                meta: Object.keys(meta).length > 0 ? meta : undefined,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    });
+}
+async function getToken(c, options) {
+    return Timing.time(c, 'token', async () => {
+        try {
+            return c.json(await resolveToken(c, options), 200);
+        }
+        catch (cause) {
+            if (isTokenNotFound(cause))
+                return Response.error(c, {
+                    code: 'token_not_found',
+                    message: 'Token not found',
+                    status: 404,
+                });
+            return Response.upstream(c, cause);
+        }
+    });
+}
+/**
+ * Resolves the token metadata object. Throws on upstream failure / not found so
+ * callers can map the error (e.g. `getToken` → 404/502). Shared by `getToken`,
+ * the holder page's `include=token`, and the per-row address balance `token`.
+ *
+ * Page-level callers that enrich many tokens at once should pre-fetch
+ * `createdAtByAddress` (one `IN (...)` TIDX query for the whole page) and pass
+ * it in to avoid N separate `getTokenCreatedAtByAddress` round-trips. The same
+ * applies to the verified-token `snapshot` and the other batch enrichments
+ * (`createdByAddress`, `holderCountByAddress`, `transferStatsByAddress`).
+ */
+export async function resolveToken(c, options) {
+    const { chainId } = options;
+    // Normalize once so address and symbol lookups share cache entries and
+    // verified-data comparisons do not depend on caller casing.
+    const address = Schema.Address.parse(options.address.toLowerCase());
+    // `createdAt`, the `TokenCreated` extras, holder counts, and transfer stats
+    // require an expensive indexer round-trip, so each only runs when the caller
+    // opts in via `?include=...`. Page-level callers can still pre-fetch the
+    // batch maps for the whole page and pass them in regardless of `include`.
+    const includeAdmin = options.include?.includes('admin') ?? false;
+    const includeCreatedAt = options.include?.includes('createdAt') ?? false;
+    const includeHolderCount = options.include?.includes('holderCount') ?? false;
+    const includeQuoteToken = options.include?.includes('quoteToken') ?? false;
+    const includeTransferStats = options.include?.includes('transferStats') ?? false;
+    const [metadata, snapshot, createdAtByAddress, createdByAddress, logo, holderCount, stats] = await Promise.all([
+        Timing.time(c, 'token_metadata', () => getTokenMetadata(c, { address, chainId })),
+        options.snapshot ?? VerifiedTokens.snapshot(c, chainId),
+        options.createdAtByAddress ??
+            (includeCreatedAt
+                ? Timing.time(c, 'token_created', () => getTokenCreatedAtByAddress(c, { addresses: [address], chainId }))
+                : Promise.resolve({})),
+        // `admin` and `quoteToken` ride one `TokenCreated` fetch: either include
+        // triggers it, and each field still surfaces independently below.
+        options.createdByAddress ??
+            (includeAdmin || includeQuoteToken
+                ? Timing.time(c, 'token_created_extras', () => getTokenCreatedByAddress(c, { addresses: [address], chainId }))
+                : Promise.resolve({})),
+        Timing.time(c, 'token_logo', () => getTokenLogo(c, { address, chainId })),
+        options.holderCountByAddress
+            ? Promise.resolve(options.holderCountByAddress[address] ?? null)
+            : includeHolderCount
+                ? Timing.time(c, 'token_holders', () => getHolderCount(c, { address, chainId }))
+                : Promise.resolve(undefined),
+        options.transferStatsByAddress
+            ? Promise.resolve(options.transferStatsByAddress[address] ?? null)
+            : includeTransferStats
+                ? Timing.time(c, 'token_transfers', () => getTransferStats(c, { address, chainId }))
+                : Promise.resolve(undefined),
+    ]);
+    const created = createdByAddress[address];
+    return Response.validated(schema.getToken.Response, {
+        address,
+        // Only the explicitly requested `TokenCreated` extra surfaces: a caller
+        // asking for `quoteToken` alone must not receive `admin`, and vice versa.
+        admin: includeAdmin ? created?.admin : undefined,
+        currency: metadata.currency,
+        createdAt: createdAtByAddress[address],
+        decimals: metadata.decimals,
+        holderCount: holderCount ?? undefined,
+        id: address,
+        // Prefer the curated R2 icon, then the verified entry's curated `logoUri`,
+        // falling back to the precompile's on-chain `logoURI` when present.
+        logoUri: logo ?? snapshot.byAddress.get(address)?.logoUri ?? metadata.logoUri,
+        name: metadata.name,
+        quoteToken: includeQuoteToken ? created?.quoteToken : undefined,
+        symbol: metadata.symbol,
+        totalSupply: metadata.totalSupply,
+        transferStats: stats ?? undefined,
+        verified: snapshot.byAddress.has(address),
+    });
+}
+/**
+ * Resolves a token's on-chain metadata (`name`/`symbol`/`decimals`/`currency`/
+ * `totalSupply`) via a single `token.getMetadata` RPC, memoized under the shared
+ * `token:v1:{chainId}:{address}:metadata` key. Exported so feed enrichers (e.g.
+ * `activities`) reuse the same cache entry as the token resource rather than
+ * fetching metadata through a parallel path.
+ */
+export function getTokenMetadata(c, options) {
+    const { address, chainId } = options;
+    const getClient = c.get('getClient');
+    const store = c.get('store');
+    return Store.memoize(async () => {
+        const fresh = await getClient(chainId).token.getMetadata({ token: address });
+        return {
+            currency: fresh.currency,
+            decimals: fresh.decimals,
+            logoUri: fresh.logoURI || undefined,
+            name: fresh.name,
+            symbol: fresh.symbol,
+            totalSupply: fresh.totalSupply.toString(),
+        };
+    }, { key: `token:v1:${chainId}:${address}:metadata`, store, ttl: Ttl.minutes(1) });
+}
+/**
+ * Resolves a token's curated R2 icon URI, memoized per `(chainId, address)`
+ * so page enrichers (balances, holders, transfers `include=token`) don't
+ * re-fetch the asset per row on every request. Misses are memoized as `null`
+ * too — most tokens have no curated icon, and the negative lookup is exactly
+ * what page enrichment would otherwise repeat N times per page.
+ *
+ * The public URI embeds the request origin, so the origin is part of the
+ * cache key; cardinality stays bounded by the number of public hostnames.
+ */
+export async function getTokenLogo(c, options) {
+    const { address, chainId } = options;
+    const getAsset = c.get('getAsset');
+    const store = c.get('store');
+    const origin = new URL(c.req.url).origin;
+    const uri = await Store.memoize(async () => (await getAsset(chainId, Path.join('icons', address)))?.uri ?? null, { key: `token:v1:${chainId}:${address}:logo:${origin}`, store, ttl: Ttl.minutes(5) });
+    return uri ?? undefined;
+}
+/**
+ * Resolves the raw logo image bytes for a token, in priority order:
+ *
+ * 1. The curated R2 icon (`<chainId>/icons/<address>`), our override surface.
+ * 2. The token's on-chain TIP-20 `logoURI` (fetched and proxied), so tokens
+ *    that publish a logo on-chain still serve through the API even without a
+ *    curated icon.
+ *
+ * Returns `undefined` when neither source yields an image, so the route can
+ * map that to a `404`. The curated R2 icon is trusted (we control it); the
+ * on-chain `logoURI` is deployer-controlled, so it is fetched through the
+ * hardened {@link fetchExternalLogo} (scheme/host allowlist, timeout, size cap,
+ * raster-only content type) to bound the SSRF / resource-exhaustion surface.
+ */
+async function fetchTokenLogo(c, options) {
+    const { address, chainId } = options;
+    // Curated R2 icon first: our override for tokens with no (or an undesirable)
+    // on-chain logo. Trusted content, served verbatim.
+    const getAsset = c.get('getAsset');
+    const asset = await getAsset(chainId, Path.join('icons', address));
+    if (asset)
+        return {
+            body: await asset.response.arrayBuffer(),
+            contentType: asset.response.headers.get('content-type') ?? 'application/octet-stream',
+        };
+    // Fall back to the on-chain TIP-20 `logoURI` (memoized with the rest of the
+    // token metadata). Deployer-controlled, so proxy it defensively.
+    const { logoUri } = await getTokenMetadata(c, { address, chainId });
+    if (!logoUri)
+        return undefined;
+    return fetchExternalLogo(logoUri);
+}
+// Cap on proxied logo bytes (1 MiB). A logo larger than this is almost
+// certainly not a real icon; the cap bounds memory for a hostile upstream.
+const maxLogoBytes = 1_000_000;
+/**
+ * Fetches a deployer-controlled `logoURI` and returns the image bytes, or
+ * `undefined` when the URI is unsafe/unusable. Hardening, since the URI is
+ * attacker-controlled and proxied through our origin:
+ *
+ * - Scheme allowlist (`http`/`https`/`data`); `ipfs://` etc. are unresolvable.
+ * - Blocks loopback/private/link-local hosts to limit SSRF (defense in depth —
+ *   Workers `fetch` is not routable to internal infra, but cheap to enforce).
+ * - 3s timeout and a {@link maxLogoBytes} streamed size cap bound resource use.
+ * - Raster-only content type: arbitrary on-chain `image/svg+xml` is rejected
+ *   (script-bearing SVG served same-origin is an XSS vector); curated R2 SVGs
+ *   are trusted and handled separately.
+ */
+async function fetchExternalLogo(uri) {
+    const url = (() => {
+        try {
+            return new URL(uri);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (!url)
+        return undefined;
+    if (url.protocol !== 'http:' && url.protocol !== 'https:' && url.protocol !== 'data:')
+        return undefined;
+    if ((url.protocol === 'http:' || url.protocol === 'https:') && isBlockedHost(url.hostname))
+        return undefined;
+    const response = await fetch(url, {
+        headers: { accept: 'image/png,image/jpeg,image/webp,image/gif,image/avif,image/*;q=0.8' },
+        redirect: 'manual',
+        signal: AbortSignal.timeout(3_000),
+    }).catch(() => undefined);
+    // A non-2xx (incl. an opaque 3xx from `redirect: 'manual'`, so a deployer
+    // cannot bounce us to an internal host) is treated as no logo.
+    if (!response || !response.ok)
+        return undefined;
+    const contentType = response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
+    if (!contentType || !contentType.startsWith('image/') || contentType === 'image/svg+xml')
+        return undefined;
+    // Reject early when the upstream advertises an oversized body.
+    const length = Number(response.headers.get('content-length'));
+    if (Number.isFinite(length) && length > maxLogoBytes)
+        return undefined;
+    const body = await readBodyWithLimit(response.body, maxLogoBytes);
+    if (!body)
+        return undefined;
+    return { body, contentType };
+}
+// Reads a stream into an `ArrayBuffer`, returning `undefined` if it exceeds
+// `limit` (so an upstream without `Content-Length` cannot stream us unbounded
+// bytes).
+async function readBodyWithLimit(body, limit) {
+    if (!body)
+        return undefined;
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > limit)
+                return undefined;
+            chunks.push(value);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const buffer = new ArrayBuffer(total);
+    const out = new Uint8Array(buffer);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return buffer;
+}
+// Blocks hosts that resolve to loopback/private/link-local space, including the
+// cloud metadata IP. Hostnames that are not literal IPs are allowed (we cannot
+// resolve DNS here); the `redirect: 'manual'` policy in `fetchExternalLogo`
+// prevents a public host from bouncing us into private space.
+function isBlockedHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (host === '' || host === 'localhost' || host.endsWith('.localhost'))
+        return true;
+    if (host === '::1' || host === '::')
+        return true;
+    if (host.startsWith('fc') || host.startsWith('fd') || host.startsWith('fe80:'))
+        return true;
+    const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (ipv4) {
+        const a = Number(ipv4[1]);
+        const b = Number(ipv4[2]);
+        if (a === 0 || a === 10 || a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 100 && b >= 64 && b <= 127)
+            return true;
+    }
+    return false;
+}
+async function getTokenLogosByAddress(c, options) {
+    const { addresses, chainId } = options;
+    // Curated R2 icons take precedence (our override for tokens that have no
+    // on-chain logo); resolve them all in parallel.
+    const assets = await Promise.all(addresses.map(async (address) => [address, await getTokenLogo(c, { address, chainId })]));
+    const logos = {};
+    let missing = [];
+    for (const [address, uri] of assets)
+        if (uri)
+            logos[address] = uri;
+        else
+            missing.push(address);
+    if (missing.length === 0)
+        return logos;
+    // Next, the verified entry's curated `logoUri` (set via the admin API). The
+    // snapshot is primed per isolate, so this is an in-memory map read.
+    const snapshot = await VerifiedTokens.snapshot(c, chainId);
+    missing = missing.filter((address) => {
+        const uri = snapshot.byAddress.get(address)?.logoUri;
+        if (uri)
+            logos[address] = uri;
+        return !uri;
+    });
+    if (missing.length === 0)
+        return logos;
+    // Fall back to the on-chain `logoURI` for tokens without a curated icon.
+    // Reuse `getTokenMetadata` so the lookup shares the same memoized cache as the
+    // single-token endpoint; the per-token reads batch into a deployless
+    // multicall. Failures degrade to no logo rather than failing the page.
+    const onchain = await Promise.all(missing.map(async (address) => {
+        try {
+            return [address, (await getTokenMetadata(c, { address, chainId })).logoUri];
+        }
+        catch {
+            return [address, undefined];
+        }
+    }));
+    for (const [address, uri] of onchain)
+        if (uri)
+            logos[address] = uri;
+    return logos;
+}
+function getHolderCount(c, options) {
+    const { address, chainId } = options;
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(chainId);
+    return Store.memoize(async () => {
+        try {
+            // Holder count for the token. Read the pre-aggregated
+            // `token_holder_counts` materialized view (one row per `token`, refreshed
+            // every ~15 min from the positive-balance `token_balances_snapshot`), so
+            // this is a single point lookup on the view's `(token)` sort key rather
+            // than an aggregation over the holder set. `address` is already lowercase
+            // (Schema.Address), matching how the indexer stores the token column. The
+            // inline query is cast to `string` so TIDX treats it as a dynamic
+            // ClickHouse query that needs no event signature for the
+            // `token_holder_counts` table.
+            const result = await tidx.fetch({
+                chainId,
+                engine: 'clickhouse',
+                query: `
+            SELECT holder_count
+            FROM token_holder_counts
+            WHERE token = '${address}'
+          `,
+            });
+            // Persist `null` (not `undefined`) so "no holder data" survives the
+            // cache round-trip without being mistaken for a miss.
+            return Value.toNumber(result.rows[0]?.['holder_count']) ?? null;
+        }
+        catch {
+            // Degrade gracefully when holder data is unavailable (e.g. the indexer
+            // lacks the ClickHouse view, or the request is rate limited) so token
+            // metadata still resolves.
+            return null;
+        }
+    }, { key: `token:v1:${chainId}:${address}:holders`, store, ttl: Ttl.minutes(5) });
+}
+async function getHolderCountsByAddress(c, options) {
+    const addresses = Array.from(new Set(options.addresses.map((address) => address.toLowerCase())))
+        .sort()
+        .map((address) => Schema.Address.parse(address));
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(options.chainId);
+    if (addresses.length === 0)
+        return {};
+    return Store.memoize(async () => {
+        try {
+            // Batched form of `getHolderCount` for a page of tokens: one multi-key
+            // point read of the pre-aggregated `token_holder_counts` materialized
+            // view instead of a `GROUP BY` aggregation over every requested token's
+            // holder set in `token_balances_snapshot` (which, for high-cardinality
+            // tokens, reads millions of rows per group).
+            const result = await tidx.fetch({
+                chainId: options.chainId,
+                engine: 'clickhouse',
+                query: `
+            SELECT token, holder_count
+            FROM token_holder_counts
+            WHERE token IN (${addresses.map((address) => `'${address}'`).join(', ')})
+          `,
+            });
+            const holderCountByAddress = {};
+            for (const row of result.rows) {
+                const address = Schema.Address.safeParse(row['token']);
+                const holderCount = Value.toNumber(row['holder_count']);
+                if (address.success && holderCount !== undefined)
+                    holderCountByAddress[address.data] = holderCount;
+            }
+            return holderCountByAddress;
+        }
+        catch {
+            // Degrade gracefully so the token page still resolves without counts.
+            return {};
+        }
+    }, {
+        key: `token:v1:${options.chainId}:holders:${addresses.join(',')}`,
+        store,
+        ttl: Ttl.minutes(5),
+    });
+}
+function getTransferStats(c, options) {
+    const { address, chainId } = options;
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(chainId);
+    return Store.memoize(async () => {
+        try {
+            // Lifetime `Transfer` statistics for the token, aggregated over the
+            // raw `logs` event stream by emitting contract. The inline query is
+            // cast to `string` so TIDX treats it as a dynamic ClickHouse query
+            // that needs no event signature for the `logs` table.
+            const result = await tidx.fetch({
+                chainId,
+                engine: 'clickhouse',
+                query: `
+            SELECT count() AS transfer_count, min(block_timestamp) AS first_at, max(block_timestamp) AS last_at
+            FROM logs
+            WHERE address = '${address}' AND selector = '${transferTopic}'
+          `,
+            });
+            const row = result.rows[0];
+            // Persist `null` (not `undefined`) so "no transfer data" survives the
+            // cache round-trip without being mistaken for a miss.
+            const count = Value.toNumber(row?.['transfer_count']);
+            if (count === undefined)
+                return null;
+            // A zero count comes back with ClickHouse epoch-default (1970)
+            // `min`/`max` aggregates; report explicit nulls instead.
+            if (count === 0)
+                return { count: 0, firstAt: null, lastAt: null };
+            // ClickHouse formats timestamps as naive-UTC `YYYY-MM-DD HH:MM:SS.sss`;
+            // `Value.toIsoDateTime` normalizes them to strict ISO 8601 UTC.
+            return {
+                count,
+                firstAt: Value.toIsoDateTime(row?.['first_at']) ?? null,
+                lastAt: Value.toIsoDateTime(row?.['last_at']) ?? null,
+            };
+        }
+        catch {
+            // Degrade gracefully when transfer data is unavailable (e.g. the
+            // indexer cannot answer the aggregation, or the request is rate
+            // limited) so token metadata still resolves.
+            return null;
+        }
+    }, { key: `token:v1:${chainId}:${address}:transfer_stats`, store, ttl: Ttl.minutes(5) });
+}
+async function getTransferStatsByAddress(c, options) {
+    const addresses = Array.from(new Set(options.addresses.map((address) => address.toLowerCase())))
+        .sort()
+        .map((address) => Schema.Address.parse(address));
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(options.chainId);
+    if (addresses.length === 0)
+        return {};
+    return Store.memoize(async () => {
+        try {
+            // Batched form of `getTransferStats` for a page of tokens: one grouped
+            // aggregation over the raw `logs` stream instead of N per-token scans.
+            // Tokens with no `Transfer` events emit no group and are omitted.
+            const result = await tidx.fetch({
+                chainId: options.chainId,
+                engine: 'clickhouse',
+                query: `
+            SELECT address, count() AS transfer_count, min(block_timestamp) AS first_at, max(block_timestamp) AS last_at
+            FROM logs
+            WHERE selector = '${transferTopic}' AND address IN (${addresses.map((address) => `'${address}'`).join(', ')})
+            GROUP BY address
+          `,
+            });
+            const statsByAddress = {};
+            for (const row of result.rows) {
+                const address = Schema.Address.safeParse(row['address']);
+                const count = Value.toNumber(row['transfer_count']);
+                if (!address.success || count === undefined)
+                    continue;
+                statsByAddress[address.data] = {
+                    count,
+                    firstAt: Value.toIsoDateTime(row['first_at']) ?? null,
+                    lastAt: Value.toIsoDateTime(row['last_at']) ?? null,
+                };
+            }
+            return statsByAddress;
+        }
+        catch {
+            // Degrade gracefully so the token page still resolves without stats.
+            return {};
+        }
+    }, {
+        key: `token:v1:${options.chainId}:transfer_stats:${addresses.join(',')}`,
+        store,
+        ttl: Ttl.minutes(5),
+    });
+}
+function getTokenHolders(c, options) {
+    const { address, chainId, limit } = options;
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(chainId);
+    // Keyset pagination on `(balance, holder)`: balance is descending and `holder`
+    // is a stable tiebreaker for the many holders sharing a balance. A malformed
+    // cursor falls back to the head page. Note: because `balance` is mutable, this
+    // is best-effort across balance changes (the inherent limit of ranking feeds).
+    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;
+    return Timing.time(c, 'token_holders', () => Store.memoize(async () => {
+        // A holder is an address with a positive balance of the token. Read the
+        // pre-aggregated, `FINAL`-correct `token_balances_snapshot` materialized
+        // view (one row per `(token, holder, balance)`, ordered by
+        // `(token, balance)`), so this is a primary-key read that stays under the
+        // indexer's ClickHouse budget even for high-cardinality tokens (e.g.
+        // PathUSD). 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
+        // `token_balances_snapshot` table.
+        //
+        // Let upstream failures propagate: unlike `getHolderCount` (optional
+        // enrichment that degrades to `null`), this is a dedicated endpoint, so a
+        // failure should surface as the declared `502` rather than masquerade as
+        // a token with zero holders.
+        const keyset = cursor !== undefined
+            ? ` AND ${Cursor.keyset([
+                { literal: Cursor.literal(cursor[0], 'uint'), name: 'balance', order: 'desc' },
+                { literal: Cursor.literal(cursor[1], 'address'), name: 'holder', order: 'asc' },
+            ])}`
+            : '';
+        // `balance` is UInt256; SELECT it as a string so values > 2^53 survive
+        // JSON without precision loss. The keyset cursor encodes the row's
+        // exact balance, so any rounding would re-include the cursor row on
+        // the next page. Alias is `balance_str` (not `balance`) because TIDX
+        // rejects expression aliases that shadow the source column (422).
+        const result = await tidx.fetch({
+            chainId,
+            engine: 'clickhouse',
+            query: `
+            SELECT holder, toString(balance) AS balance_str
+            FROM token_balances_snapshot
+            WHERE token = '${address}' AND balance > 0${keyset}
+            ORDER BY balance DESC, holder ASC
+            LIMIT ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
+          `,
+        });
+        // The next page anchors below the last fetched row's `(balance, holder)`.
+        const page = Cursor.paginate({
+            rows: result.rows,
+            limit,
+            key: (row) => {
+                const balance = Value.toIntegerString(row['balance_str']);
+                const holder = Schema.Address.safeParse(row['holder']);
+                return balance !== undefined && holder.success ? [balance, holder.data] : undefined;
+            },
+        });
+        const data = [];
+        for (const row of page.rows) {
+            const holder = Schema.Address.safeParse(row['holder']);
+            const balance = Value.toIntegerString(row['balance_str']);
+            if (holder.success && balance !== undefined)
+                data.push({ address: holder.data, balance, id: holder.data });
+        }
+        return { data, nextCursor: page.nextCursor };
+    }, {
+        key: `token:v1:${chainId}:${address}:holders:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : offset !== undefined ? `page:${options.page}` : 'head'}:${limit}`,
+        store,
+        ttl: Ttl.minutes(1),
+    }));
+}
+/**
+ * Resolves `createdAt` for many tokens in one TIDX round-trip while keeping
+ * cache entries keyed per-address, so two pages sharing N-1 of N tokens
+ * naturally reuse most of the cache. We:
+ *
+ *   1. Look up each requested address in the per-address cache.
+ *   2. Issue a single `IN (…)` query for the misses only.
+ *   3. Write each freshly-resolved address back to the per-address cache.
+ *
+ * Token creation timestamps are immutable, so successful entries are cached
+ * for a day. Addresses the indexer answered but did not resolve (no
+ * `TokenCreated` row — e.g. genesis tokens) are negative-cached briefly so
+ * they do not re-run the `logs` decode CTE on every request; the short TTL
+ * covers tokens that are simply not indexed yet.
+ */
+export async function getTokenCreatedAtByAddress(c, options) {
+    const addresses = Array.from(new Set(options.addresses.map((address) => address.toLowerCase())))
+        .sort()
+        .map((address) => Schema.Address.parse(address));
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(options.chainId);
+    if (addresses.length === 0)
+        return {};
+    const key = (address) => `token:v1:${options.chainId}:${address}:created_at`;
+    const cached = await Promise.all(addresses.map((address) => store.get(key(address))));
+    const createdAtByAddress = {};
+    const misses = [];
+    for (const [index, address] of addresses.entries()) {
+        const hit = cached[index];
+        // A negative entry means "known to have no TokenCreated row" — resolved
+        // as absent, so it neither joins the result nor re-queries.
+        if (hit === noCreatedAt)
+            continue;
+        if (hit)
+            createdAtByAddress[address] = hit;
+        else
+            misses.push(address);
+    }
+    if (misses.length === 0)
+        return createdAtByAddress;
+    try {
+        const result = await tidx.fetch({
+            chainId: options.chainId,
+            query: `
+        SELECT token, block_timestamp
+        FROM tokencreated
+        WHERE token IN (${misses.map((address) => `'${address}'`).join(', ')})
+      `,
+            signatures: [tokenCreatedSignature],
+        });
+        const writes = [];
+        for (const row of result.rows) {
+            const address = Schema.Address.safeParse(row.token);
+            const createdAt = Value.toIsoDateTime(row.block_timestamp);
+            if (!address.success || !createdAt)
+                continue;
+            createdAtByAddress[address.data] = createdAt;
+            writes.push(store.put(key(address.data), createdAt, { ttl: Ttl.days(1) }));
+        }
+        // Negative-cache the addresses this (successful) query did not resolve, so
+        // a token with no `TokenCreated` row doesn't re-run the decode CTE on
+        // every request.
+        for (const address of misses)
+            if (!(address in createdAtByAddress))
+                writes.push(store.put(key(address), noCreatedAt, { ttl: Ttl.minutes(1) }));
+        // Persist new entries best-effort; do not block the response on cache writes.
+        void Promise.all(writes).catch(() => { });
+    }
+    catch {
+        // Creation timestamps improve resource completeness, but token metadata
+        // should remain available when the indexer is temporarily unable to
+        // answer this auxiliary query.
+    }
+    return createdAtByAddress;
+}
+/**
+ * Negative-cache sentinel for {@link getTokenCreatedAtByAddress}: stored under
+ * an address's `created_at` key when the indexer has no `TokenCreated` row
+ * for it, distinguishable from any real ISO timestamp.
+ */
+const noCreatedAt = 'none';
+/**
+ * Resolves the `TokenCreated` extras (`admin`/`quoteToken`, plus the event's
+ * `createdAt` timestamp) for many tokens in one TIDX round-trip while keeping
+ * cache entries keyed per-address, mirroring {@link getTokenCreatedAtByAddress}.
+ * The deployed indexer's `tokencreated` event CTE cannot serve the
+ * `quoteToken`/`admin` columns (selecting them returns `db error`), so this
+ * reads the raw `logs` table by topic0 and ABI-decodes the non-indexed event
+ * data instead.
+ *
+ * Token creation payloads are immutable, so successful entries are cached for
+ * a day. Addresses the indexer answered but did not resolve (no `TokenCreated`
+ * log — e.g. genesis tokens) are negative-cached briefly so they do not
+ * re-scan `logs` on every request; the short TTL covers tokens that are simply
+ * not indexed yet.
+ */
+async function getTokenCreatedByAddress(c, options) {
+    const addresses = Array.from(new Set(options.addresses.map((address) => address.toLowerCase())))
+        .sort()
+        .map((address) => Schema.Address.parse(address));
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(options.chainId);
+    if (addresses.length === 0)
+        return {};
+    const key = (address) => `token:v2:${options.chainId}:${address}:created`;
+    const cached = await Promise.all(addresses.map((address) => store.get(key(address))));
+    const createdByAddress = {};
+    const misses = [];
+    for (const [index, address] of addresses.entries()) {
+        const hit = cached[index];
+        // A negative entry means "known to have no TokenCreated log" — resolved
+        // as absent, so it neither joins the result nor re-queries.
+        if (hit === noCreated)
+            continue;
+        if (hit)
+            createdByAddress[address] = JSON.parse(hit);
+        else
+            misses.push(address);
+    }
+    if (misses.length === 0)
+        return createdByAddress;
+    try {
+        // The raw `logs` table stores topic0 in the `selector` column; `topic1` is
+        // the indexed `token` address left-padded to a 32-byte topic. The inline
+        // query is cast to `string` so TIDX treats it as a dynamic query that
+        // needs no event signature for the `logs` table.
+        const result = await tidx.fetch({
+            chainId: options.chainId,
+            query: `
+        SELECT topic1, data, block_timestamp
+        FROM logs
+        WHERE selector = '${tokenCreatedTopic}'
+          AND topic1 IN (${misses.map((address) => `'0x${'0'.repeat(24)}${address.slice(2)}'`).join(', ')})
+      `,
+        });
+        const writes = [];
+        for (const row of result.rows) {
+            const topic = Value.toText(row['topic1']);
+            const data = Schema.Hex.safeParse(row['data']);
+            const createdAt = Value.toIsoDateTime(row['block_timestamp']);
+            if (!topic || !data.success || !createdAt)
+                continue;
+            // `topic1` left-pads the address to 32 bytes; strip the padding.
+            const address = Schema.Address.safeParse(`0x${topic.slice(-40)}`);
+            if (!address.success)
+                continue;
+            const decoded = (() => {
+                try {
+                    return AbiParameters.decode(tokenCreatedData, data.data);
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            if (!decoded)
+                continue;
+            const quoteToken = Schema.Address.safeParse(decoded[3]);
+            const admin = Schema.Address.safeParse(decoded[4]);
+            if (!quoteToken.success || !admin.success)
+                continue;
+            const created = { admin: admin.data, createdAt, quoteToken: quoteToken.data };
+            createdByAddress[address.data] = created;
+            writes.push(store.put(key(address.data), JSON.stringify(created), { ttl: Ttl.days(1) }));
+        }
+        // Negative-cache the addresses this (successful) query did not resolve, so
+        // a token with no `TokenCreated` log doesn't re-scan `logs` on every
+        // request.
+        for (const address of misses)
+            if (!(address in createdByAddress))
+                writes.push(store.put(key(address), noCreated, { ttl: Ttl.minutes(1) }));
+        // Persist new entries best-effort; do not block the response on cache writes.
+        void Promise.all(writes).catch(() => { });
+    }
+    catch {
+        // `TokenCreated` extras improve resource completeness, but token metadata
+        // should remain available when the indexer is temporarily unable to
+        // answer this auxiliary query.
+    }
+    return createdByAddress;
+}
+/**
+ * Negative-cache sentinel for {@link getTokenCreatedByAddress}: stored under
+ * an address's `created` key when the indexer has no `TokenCreated` log for
+ * it, distinguishable from any real JSON payload.
+ */
+const noCreated = 'none';
+async function getTokens(c, options) {
+    const store = c.get('store');
+    const tidx = c.get('getTidx')(options.chainId);
+    const snapshot = await VerifiedTokens.snapshot(c, options.chainId);
+    // `verified=true` is served from the curated static list — TIDX's event-CTE
+    // planner rejects `WHERE token IN (…)` against `tokencreated` when combined
+    // with `ORDER BY` / `LIMIT`, so we paginate the in-memory list positionally
+    // instead (see the branch below). The response keeps the same shape as the
+    // unfiltered page: `currency` narrows the static rows, the `include`
+    // enrichments run against the page's addresses, and `cursor`/`page`/`limit`/
+    // `order` slice the list.
+    // `createdAt` is an opt-in `include`: skip the indexer round-trip unless the
+    // caller asked for it, keeping the base page fast.
+    const wantCreatedAt = options.include?.includes('createdAt') ?? false;
+    // `admin` and `quoteToken` both decode from the raw `TokenCreated` log, so
+    // one batched fetch serves either; each field still only surfaces when its
+    // own include was requested. Holder counts and transfer stats are likewise
+    // opt-in batched enrichments.
+    const wantAdmin = options.include?.includes('admin') ?? false;
+    const wantQuoteToken = options.include?.includes('quoteToken') ?? false;
+    const wantCreatedExtras = wantAdmin || wantQuoteToken;
+    const wantHolderCount = options.include?.includes('holderCount') ?? false;
+    const wantTransferStats = options.include?.includes('transferStats') ?? false;
+    // An explicit `addresses=` batch lookup takes precedence over both the
+    // verified-list branch and the indexed listing: the caller already named the
+    // exact tokens, so `cursor`/`order` are inapplicable and the page is the
+    // resolved set in input order. Batch enrichments are pre-fetched here (one
+    // TIDX query per include) and passed through `resolveToken`, mirroring the
+    // verified branch, so the per-address fan-out costs RPC metadata only.
+    if (options.addresses !== undefined) {
+        const addresses = options.addresses;
+        const [createdAtByAddress, createdByAddress, holderCountByAddress, transferStatsByAddress] = await Promise.all([
+            wantCreatedAt && addresses.length > 0
+                ? Timing.time(c, 'tokens_created_at', () => getTokenCreatedAtByAddress(c, { addresses, chainId: options.chainId }))
+                : Promise.resolve({}),
+            wantCreatedExtras && addresses.length > 0
+                ? Timing.time(c, 'tokens_created_extras', () => getTokenCreatedByAddress(c, { addresses, chainId: options.chainId }))
+                : Promise.resolve({}),
+            wantHolderCount && addresses.length > 0
+                ? Timing.time(c, 'tokens_holders', () => getHolderCountsByAddress(c, { addresses, chainId: options.chainId }))
+                : Promise.resolve(undefined),
+            wantTransferStats && addresses.length > 0
+                ? Timing.time(c, 'tokens_transfers', () => getTransferStatsByAddress(c, { addresses, chainId: options.chainId }))
+                : Promise.resolve(undefined),
+        ]);
+        // Unresolvable addresses (not a TIP-20 token, upstream failure) drop out
+        // of the page rather than failing it; input order is preserved.
+        const resolved = await Promise.all(addresses.map((address) => resolveToken(c, {
+            address,
+            chainId: options.chainId,
+            createdAtByAddress,
+            createdByAddress,
+            holderCountByAddress,
+            include: options.include,
+            snapshot,
+            transferStatsByAddress,
+        }).catch(() => undefined)));
+        // `currency` and `verified=true` act as post-filters on the resolved set:
+        // the caller addressed specific tokens, so non-matching rows drop out
+        // instead of erroring.
+        const currency = options.currency?.toLowerCase();
+        return {
+            data: resolved.filter((token) => token !== undefined &&
+                (currency === undefined || token.currency.toLowerCase() === currency) &&
+                (options.verified !== true || token.verified)),
+            nextCursor: null,
+        };
+    }
+    if (options.verified) {
+        const all = options.currency
+            ? (snapshot.byCurrency.get(options.currency.toLowerCase()) ?? [])
+            : snapshot.list;
+        // The curated list is static and fully in memory, so paginate it
+        // positionally: the cursor encodes the next offset, `page` slices by index,
+        // and `order=asc` reverses the canonical (`desc`) order. Only the page slice
+        // is enriched below, so a request costs at most `limit` logo/stat lookups
+        // instead of one per verified token.
+        const ordered = options.order === 'asc' ? [...all].reverse() : all;
+        const start = Cursor.decode(options.cursor ?? '', ['int'])?.[0] ??
+            (options.page !== undefined && options.page > 1 ? (options.page - 1) * options.limit : 0);
+        const rows = ordered.slice(start, start + options.limit);
+        const nextCursor = ordered.length > start + options.limit ? Cursor.encode([start + options.limit]) : null;
+        // `createdAt`, the `TokenCreated` extras, holder counts, and transfer
+        // stats come from TIDX. We fetch them in parallel so the verified page
+        // costs at most one round-trip per enrichment — and each is only fetched
+        // when opted into via `include`.
+        const addresses = rows.map((token) => token.address);
+        const [createdAtByAddress, createdByAddress, holderCounts, logoByAddress, statsByAddress] = await Promise.all([
+            wantCreatedAt && rows.length > 0
+                ? Timing.time(c, 'tokens_created_at', () => getTokenCreatedAtByAddress(c, { addresses, chainId: options.chainId }))
+                : Promise.resolve({}),
+            wantCreatedExtras && rows.length > 0
+                ? Timing.time(c, 'tokens_created_extras', () => getTokenCreatedByAddress(c, { addresses, chainId: options.chainId }))
+                : Promise.resolve({}),
+            wantHolderCount && rows.length > 0
+                ? Timing.time(c, 'tokens_holders', () => getHolderCountsByAddress(c, { addresses, chainId: options.chainId }))
+                : Promise.resolve(undefined),
+            // Logos always ride along on the verified page: the curated set is small
+            // and the page is cached. Curated R2 icons take precedence, falling back
+            // to the on-chain `logoURI` for any token without one.
+            Timing.time(c, 'tokens_logos', () => getTokenLogosByAddress(c, { addresses, chainId: options.chainId })),
+            wantTransferStats && rows.length > 0
+                ? Timing.time(c, 'tokens_transfers', () => getTransferStatsByAddress(c, { addresses, chainId: options.chainId }))
+                : Promise.resolve(undefined),
+        ]);
+        return {
+            data: rows.map((token) => {
+                const created = createdByAddress[token.address];
+                return {
+                    address: token.address,
+                    admin: wantAdmin ? created?.admin : undefined,
+                    currency: token.currency,
+                    createdAt: createdAtByAddress[token.address],
+                    decimals: token.decimals,
+                    holderCount: holderCounts?.[token.address],
+                    id: token.address,
+                    logoUri: logoByAddress[token.address],
+                    name: token.name,
+                    quoteToken: wantQuoteToken ? created?.quoteToken : undefined,
+                    symbol: token.symbol,
+                    transferStats: statsByAddress?.[token.address],
+                    verified: true,
+                };
+            }),
+            nextCursor,
+        };
+    }
+    const limit = options.limit;
+    const order = options.order;
+    const direction = order === 'asc' ? 'ASC' : 'DESC';
+    // Keyset pagination on `(block_num, log_idx)`: anchor the page below the
+    // previous row's creation position instead of a numeric offset, so newly
+    // created tokens can't shift items across pages. 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;
+    function getIndexedTokens() {
+        return Store.memoize(async () => {
+            // TIDX's event-CTE planner refuses `WHERE token = X` / `token IN (…)`
+            // on `tokencreated` when combined with `ORDER BY` / `LIMIT` (column
+            // equality on event params errors with `db error`). Supported filters
+            // here are real columns like `block_num` and `currency`, plus the
+            // cursor keyset; verified-only mode is handled above by serving the
+            // curated static list directly.
+            const filters = [];
+            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 },
+                ]));
+            if (options.currency !== undefined)
+                filters.push(`LOWER(currency) = LOWER('${Tidx.escape(options.currency)}')`);
+            const where = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
+            const result = await tidx.fetch({
+                chainId: options.chainId,
+                query: `
+            SELECT token, block_num, log_idx, block_timestamp, currency, name, symbol
+            FROM tokencreated
+            ${where}
+            ORDER BY block_num ${direction}, log_idx ${direction}
+            LIMIT ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
+          `,
+                signatures: [tokenCreatedSignature],
+            });
+            // 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;
+                },
+            });
+            return {
+                nextCursor: page.nextCursor,
+                rows: page.rows.map((row) => ({
+                    currency: row.currency,
+                    createdAt: Value.toIsoDateTime(row.block_timestamp),
+                    name: row.name,
+                    symbol: row.symbol,
+                    token: row.token,
+                })),
+            };
+        }, {
+            key: `token:v1:${options.chainId}:indexed:${order}:${encodeURIComponent(options.currency?.toLowerCase() ?? '')}:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : offset !== undefined ? `page:${options.page}` : 'head'}:${limit}`,
+            store,
+            ttl: Ttl.minutes(2),
+        });
+    }
+    const chunk = await Timing.time(c, 'tokens_indexed', () => getIndexedTokens());
+    const addresses = chunk.rows.map((row) => row.token);
+    // `TokenCreated` extras, holder counts, and transfer stats are opt-in
+    // `include`s; logos always ride along (curated R2 icon, falling back to the
+    // on-chain `logoURI`). Resolve all in parallel.
+    const [createdByAddress, holderCounts, logoByAddress, statsByAddress] = await Promise.all([
+        wantCreatedExtras && chunk.rows.length > 0
+            ? Timing.time(c, 'tokens_created_extras', () => getTokenCreatedByAddress(c, { addresses, chainId: options.chainId }))
+            : Promise.resolve({}),
+        wantHolderCount && chunk.rows.length > 0
+            ? Timing.time(c, 'tokens_holders', () => getHolderCountsByAddress(c, { addresses, chainId: options.chainId }))
+            : Promise.resolve(undefined),
+        chunk.rows.length > 0
+            ? Timing.time(c, 'tokens_logos', () => getTokenLogosByAddress(c, { addresses, chainId: options.chainId }))
+            : Promise.resolve({}),
+        wantTransferStats && chunk.rows.length > 0
+            ? Timing.time(c, 'tokens_transfers', () => getTransferStatsByAddress(c, { addresses, chainId: options.chainId }))
+            : Promise.resolve(undefined),
+    ]);
+    return {
+        data: chunk.rows.map((row) => {
+            const created = createdByAddress[row.token];
+            return {
+                address: row.token,
+                admin: wantAdmin ? created?.admin : undefined,
+                currency: row.currency,
+                // `createdAt` rides along free in the indexed page query, but stays an
+                // opt-in field for a consistent contract with the verified page.
+                createdAt: wantCreatedAt ? row.createdAt : undefined,
+                decimals: 6,
+                holderCount: holderCounts?.[row.token],
+                id: row.token,
+                logoUri: logoByAddress[row.token],
+                name: row.name,
+                quoteToken: wantQuoteToken ? created?.quoteToken : undefined,
+                symbol: row.symbol,
+                transferStats: statsByAddress?.[row.token],
+                verified: snapshot.byAddress.has(row.token),
+            };
+        }),
+        nextCursor: chunk.nextCursor,
+    };
+}
+function isTokenNotFound(cause) {
+    if (cause instanceof ContractFunctionExecutionError)
+        return true;
+    if (cause instanceof Error && cause.message.includes('invalid tip20 address'))
+        return true;
+    return false;
+}
+//# sourceMappingURL=tokens.js.map