tapimo 0.5.2 → 0.6.0

package/src/apps/data/routes/addresses.ts

@@ -3,22 +3,32 @@ import { Hono } from 'hono'
 import type * as App from '../../../App.js'
 import * as Activities from './activities.js'
 import * as Balances from './balances.js'
+import * as Valuation from './valuation.js'
 
 /**
  * Composes the `/v1/addresses/:address/*` route surface from the
  * address-scoped sub-routers exported by each resource module. The handlers,
  * schemas, and paths live with the resource they describe (activities,
- * balances); this composer only aggregates them so docs grouping stays by tag
- * while URLs stay nested under the parent resource.
+ * balances, valuation); this composer only aggregates them so docs grouping
+ * stays by tag while URLs stay nested under the parent resource.
  *
  * Only subject-relative resources live here — rows that cannot be interpreted
- * without the path address (activity classification, held-token balances).
- * Plain filtered views of canonical collections are reached via search params
- * instead (`GET /transactions?address=…`, `GET /transfers?address=…`,
- * `GET /transactions/receipts?address=…`).
+ * without the path address (activity classification, held-token balances,
+ * holdings valuation). Plain filtered views of canonical collections are
+ * reached via search params instead (`GET /transactions?address=…`,
+ * `GET /transfers?address=…`, `GET /transactions/receipts?address=…`).
  */
