tapimo 0.9.0 → 0.10.0

package/dist/apps/data/routes/balances.d.ts

@@ -51,10 +51,10 @@ export declare namespace schema {
                 symbol: z.ZodMiniString<string>;
                 verified: z.ZodMiniBoolean<boolean>;
             }, z.core.$strip>;
-            valuation: z.ZodMiniNullable<z.ZodMiniObject<{
+            valuation: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniObject<{
                 amount: z.ZodMiniString<string>;
                 currency: z.ZodMiniString<string>;
-            }, z.core.$strip>>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>;
         /** Page-level resources: opt-in counts plus valuation rate provenance. */
         const Meta: z.ZodMiniObject<{
@@ -85,10 +85,10 @@ export declare namespace schema {
                     symbol: z.ZodMiniString<string>;
                     verified: z.ZodMiniBoolean<boolean>;
                 }, z.core.$strip>;
-                valuation: z.ZodMiniNullable<z.ZodMiniObject<{
+                valuation: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniObject<{
                     amount: z.ZodMiniString<string>;
                     currency: z.ZodMiniString<string>;
-                }, z.core.$strip>>;
+                }, z.core.$strip>>>;
             }, z.core.$strip>>;
             meta: z.ZodMiniOptional<z.ZodMiniObject<{
                 valuation: z.ZodMiniOptional<z.ZodMiniObject<{
@@ -135,10 +135,10 @@ export declare namespace schema {
                 symbol: z.ZodMiniString<string>;
                 verified: z.ZodMiniBoolean<boolean>;
             }, z.core.$strip>;
-            valuation: z.ZodMiniNullable<z.ZodMiniObject<{
+            valuation: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniObject<{
                 amount: z.ZodMiniString<string>;
                 currency: z.ZodMiniString<string>;
-            }, z.core.$strip>>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>;
     }
 }
@@ -172,14 +172,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "api_key_malformed";
+                    code: "upstream_error";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 502;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -200,14 +200,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "api_key_invalid" | "api_key_missing";
+                    code: "api_key_malformed";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 401;
+            status: 400;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -228,14 +228,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "api_key_forbidden" | "api_key_ip_forbidden";
+                    code: "api_key_invalid" | "api_key_missing";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
+            status: 401;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -256,14 +256,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "payment_required" | "rate_limit_exceeded";
+                    code: "api_key_forbidden" | "api_key_ip_forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 429;
+            status: 403;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -284,14 +284,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "query_invalid";
+                    code: "payment_required" | "rate_limit_exceeded";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 429;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -312,14 +312,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "upstream_error";
+                    code: "address_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 502;
+            status: 400;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -340,7 +340,7 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "address_invalid";
+                    code: "query_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
@@ -384,10 +384,10 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
                         symbol: string;
                         verified: boolean;
                     };
-                    valuation: {
+                    valuation?: {
                         amount: string;
                         currency: string;
-                    } | null;
+                    } | null | undefined;
                 }[];
                 meta?: {
                     valuation?: {
@@ -441,14 +441,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "api_key_malformed";
+                    code: "upstream_error";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 502;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -463,14 +463,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "api_key_invalid" | "api_key_missing";
+                    code: "api_key_malformed";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 401;
+            status: 400;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -485,14 +485,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "api_key_forbidden" | "api_key_ip_forbidden";
+                    code: "api_key_invalid" | "api_key_missing";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 403;
+            status: 401;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -507,14 +507,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "payment_required" | "rate_limit_exceeded";
+                    code: "api_key_forbidden" | "api_key_ip_forbidden";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 429;
+            status: 403;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -529,14 +529,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "query_invalid";
+                    code: "payment_required" | "rate_limit_exceeded";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 400;
+            status: 429;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -551,14 +551,14 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "upstream_error";
+                    code: "address_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
                 requestId: string;
             };
             outputFormat: "json";
-            status: 502;
+            status: 400;
             input: {
                 param: {
                     address: `0x${string}`;
@@ -573,7 +573,7 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
         } | {
             output: {
                 error: {
-                    code: "address_invalid";
+                    code: "query_invalid";
                     details?: readonly Response.error.Detail[] | undefined;
                     message: string;
                 };
@@ -610,10 +610,10 @@ export declare function addresses(options?: addresses.Options): import("hono/hon
                     symbol: string;
                     verified: boolean;
                 };
-                valuation: {
+                valuation?: {
                     amount: string;
                     currency: string;
-                } | null;
+                } | null | undefined;
             };
             outputFormat: "json";
             status: 200;

package/dist/apps/data/routes/balances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"balances.d.ts","sourceRoot":"","sources":["../../../../src/apps/data/routes/balances.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAE7B,OAAO,KAAK,KAAK,GAAG,MAAM,iBAAiB,CAAA;AAK3C,OAAO,KAAK,QAAQ,MAAM,+BAA+B,CAAA;AAOzD,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAQ3C,iDAAiD;AACjD,yBAAiB,MAAM,CAAC;IACtB,oDAAoD;IACpD,UAAiB,kBAAkB,CAAC;QAClC,oDAAoD;QAC7C,MAAM,MAAM;;yBAM6D,CAAA;QAEhF,qDAAqD;QAC9C,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;0BA0Cf,CAAA;QAEH,kGAAkG;QAC3F,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;yBAoEnB,CAAA;QAED,0EAA0E;QACnE,MAAM,IAAI;;;;;;;;yBAasD,CAAA;QAEvE,sFAAsF;QAC/E,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yBAUwD,CAAA;KAC9E;IAED,mDAAmD;IACnD,UAAiB,iBAAiB,CAAC;QACjC,4DAA4D;QACrD,MAAM,MAAM;;;yBAO2D,CAAA;QAE9E,6DAA6D;QACtD,MAAM,KAAK;;;;;;0BAK6D,CAAA;QAE/E,wDAAwD;QACjD,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;yBAEpB,CAAA;KACF;CACF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,SAAS,CAAC,OAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAqMxD;AAED,MAAM,CAAC,OAAO,WAAW,SAAS,CAAC;IACjC,uDAAuD;IACvD,KAAK,OAAO,GAAG;QACb,kDAAkD;QAClD,EAAE,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,EAAE,GAAG,SAAS,CAAA;KACxC,CAAA;CACF"}
+{"version":3,"file":"balances.d.ts","sourceRoot":"","sources":["../../../../src/apps/data/routes/balances.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAE7B,OAAO,KAAK,KAAK,GAAG,MAAM,iBAAiB,CAAA;AAK3C,OAAO,KAAK,QAAQ,MAAM,+BAA+B,CAAA;AAOzD,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAQ3C,iDAAiD;AACjD,yBAAiB,MAAM,CAAC;IACtB,oDAAoD;IACpD,UAAiB,kBAAkB,CAAC;QAClC,oDAAoD;QAC7C,MAAM,MAAM;;yBAM6D,CAAA;QAEhF,qDAAqD;QAC9C,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;0BA+Cf,CAAA;QAEH,kGAAkG;QAC3F,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;yBAoEnB,CAAA;QAED,0EAA0E;QACnE,MAAM,IAAI;;;;;;;;yBAasD,CAAA;QAEvE,sFAAsF;QAC/E,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yBAUwD,CAAA;KAC9E;IAED,mDAAmD;IACnD,UAAiB,iBAAiB,CAAC;QACjC,4DAA4D;QACrD,MAAM,MAAM;;;yBAO2D,CAAA;QAE9E,6DAA6D;QACtD,MAAM,KAAK;;;;;;0BAU6D,CAAA;QAE/E,wDAAwD;QACjD,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;yBAEpB,CAAA;KACF;CACF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,SAAS,CAAC,OAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAsMxD;AAED,MAAM,CAAC,OAAO,WAAW,SAAS,CAAC;IACjC,uDAAuD;IACvD,KAAK,OAAO,GAAG;QACb,kDAAkD;QAClD,EAAE,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,EAAE,GAAG,SAAS,CAAA;KACxC,CAAA;CACF"}

package/dist/apps/data/routes/balances.js

@@ -51,7 +51,8 @@ export var schema;
             include: Schema.totalCountInclude,
             limit: Schema.Limit,
             page: Schema.Page,
-            'valuation.currency': Schema.Denomination,
+            'valuation.currency': Schema.Denomination.check(z.describe('When present, include each holding’s nominal value in this denomination. ' +
+                'Case-insensitive and must be priced by the configured FX oracle.')),
             verified: z
                 .optional(Schema.booleanQuery())
                 .check(z.describe('When `true`, include only tokens from Tempo’s curated verified token list.'), z.meta({ examples: [true] })),
@@ -83,9 +84,9 @@ export var schema;
                 .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 `valuation.currency`, or `null` when the ' +
-                'token is unverified, its display currency has no rate, or rates were unavailable.')),
+                .optional(z.nullable(Valuation.schema.Value))
+                .check(z.describe('The holding’s nominal value when `valuation.currency` is requested, 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. */
         getAddressBalances.Meta = z
@@ -125,7 +126,8 @@ export var schema;
         getAddressBalance.Query = z
             .strictObject({
             chainId: Schema.ChainIdQuery,
-            'valuation.currency': Schema.Denomination,
+            'valuation.currency': Schema.Denomination.check(z.describe('When present, include the holding’s nominal value in this denomination. ' +
+                'Case-insensitive and must be priced by the configured FX oracle.')),
         })
             .check(z.describe('Query parameters for reading one account token balance.'));
         /** A single TIP-20 token balance held by an address. */
@@ -146,7 +148,7 @@ export function addresses(options = {}) {
         code: 'query_invalid',
         message: 'Invalid query parameters',
     }), 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, and each verified holding carries its nominal value in the requested denomination.',
+        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. Pass `valuation.currency` to include nominal values.',
         operationId: 'getAddressBalances',
         responses: OpenApi.responses({
             errors: { 502: 'Could not read balance or token data from an upstream service.' },
@@ -182,26 +184,13 @@ export function addresses(options = {}) {
             // `verified=true` from the caller's perspective.
             const verified = query.verified || query.currency !== undefined;
             const feeEligible = query.feeEligible ?? false;
-            // The fee-token set powers both the per-row `feeEligible` flag (always)
-            // and the optional `feeEligible=true` page restriction. It is memoized
-            // per chain (a near-constant), so one read feeds the page, the count,
-            // and the row enrichment. It is a best-effort enrichment: a lookup
-            // failure omits `feeEligible` rather than failing the page — unless the
-            // caller explicitly asked to filter by `feeEligible`, where the filter
-            // can't be honored, so the failure surfaces as the declared `502`.
-            const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch((cause) => {
-                if (feeEligible)
-                    throw cause;
-                return undefined;
-            });
             const balances = await getAddressBalances(c, {
                 address,
                 chainId,
                 currency: query.currency,
                 cursor: query.cursor,
-                denomination: query['valuation.currency'] ?? 'USD',
+                denomination: query['valuation.currency'],
                 feeEligible,
-                feeTokens,
                 includeTotalCount: query.include.includes('totalCount'),
                 limit: query.limit,
                 oracle,
@@ -260,9 +249,24 @@ export function addresses(options = {}) {
         const { address, token } = c.req.valid('param');
         const query = c.req.valid('query');
         const chainId = query.chainId ?? c.get('chainId');
+        const denomination = query['valuation.currency'];
         try {
-            const snapshot = await VerifiedTokens.snapshot(c, chainId);
-            const [balance, resolvedToken] = await Promise.all([
+            const rates = denomination
+                ? await Valuation.rateSet(c, oracle)
+                    .then((rates) => {
+                    if (denomination !== rates.base && rates.rates[denomination] === undefined)
+                        throw new Valuation.UnsupportedDenominationError(denomination, oracle.name);
+                    return rates;
+                })
+                    .catch((cause) => {
+                    if (cause instanceof Valuation.UnsupportedDenominationError)
+                        throw cause;
+                    return undefined;
+                })
+                : undefined;
+            const snapshotPromise = VerifiedTokens.snapshot(c, chainId);
+            const resolvedTokenPromise = snapshotPromise.then((snapshot) => Timing.time(c, 'token', () => Tokens.resolveToken(c, { address: token, chainId, include: [], snapshot })));
+            const [balance, feeTokens, snapshot, resolvedToken] = await Promise.all([
                 Timing.time(c, 'balance_rpc', async () => {
                     const result = await Actions.token.getBalance(c.get('getClient')(chainId), {
                         account: address,
@@ -270,15 +274,10 @@ export function addresses(options = {}) {
                     });
                     return result.amount;
                 }),
-                Timing.time(c, 'token', () => Tokens.resolveToken(c, { address: token, chainId, include: [], snapshot })),
+                FeeAmm.feeTokenSet(c, chainId).catch(() => undefined),
+                snapshotPromise,
+                resolvedTokenPromise,
             ]);
-            const denomination = query['valuation.currency'] ?? 'USD';
-            const rates = await Valuation.ratesFor(c, {
-                currencies: snapshot.byAddress.has(token) ? [resolvedToken.currency] : [],
-                denomination,
-                oracle,
-            });
-            const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch(() => undefined);
             return c.json(Response.validated(schema.getAddressBalance.Response, {
                 amount: balance.toString(),
                 currency: resolvedToken.currency,
@@ -287,12 +286,16 @@ export function addresses(options = {}) {
                 formatted: core_Value.format(balance, resolvedToken.decimals),
                 id: token,
                 token: resolvedToken,
-                valuation: Valuation.valuationFor({
-                    amount: balance,
-                    denomination,
-                    rates,
-                    token: snapshot.byAddress.get(token),
-                }),
+                ...(denomination
+                    ? {
+                        valuation: Valuation.valuationFor({
+                            amount: balance,
+                            denomination,
+                            rates,
+                            token: snapshot.byAddress.get(token),
+                        }),
+                    }
+                    : {}),
             }), 200);
         }
         catch (cause) {
@@ -309,12 +312,14 @@ export function addresses(options = {}) {
     });
 }
 async function getAddressBalances(c, options) {
-    const { address, chainId, currency, denomination, feeEligible, feeTokens, includeTotalCount, limit, oracle, verified, } = options;
+    const { address, chainId, currency, denomination, feeEligible, 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 });
+    // Validate an explicit denomination before balance discovery and correction
+    // so dependency failures cannot mask a caller error.
+    if (denomination)
+        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
@@ -322,16 +327,31 @@ async function getAddressBalances(c, options) {
     // intersection. If any active filter rules every token out, return an empty
     // page without a round trip. The snapshot is reused for the page enrichment
     // below.
-    const snapshot = await VerifiedTokens.snapshot(c, chainId);
-    const allowed = allowedTokens({ currency, feeEligible, feeTokens, snapshot, verified });
+    const snapshotPromise = VerifiedTokens.snapshot(c, chainId);
+    // Fee filtering can fail before the concurrently started snapshot is awaited.
+    // Observing this branch prevents an unhandled rejection; the later await still propagates it.
+    void snapshotPromise.catch(() => undefined);
+    const [snapshot_filter, feeTokens_filter] = await Promise.all([
+        verified ? snapshotPromise : Promise.resolve(undefined),
+        feeEligible ? FeeAmm.feeTokenSet(c, chainId) : Promise.resolve(undefined),
+    ]);
+    const allowed = allowedTokens({
+        currency,
+        feeEligible,
+        feeTokens: feeTokens_filter,
+        snapshot: snapshot_filter,
+        verified,
+    });
     const tokenFilter = allowed?.map((address) => `'${address}'`);
-    if (tokenFilter?.length === 0)
+    if (tokenFilter?.length === 0) {
+        await snapshotPromise;
         return {
             data: [],
             ...(includeTotalCount ? { meta: { totalCount: 0, totalCountCapped: false } } : {}),
             nextCursor: null,
         };
-    const holdings = await Timing.time(c, 'balances_discovery', async () => {
+    }
+    const holdingsPromise = Timing.time(c, 'balances_discovery', async () => {
         const tokenIn = tokenFilter ? ` AND token IN (${tokenFilter.join(', ')})` : '';
         const result = await tidx.fetch({
             chainId,
@@ -349,33 +369,49 @@ async function getAddressBalances(c, options) {
             return token.success ? [{ address: token.data }] : [];
         });
     });
-    if (holdings.length === 0)
+    // Correction starts as soon as discovery completes. Snapshot and fee-token
+    // cache misses continue concurrently until enrichment needs their results.
+    const correctedPromise = holdingsPromise.then(async (holdings) => {
+        if (holdings.length === 0)
+            return [];
+        const client = c.get('getClient')(chainId);
+        return Timing.time(c, 'balances_rpc', async () => {
+            // Concurrent reads enter viem's shared batch window and become one
+            // deployless multicall. A failed read fails the request rather than serving
+            // a stale or partial balance page.
+            const results = await Promise.all(holdings.map(async (holding) => {
+                const { amount } = await Actions.token.getBalance(client, {
+                    account: address,
+                    token: holding.address,
+                });
+                return amount === 0n ? undefined : { address: holding.address, amount: amount.toString() };
+            }));
+            const rows = results.filter((holding) => holding !== undefined);
+            rows.sort((a, b) => {
+                const delta = BigInt(b.amount) - BigInt(a.amount);
+                if (delta !== 0n)
+                    return delta > 0n ? 1 : -1;
+                return a.address < b.address ? -1 : a.address > b.address ? 1 : 0;
+            });
+            return rows;
+        });
+    });
+    const feeTokensPromise = feeEligible
+        ? Promise.resolve(feeTokens_filter)
+        : holdingsPromise.then((holdings) => holdings.length === 0 ? undefined : FeeAmm.feeTokenSet(c, chainId).catch(() => undefined));
+    const [holdings, snapshot, feeTokens, corrected] = await Promise.all([
+        holdingsPromise,
+        snapshotPromise,
+        feeTokensPromise,
+        correctedPromise,
+    ]);
+    if (holdings.length === 0) {
         return {
             data: [],
             ...(includeTotalCount ? { meta: { totalCount: 0, totalCountCapped: false } } : {}),
             nextCursor: null,
         };
-    const client = c.get('getClient')(chainId);
-    const corrected = await Timing.time(c, 'balances_rpc', async () => {
-        // Concurrent reads enter viem's shared batch window and become one
-        // deployless multicall. A failed read fails the request rather than serving
-        // a stale or partial balance page.
-        const results = await Promise.all(holdings.map(async (holding) => {
-            const { amount } = await Actions.token.getBalance(client, {
-                account: address,
-                token: holding.address,
-            });
-            return amount === 0n ? undefined : { address: holding.address, amount: amount.toString() };
-        }));
-        const rows = results.filter((holding) => holding !== undefined);
-        rows.sort((a, b) => {
-            const delta = BigInt(b.amount) - BigInt(a.amount);
-            if (delta !== 0n)
-                return delta > 0n ? 1 : -1;
-            return a.address < b.address ? -1 : a.address > b.address ? 1 : 0;
-        });
-        return rows;
-    });
+    }
     const positioned = (() => {
         if (!cursor)
             return corrected.slice(offset);
@@ -389,7 +425,7 @@ async function getAddressBalances(c, options) {
         limit,
         key: (holding) => [holding.amount, holding.address],
     });
-    if (page.rows.length === 0)
+    if (page.rows.length === 0) {
         return {
             data: [],
             ...(includeTotalCount
@@ -397,18 +433,31 @@ async function getAddressBalances(c, options) {
                 : {}),
             nextCursor: page.nextCursor,
         };
-    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,
-    });
+    }
+    const ratesPromise = denomination
+        ? Valuation.ratesFor(c, {
+            currencies: page.rows.flatMap((row) => {
+                const held = snapshot.byAddress.get(row.address.toLowerCase())?.currency;
+                return held === undefined ? [] : [held];
+            }),
+            denomination,
+            oracle,
+        })
+        : Promise.resolve(undefined);
     // Balance tokens retain their logo and verification metadata by default.
-    const resolved = await Timing.time(c, 'tokens', () => Promise.all(page.rows.map(async (holding) => {
+    const resolvedPromise = Timing.time(c, 'tokens', () => Promise.all(page.rows.map(async (holding) => {
         try {
             const token = Schema.Address.parse(holding.address.toLowerCase());
+            const verifiedToken = snapshot.byAddress.get(token);
+            // The curated list owns verified-token metadata, but uploaded logos live only in the asset store.
+            if (verifiedToken)
+                return {
+                    amount: holding.amount,
+                    logoUri: verifiedToken.logoUri ??
+                        (await Timing.time(c, 'token_logo', () => Tokens.getTokenLogo(c, { address: token, chainId })).catch(() => undefined)),
+                    metadata: verifiedToken,
+                    token,
+                };
             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 })),
@@ -419,6 +468,7 @@ async function getAddressBalances(c, options) {
             return undefined;
         }
     })));
+    const [rates, resolved] = await Promise.all([ratesPromise, resolvedPromise]);
     const data = [];
     for (const entry of resolved) {
         if (!entry)
@@ -442,12 +492,16 @@ async function getAddressBalances(c, options) {
                 symbol: entry.metadata.symbol,
                 verified: snapshot.byAddress.has(entry.token),
             },
-            valuation: Valuation.valuationFor({
-                amount: BigInt(entry.amount),
-                denomination,
-                rates,
-                token: snapshot.byAddress.get(entry.token),
-            }),
+            ...(denomination
+                ? {
+                    valuation: Valuation.valuationFor({
+                        amount: BigInt(entry.amount),
+                        denomination,
+                        rates,
+                        token: snapshot.byAddress.get(entry.token),
+                    }),
+                }
+                : {}),
         });
     }
     const meta = {