-export function addresses() {
+export function addresses(options: addresses.Options = {}) {
   return new Hono<App.Environment>()
-    .route('/', Activities.addresses())
-    .route('/', Balances.addresses())
+    .route('/', Activities.addresses({ fx: options.fx }))
+    .route('/', Balances.addresses({ fx: options.fx }))
+    .route('/', Valuation.addresses({ fx: options.fx }))
+}
+
+export declare namespace addresses {
+  /** Options for the address-scoped route composer. */
+  type Options = {
+    /** FX configuration for the valuation endpoint. */
+    fx?: Valuation.addresses.Fx | undefined
+  }
 }

package/src/apps/data/routes/balances.test.ts

@@ -1,4 +1,5 @@
 import { Schema } from 'tapimo'
+import { FxOracle } from 'tapimo/apps'
 import { Value as core_Value } from 'ox'
 import { Actions } from 'viem/tempo'
 
@@ -8,6 +9,12 @@ import * as TestViem from '../../../../test/Viem.js'
 import * as Balances from './balances.js'
 import * as Tokens from './tokens.js'
 
+// Deterministic EUR-based rate set so conversion math is exact in assertions.
+const fixed = FxOracle.from({
+  name: 'fixed',
+  rates: async () => ({ asOf: '2026-01-01', base: 'EUR', rates: { AUD: '1.6', USD: '1.0' } }),
+})
+
 // Verified enrichment is store-backed now that the build-time bundle is gone, so
 // seed a shared in-memory verified store from the curated seeds file. Tests use
 // this wrapper instead of `TestApp.client` so the default app exposes the same
@@ -35,6 +42,21 @@ async function holderWithBalance(client: ReturnType<typeof app>) {
 }
 
 describe('GET /addresses/:address/balances', () => {
+  test('parses the total count include', () => {
+    expect(Balances.schema.getAddressBalances.Query.parse({ include: 'totalCount' }).include)
+      .toMatchInlineSnapshot(`
+        [
+          "totalCount",
+        ]
+      `)
+    expect(Balances.schema.getAddressBalances.Query.safeParse({ include: 'token' }).success).toBe(
+      false,
+    )
+    expect(
+      Balances.schema.getAddressBalances.Query.safeParse({ include: 'token.logoUri' }).success,
+    ).toBe(false)
+  })
+
   test('returns an amount-ranked balance page with per-row token references', async () => {
     const client = app()
     const holder = await holderWithBalance(client)
@@ -64,12 +86,15 @@ describe('GET /addresses/:address/balances', () => {
           // `formatted` is `amount` scaled down by `decimals` (round-trips back
           // to the base-unit amount).
           /^\d+(\.\d+)?$/.test(entry.formatted) &&
-          core_Value.from(entry.formatted, entry.token.decimals) === BigInt(entry.amount) &&
+          core_Value.from(entry.formatted, entry.decimals) === BigInt(entry.amount) &&
+          entry.currency === entry.token.currency &&
+          entry.decimals === entry.token.decimals &&
           /^0x[0-9a-f]{40}$/.test(entry.token.address) &&
-          typeof entry.token.currency === 'string' &&
-          Number.isInteger(entry.token.decimals) &&
+          typeof entry.currency === 'string' &&
+          Number.isInteger(entry.decimals) &&
           typeof entry.token.name === 'string' &&
           typeof entry.token.symbol === 'string' &&
+          (entry.token.logoUri === undefined || typeof entry.token.logoUri === 'string') &&
           typeof entry.token.verified === 'boolean',
       ),
     ).toBe(true)
@@ -133,15 +158,17 @@ describe('GET /addresses/:address/balances', () => {
     // The count comes from the corrected candidate set and is never capped.
     expect(body.meta!.totalCountCapped).toBe(false)
 
-    // Without the include, `meta` is omitted. The corrected candidate set
-    // already supplies the count, so no second indexer query is needed.
+    // Without the include, counts are omitted (`meta` carries at most rate
+    // provenance). The corrected candidate set already supplies the count, so
+    // no second indexer query is needed.
     const bareResponse = await client.v1.addresses[':address'].balances.$get(
       { param: { address: holder }, query: { limit: '5' } },
       TestApp.auth,
     )
     const bare = await TestApp.json(bareResponse, Balances.schema.getAddressBalances.Response)
     expect(bareResponse.status).toBe(200)
-    expect(bare.meta).toBeUndefined()
+    expect(bare.meta?.totalCount).toBeUndefined()
+    expect(bare.meta?.totalCountCapped).toBeUndefined()
     expect(bareResponse.headers.get('server-timing')?.includes('balances_discovery;dur=')).toBe(
       true,
     )
@@ -235,24 +262,45 @@ describe('GET /addresses/:address/balances', () => {
     expect(stable.error.code).toMatchInlineSnapshot(`"query_invalid"`)
   })
 
-  test('restricts balances to verified tokens when verified=true', async () => {
-    const client = app()
+  test('includes token logo and verification fields by default', async () => {
+    const logoDb = TestApp.database()
+    await TestApp.verifiedSeed(logoDb, runtime.chainId, {
+      tokens: [
+        {
+          address: TestApp.tokenWithHolders,
+          currency: 'USD',
+          decimals: 6,
+          logoUri: 'https://example.com/pathusd.svg',
+          name: 'PathUSD',
+          symbol: 'pathUSD',
+        },
+      ],
+    })
+    const client = app({ db: logoDb })
     const holder = await holderWithBalance(client)
     expect(holder).toMatch(/^0x[0-9a-f]{40}$/)
 
     // The seeded holder is a holder of a verified token, so the verified
     // balances page must include at least that token.
     const response = await client.v1.addresses[':address'].balances.$get(
-      { param: { address: holder }, query: { limit: '20', verified: 'true' } },
+      {
+        param: { address: holder },
+        query: {
+          limit: '20',
+          verified: 'true',
+        },
+      },
       TestApp.auth,
     )
     const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
     expect(response.status).toBe(200)
     expect(body.data.length).toBeGreaterThan(0)
     for (const balance of body.data) expect(balance.token.verified).toBe(true)
+    const pathUsd = body.data.find((balance) => balance.token.address === TestApp.tokenWithHolders)
+    expect(pathUsd?.token.logoUri).toMatch(/^http/)
   })
 
-  test('narrows balances by currency (implies verified)', async () => {
+  test('narrows balances by currency and retains verification', async () => {
     const client = app()
     const holder = await holderWithBalance(client)
     expect(holder).toMatch(/^0x[0-9a-f]{40}$/)
@@ -264,8 +312,9 @@ describe('GET /addresses/:address/balances', () => {
     const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
     expect(response.status).toBe(200)
     for (const balance of body.data) {
-      expect(balance.token.verified).toBe(true)
+      expect(balance.currency).toBe('USD')
       expect(balance.token.currency).toBe('USD')
+      expect(balance.token.verified).toBe(true)
     }
   })
 
@@ -293,6 +342,90 @@ describe('GET /addresses/:address/balances', () => {
     expect(pathUsd?.feeEligible).toBe(true)
   })
 
+  test('values each verified holding in the default denomination', async () => {
+    await TestApp.verifiedSeed(db, runtime.chainId)
+    const client = app()
+    const holder = await holderWithBalance(client)
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: { limit: '50' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+    expect(response.status).toBe(200)
+
+    // The guaranteed pathUSD holding is curated USD, so its USD value is the
+    // holding itself; unverified holdings are never valued.
+    const pathUsd = body.data.find((entry) => entry.token.address === TestApp.tokenWithHolders)
+    expect(pathUsd?.valuation).toEqual({ amount: pathUsd!.formatted, currency: 'USD' })
+    for (const entry of body.data) if (!entry.token.verified) expect(entry.valuation).toBeNull()
+  })
+
+  test('values holdings in a requested denomination', async () => {
+    await TestApp.verifiedSeed(db, runtime.chainId)
+    const client = app({ fx: { oracle: fixed } })
+    const holder = await holderWithBalance(client)
+
+    // Denominations are case-insensitive.
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: { denomination: 'aud', limit: '50' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+    expect(response.status).toBe(200)
+
+    // USD -> AUD at the fixed 1.6 cross rate, floored to 6 dp.
+    const pathUsd = body.data.find((entry) => entry.token.address === TestApp.tokenWithHolders)
+    const expected = core_Value.format((core_Value.from(pathUsd!.formatted, 6) * 16n) / 10n, 6)
+    expect(pathUsd?.valuation).toEqual({ amount: expected, currency: 'AUD' })
+    // Consulted rates surface their provenance response-wide.
+    expect(body.meta?.pricing).toMatchInlineSnapshot(`
+      {
+        "asOf": "2026-01-01",
+        "basis": "nominal",
+        "source": "fixed",
+      }
+    `)
+  })
+
+  test('nulls valuations when rates are unavailable', async () => {
+    await TestApp.verifiedSeed(db, runtime.chainId)
+    const client = app({ fx: { oracle: FxOracle.ecb({ url: 'http://127.0.0.1:1' }) } })
+    const holder = await holderWithBalance(client)
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: { denomination: 'AUD', limit: '50' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+
+    // The live balance page survives a rate outage; only values degrade, and
+    // no provenance is claimed.
+    expect(response.status).toBe(200)
+    expect(body.data.length).toBeGreaterThan(0)
+    for (const entry of body.data) expect(entry.valuation).toBeNull()
+    expect(body.meta?.pricing).toBeUndefined()
+  })
+
+  test('rejects denominations the oracle does not price', async () => {
+    await TestApp.verifiedSeed(db, runtime.chainId)
+    const client = app({ fx: { oracle: fixed } })
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      {
+        param: { address: `0x${'11'.repeat(20)}` },
+        query: { currency: 'JPY', denomination: 'JPY' },
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    const { requestId, ...stable } = body
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(typeof requestId).toMatchInlineSnapshot(`"string"`)
+    expect(stable.error.code).toMatchInlineSnapshot(`"query_invalid"`)
+  })
+
   test('restricts the page to fee tokens when feeEligible=true', async () => {
     const client = app()
     const holder = await holderWithBalance(client)

package/src/apps/data/routes/balances.ts

@@ -12,8 +12,10 @@ import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as Timing from '../../../internal/Timing.js'
 import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
+import * as FxOracle from '../FxOracle.js'
 import * as FeeAmm from './fee-amm.js'
 import * as Tokens from './tokens.js'
+import * as Valuation from './valuation.js'
 
 // TIP-20 tokens are minted by the TIP-20 factory and live at deterministic
 // `0x20c0…`-prefixed addresses (e.g. pathUSD `0x20c0…0000`). The indexer's
@@ -50,6 +52,7 @@ export namespace schema {
             ),
           ),
         cursor: Schema.Cursor,
+        denomination: Schema.Denomination,
         feeEligible: z
           .optional(Schema.booleanQuery())
           .check(
@@ -78,12 +81,7 @@ export namespace schema {
         z.describe('Query parameters for listing an account’s token balances.'),
       )
 
-    /**
-     * A TIP-20 token balance held by an address: the held `amount` in the
-     * token's base unit, its `formatted` value, and the trimmed `token`
-     * reference inlined per row. Rows whose token metadata cannot be resolved
-     * are omitted.
-     */
+    /** A TIP-20 balance with raw and formatted amounts. Unresolvable token metadata omits the row. */
     export const Balance = Schema.describe(
       z.object({
         amount: z
@@ -95,21 +93,23 @@ export namespace schema {
             ),
             z.meta({ examples: ['1500000'] }),
           ),
-        formatted: z
+        currency: z
           .string()
           .check(
             z.describe(
-              'The same balance in human-readable decimal form, using the token’s `decimals`.',
+              'The currency label for this balance, such as `USD` for a USD-denominated token.',
             ),
-            z.meta({ examples: ['1.5'] }),
+            z.meta({ examples: ['USD'] }),
           ),
-        id: z
-          .string()
+        decimals: z
+          .number()
           .check(
+            z.int(),
+            z.nonnegative(),
             z.describe(
-              'A stable resource ID for this balance, equal to the token contract address.',
+              'The number of decimal places used to convert this balance between base units and human-readable form.',
             ),
-            z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
+            z.meta({ examples: [6] }),
           ),
         feeEligible: z
           .optional(z.boolean())
@@ -123,11 +123,51 @@ export namespace schema {
             ),
             z.meta({ examples: [true] }),
           ),
+        formatted: z
+          .string()
+          .check(
+            z.describe(
+              'The same balance in human-readable decimal form, using this balance’s `decimals`.',
+            ),
+            z.meta({ examples: ['1.5'] }),
+          ),
+        id: z
+          .string()
+          .check(
+            z.describe(
+              'A stable resource ID for this balance, equal to the token contract address.',
+            ),
+            z.meta({ examples: ['0x20c0000000000000000000008f5425160ebe5525'] }),
+          ),
         token: Tokens.schema.Token,
+        valuation: z
+          .nullable(Valuation.schema.Value)
+          .check(
+            z.describe(
+              'The holding’s nominal value in the requested `denomination`, or `null` when the ' +
+                'token is unverified, its display currency has no rate, or rates were unavailable.',
+            ),
+          ),
       }),
       'One TIP-20 token balance held by this account, with both raw and human-readable amounts.',
     )
 
+    /** Page-level resources: opt-in counts plus valuation rate provenance. */
+    export const Meta = z
+      .object({
+        pricing: z
+          .optional(Valuation.schema.Pricing)
+          .check(
+            z.describe(
+              'Rate provenance for row valuations. Present when conversion rates were ' +
+                'consulted; absent when every value was identity-valued or rates were unavailable.',
+            ),
+          ),
+        totalCount: z.optional(Schema.TotalCount),
+        totalCountCapped: z.optional(Schema.TotalCountCapped),
+      })
+      .check(z.describe('Page-level resources attached to this response.'))
+
     /** Page of TIP-20 token balances held by an address, ordered by amount descending. */
     export const Response = z
       .object({
@@ -135,8 +175,8 @@ export namespace schema {
           .array(Balance)
           .check(z.describe('The balances in this page, ordered from largest to smallest amount.')),
         meta: z
-          .optional(Schema.CountMeta)
-          .check(z.describe('Page-level resources you requested with `include`.')),
+          .optional(Meta)
+          .check(z.describe('Page-level resources: opt-in counts and valuation rate provenance.')),
         nextCursor: Schema.NextCursor,
       })
       .check(z.describe('A page of TIP-20 token balances held by this account.'))
@@ -147,7 +187,8 @@ export namespace schema {
  * Creates address-scoped balance handlers, mounted under the `/addresses`
  * composer. Exposes `GET /:address/balances`, the held-balance page.
  */
-export function addresses() {
+export function addresses(options: addresses.Options = {}) {
+  const oracle = options.fx?.oracle ?? FxOracle.ecb()
   return new Hono<App.Environment>().get(
     '/v1/addresses/:address/balances',
     Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -161,10 +202,10 @@ export function addresses() {
     }),
     OpenApi.describeRoute({
       description:
-        'Lists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form.',
+        'Lists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form, and each verified holding carries its nominal value in the requested denomination.',
       operationId: 'getAddressBalances',
       responses: OpenApi.responses({
-        errors: { 502: 'The upstream indexer could not serve this request.' },
+        errors: { 502: 'Could not read balance or token data from an upstream service.' },
         success: {
           description: 'A page of token balances for this account.',
           schema: schema.getAddressBalances.Response,
@@ -218,32 +259,57 @@ export function addresses() {
           chainId,
           currency: query.currency,
           cursor: query.cursor,
+          denomination: query.denomination ?? 'USD',
           feeEligible,
           feeTokens,
           includeTotalCount: query.include.includes('totalCount'),
           limit: query.limit,
+          oracle,
           page: query.page,
           verified,
         })
 
         return c.json(Response.validated(schema.getAddressBalances.Response, balances), 200)
       } catch (cause) {
+        if (cause instanceof Valuation.UnsupportedDenominationError)
+          return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
         return Response.upstream(c, cause)
       }
     },
   )
 }
 
+export declare namespace addresses {
+  /** Options for the address-scoped balance handlers. */
+  type Options = {
+    /** FX configuration backing per-row valuation. */
+    fx?: Valuation.addresses.Fx | undefined
+  }
+}
+
 async function getAddressBalances(
   c: Context<App.Environment>,
   options: getAddressBalances.Options,
 ) {
-  const { address, chainId, currency, feeEligible, feeTokens, includeTotalCount, limit, verified } =
-    options
+  const {
+    address,
+    chainId,
+    currency,
+    denomination,
+    feeEligible,
+    feeTokens,
+    includeTotalCount,
+    limit,
+    oracle,
+    verified,
+  } = options
   const tidx = c.get('getTidx')(chainId)
   const cursor = options.cursor ? Cursor.decode(options.cursor, ['uint', 'address']) : undefined
   const offset = options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : 0
 
+  // Validate the requested denomination independently of the current page.
+  await Valuation.ratesFor(c, { currencies: [], denomination, oracle })
+
   // Build the optional `token IN (…)` restriction before hitting TIDX. The
   // verified/`currency` filter and the `feeEligible` filter each contribute a set
   // of allowed addresses (`currency` matched case-insensitively so callers can
@@ -338,58 +404,76 @@ async function getAddressBalances(
       nextCursor: page.nextCursor,
     }
 
-  // Resolve token metadata for each balance. The endpoint's contract is a
-  // balance with its `token` reference inlined per row (and `formatted` needs
-  // the token `decimals`), so a row whose metadata cannot be resolved is
-  // dropped rather than returned with placeholders. Because the TIDX filter
-  // already restricts to TIP-20 (`0x20c0…`) tokens, resolution should succeed
-  // for nearly every row in practice.
-  //
-  // The verified `snapshot` fetched above is reused across the page instead of
-  // re-resolved per row. `createdAt` is not part of this endpoint's response,
-  // so it is never fetched here.
+  const rates = await Valuation.ratesFor(c, {
+    currencies: page.rows.flatMap((row) => {
+      const held = snapshot.byAddress.get(row.address.toLowerCase())?.currency
+      return held === undefined ? [] : [held]
+    }),
+    denomination,
+    oracle,
+  })
+
+  // Balance tokens retain their logo and verification metadata by default.
   const resolved = await Timing.time(c, 'tokens', () =>
     Promise.all(
-      page.rows.map((holding) =>
-        Tokens.resolveToken(c, {
-          address: holding.address,
-          chainId,
-          snapshot,
-        })
-          .then((metadata) => ({ amount: holding.amount, metadata }) as const)
-          .catch(() => ({ amount: holding.amount, metadata: undefined }) as const),
-      ),
+      page.rows.map(async (holding) => {
+        try {
+          const token = Schema.Address.parse(holding.address.toLowerCase())
+          const [logoUri, metadata] = await Promise.all([
+            Timing.time(c, 'token_logo', () =>
+              Tokens.getTokenLogo(c, { address: token, chainId }),
+            ).catch(() => undefined),
+            Timing.time(c, 'token_metadata', () =>
+              Tokens.getTokenMetadata(c, { address: token, chainId }),
+            ),
+          ])
+          return { amount: holding.amount, logoUri, metadata, token }
+        } catch {
+          return undefined
+        }
+      }),
     ),
   )
 
   const data: z.output<typeof schema.getAddressBalances.Balance>[] = []
   for (const entry of resolved) {
-    if (!entry.metadata) continue
+    if (!entry) continue
     data.push({
       amount: entry.amount,
-      formatted: core_Value.format(BigInt(entry.amount), entry.metadata.decimals),
-      id: entry.metadata.address,
+      currency: entry.metadata.currency,
+      decimals: entry.metadata.decimals,
       // Best-effort: omit `feeEligible` entirely when the fee-token set was
       // unavailable, rather than reporting a misleading `false`.
-      ...(feeTokens ? { feeEligible: feeTokens.has(entry.metadata.address.toLowerCase()) } : {}),
+      ...(feeTokens ? { feeEligible: feeTokens.has(entry.token.toLowerCase()) } : {}),
+      formatted: core_Value.format(BigInt(entry.amount), entry.metadata.decimals),
+      id: entry.token,
       token: {
-        address: entry.metadata.address,
+        address: entry.token,
         currency: entry.metadata.currency,
         decimals: entry.metadata.decimals,
-        id: entry.metadata.id,
-        logoUri: entry.metadata.logoUri,
+        id: entry.token,
+        logoUri:
+          entry.logoUri ?? snapshot.byAddress.get(entry.token)?.logoUri ?? entry.metadata.logoUri,
         name: entry.metadata.name,
         symbol: entry.metadata.symbol,
-        verified: entry.metadata.verified,
+        verified: snapshot.byAddress.has(entry.token),
       },
+      valuation: Valuation.valuationFor({
+        amount: BigInt(entry.amount),
+        denomination,
+        rates,
+        token: snapshot.byAddress.get(entry.token),
+      }),
     })
   }
 
+  const meta = {
+    ...(rates ? { pricing: Valuation.pricing(rates, oracle) } : {}),
+    ...(includeTotalCount ? { totalCount: corrected.length, totalCountCapped: false } : {}),
+  }
   return {
     data,
-    ...(includeTotalCount
-      ? { meta: { totalCount: corrected.length, totalCountCapped: false } }
-      : {}),
+    ...(Object.keys(meta).length > 0 ? { meta } : {}),
     nextCursor: page.nextCursor,
   }
 }
@@ -402,6 +486,8 @@ declare namespace getAddressBalances {
     currency?: string | undefined
     /** Opaque keyset cursor anchoring the page; omit for the head page. */
     cursor?: string | undefined
+    /** Currency the per-row valuations are denominated in (uppercase). */
+    denomination: string
     /** When true, restrict the page to fee-usable tokens (members of `feeTokens`). */
     feeEligible?: boolean | undefined
     /**
@@ -413,6 +499,8 @@ declare namespace getAddressBalances {
     /** When true, include the corrected candidate count in response metadata. */
     includeTotalCount: boolean
     limit: number
+    /** FX rate oracle backing per-row valuation. */
+    oracle: FxOracle.Oracle
     /** 1-indexed page number (positional pagination; exclusive with `cursor`). */
     page?: number | undefined
     /** When true, restrict the page to addresses in the curated verified list. */
@@ -433,6 +521,7 @@ function allowedTokens(options: allowedTokens.Options): string[] | undefined {
   const { currency, feeEligible, feeTokens, snapshot, verified } = options
   let allowed: string[] | undefined
   if (verified) {
+    if (!snapshot) throw new Error('Unable to resolve verified token metadata')
     const matching = currency
       ? (snapshot.byCurrency.get(currency.toLowerCase()) ?? [])
       : snapshot.list
@@ -459,7 +548,7 @@ declare namespace allowedTokens {
     /** The chain's fee-token set, if resolved (best-effort). */
     feeTokens?: ReadonlySet<string> | undefined
     /** Compiled verified-token snapshot for the chain. */
-    snapshot: VerifiedTokens.Snapshot
+    snapshot?: VerifiedTokens.Snapshot | undefined
     /** When true, restrict to addresses in the curated verified list. */
     verified?: boolean | undefined
   }