tapimo 0.5.3 → 0.6.0

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

@@ -1,7 +1,7 @@
 import { Hono } from 'hono';
-import { AbiEvent } from 'ox';
+import { AbiError, AbiEvent } from 'ox';
 import { BaseError, ContractFunctionRevertedError, decodeFunctionData, parseAbi, } from 'viem';
-import { Actions, Addresses, Tick } from 'viem/tempo';
+import { Abis, Actions, Addresses, Tick } from 'viem/tempo';
 import * as z from 'zod/mini';
 import * as Auth from '../../../internal/Auth.js';
 import * as Cache from '../../../internal/Cache.js';
@@ -14,10 +14,13 @@ 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 FxOracle from '../FxOracle.js';
 import * as Tokens from './tokens.js';
+import * as Valuation from './valuation.js';
 // Stablecoin DEX precompile. Pair lifecycle is announced by `PairCreated` from
 // this address; the indexer pre-decodes those into the `dex_pairs` table.
 const stablecoinDex = Addresses.stablecoinDex.toLowerCase();
+const contractPausedSelector = AbiError.getSelector(AbiError.fromAbi(Abis.tip20, 'ContractPaused'));
 // `OrderCancelled(uint128 orderId)` — emitted when a maker cancels a resting
 // order. Used by the orders endpoint to exclude cancelled orders from the
 // resting set.
@@ -53,6 +56,18 @@ const swapAbi = parseAbi([
 // pathUSD on-chain). Uses a fresh `Schema.tokenAddress(...)` so the example
 // reaches the pipe input that path-param OpenAPI generation reads from.
 const exampleBase = '0x20c000000000000000000000b9537d11c60e8b50';
+const exampleSourceToken = '0x20c0000000000000000000008f5425160ebe5525';
+const exampleApprovalCall = Actions.token.approve.call({
+    amount: 1000000n,
+    spender: Addresses.stablecoinDex,
+    token: exampleSourceToken,
+});
+const exampleSwapCall = Actions.dex.sell.call({
+    amountIn: 1000000n,
+    minAmountOut: 995000n,
+    tokenIn: exampleSourceToken,
+    tokenOut: exampleBase,
+});
 /**
  * Tick spacing enforced by the stablecoin DEX precompile: orders must be
  * placed at ticks divisible by 10 (a 1 bp price grid). Walking the depth at
@@ -82,6 +97,11 @@ const maxDepthLevels = 200;
  * namespace because the OHLC `Query` refine references it at validation time.
  */
 const maxBuckets = 500;
+/** Largest amount accepted by the DEX precompile's uint128 swap arguments. */
+const maxSwapAmount = 2n ** 128n - 1n;
+/** Basis-point denominator used for caller-selected swap slippage. */
+const slippageDenominator = 10000n;
+const tokenFields = ['token.logoUri', 'token.verified'];
 /** Converts the OHLC `interval` enum to a millisecond duration. */
 function intervalMs(interval) {
     switch (interval) {
@@ -157,6 +177,126 @@ export var schema;
             .optional(z.boolean())
             .check(z.describe('Whether Tempo has verified this token metadata.'), z.meta({ examples: [true] })),
     }), 'One side of a trading pair (with metadata when requested via `include=tokens`).');
+    /** A token amount carrying its nominal value in the requested denomination. */
+    const ValuedAmount = z.extend(Schema.TokenAmount, {
+        valuation: z
+            .optional(z.nullable(Valuation.schema.Value))
+            .check(z.describe('The amount’s nominal value in the requested `denomination`. `null` when the token is ' +
+            'unverified, its display currency has no rate, or rates were unavailable.')),
+    });
+    /** Schemas for creating an executable native DEX exchange quote. */
+    let createQuote;
+    (function (createQuote) {
+        const DestinationTokenAddress = Schema.tokenAddress(exampleBase);
+        const SourceTokenAddress = Schema.tokenAddress(exampleSourceToken);
+        /** Positive token amount accepted by the DEX's uint128 arguments. */
+        createQuote.Amount = Schema.DecimalString.check(z.refine((value) => {
+            const amount = BigInt(value);
+            return amount > 0n && amount <= maxSwapAmount;
+        }, { error: 'Amount must be between 1 and the maximum uint128 value.' }), z.describe('Positive token amount in the token’s smallest unit, encoded as a decimal string.'), z.meta({ examples: ['1000000'] }));
+        /** Optional token fields that require sources beyond RPC metadata. */
+        createQuote.Include = z
+            .enum(tokenFields)
+            .check(z.describe('Additional token fields to include in the quote response.'));
+        /** Parses comma-separated optional token fields. */
+        createQuote.includeQuery = Schema.includeQuery(createQuote.Include, 'Comma-separated token fields to include, such as `token.logoUri,token.verified`.');
+        /** Query parameters selecting the Tempo chain and optional token fields. */
+        createQuote.Query = z
+            .strictObject({
+            chainId: Schema.ChainIdQuery,
+            denomination: Schema.Denomination,
+            include: createQuote.includeQuery,
+        })
+            .check(z.describe('Query parameters for creating a native DEX exchange quote.'));
+        /** Quote request with one pinned side and caller-selected slippage. */
+        createQuote.Request = z
+            .strictObject({
+            amount: createQuote.Amount.check(z.describe('Pinned amount in base units: source amount for `exactSource`, destination amount for `exactDestination`.')),
+            destinationToken: DestinationTokenAddress.check(z.describe('TIP-20 token the swap receives.')),
+            mode: z
+                .enum(['exactSource', 'exactDestination'])
+                .check(z.describe('Which side of the swap keeps the requested amount exact.'), z.meta({ examples: ['exactSource'] })),
+            slippageBps: z
+                .number()
+                .check(z.int(), z.gte(0), z.lt(10_000), z.describe('Allowed execution slippage in basis points, where 100 is 1%.'), z.meta({ examples: [50] })),
+            sourceToken: SourceTokenAddress.check(z.describe('TIP-20 token the swap spends.')),
+        })
+            .check(z.refine((request) => request.sourceToken !== request.destinationToken, {
+            error: 'Source and destination tokens must differ.',
+        }), z.describe('Request for an executable quote on Tempo’s native stablecoin DEX.'));
+        /** One call in the unsigned Tempo transaction plan. */
+        createQuote.Call = z
+            .object({
+            data: Schema.Hex.check(z.describe('ABI-encoded call data.')),
+            to: Schema.Address.check(z.describe('Contract or precompile that receives the call.')),
+            value: Schema.Quantity.check(z.describe('Native token value sent with the call; native DEX swap calls use `0x0`.'), z.meta({ examples: ['0x0'] })),
+        })
+            .check(z.describe('One unsigned call in the Tempo transaction plan.'));
+        const QuoteToken = Schema.describe(z.partial(z.omit(Tokens.schema.Token, { id: true }), {
+            logoUri: true,
+            verified: true,
+        }), 'A token referenced by an exchange quote, with RPC metadata and optional enrichments.');
+        const DestinationToken = z.extend(QuoteToken, {
+            address: DestinationTokenAddress.check(z.describe('TIP-20 token the swap receives.')),
+        });
+        const SourceToken = z.extend(QuoteToken, {
+            address: SourceTokenAddress.check(z.describe('TIP-20 token the swap spends.')),
+        });
+        const Transaction = z
+            .object({
+            calls: z.array(createQuote.Call).check(z.length(2), z.describe('Approval followed by the native DEX swap call.'), z.meta({
+                examples: [
+                    [
+                        {
+                            data: exampleApprovalCall.data,
+                            to: exampleApprovalCall.to,
+                            value: '0x0',
+                        },
+                        { data: exampleSwapCall.data, to: exampleSwapCall.to, value: '0x0' },
+                    ],
+                ],
+            })),
+            chainId: Schema.ChainId.check(z.describe('Tempo chain where these calls execute.')),
+        })
+            .check(z.describe('Unsigned Tempo transaction plan.'));
+        /** Response-level valuation rate provenance. */
+        createQuote.Meta = z
+            .object({
+            pricing: z
+                .optional(Valuation.schema.Pricing)
+                .check(z.describe('Rate provenance for amount valuations. Present when conversion rates were consulted.')),
+        })
+            .check(z.describe('Response-level resources attached to this quote.'));
+        /** Native DEX quote plus the approval and swap calls needed to execute it. */
+        createQuote.Response = z
+            .discriminatedUnion('mode', [
+            z.object({
+                destinationAmount: ValuedAmount.check(z.describe('Quoted destination amount.')),
+                destinationAmountMin: ValuedAmount.check(z.describe('Minimum destination amount after slippage.')),
+                destinationToken: DestinationToken,
+                meta: z.optional(createQuote.Meta).check(z.describe('Valuation rate provenance for this quote.')),
+                mode: z
+                    .literal('exactSource')
+                    .check(z.describe('The source amount is fixed and the destination has a minimum.'), z.meta({ examples: ['exactSource'] })),
+                sourceAmount: ValuedAmount.check(z.describe('Exact source amount.')),
+                sourceToken: SourceToken.check(z.describe('Token spent by the swap.')),
+                transaction: Transaction,
+            }),
+            z.object({
+                destinationAmount: ValuedAmount.check(z.describe('Exact destination amount.')),
+                destinationToken: DestinationToken.check(z.describe('Token received by the swap.')),
+                meta: z.optional(createQuote.Meta).check(z.describe('Valuation rate provenance for this quote.')),
+                mode: z
+                    .literal('exactDestination')
+                    .check(z.describe('The destination amount is fixed and the source has a maximum.'), z.meta({ examples: ['exactDestination'] })),
+                sourceAmount: ValuedAmount.check(z.describe('Quoted source amount.')),
+                sourceAmountMax: ValuedAmount.check(z.describe('Maximum source amount after slippage.')),
+                sourceToken: SourceToken,
+                transaction: Transaction,
+            }),
+        ])
+            .check(z.describe('Executable native DEX quote with slippage-protected calls.'));
+    })(createQuote = schema.createQuote || (schema.createQuote = {}));
     /** Schemas for the getPairs operation. */
     let getPairs;
     (function (getPairs) {
@@ -255,20 +395,12 @@ export var schema;
     /** Schemas for the getSwaps operation (the swap feed, optionally pair-scoped). */
     let getSwaps;
     (function (getSwaps) {
-        /**
-         * Optional related resource that callers opt into via `include`. Currently
-         * only `tokens` (embeds metadata for both pair tokens on each row's
-         * `sourceToken`/`destinationToken`).
-         */
+        /** Optional token fields that require sources beyond RPC metadata. */
         getSwaps.Include = z
-            .enum(['tokens'])
-            .check(z.describe('Related resource you can opt into with `include`.'));
-        /**
-         * Parses a comma-separated `include` query value into a list of optional
-         * resources to embed. Extra lookups (e.g. token metadata) only run when
-         * explicitly requested, keeping the base swap feed fast.
-         */
-        getSwaps.includeQuery = Schema.includeQuery(getSwaps.Include, 'Comma-separated optional resources to embed, e.g. `tokens`.');
+            .enum(tokenFields)
+            .check(z.describe('Additional token fields to include in swap responses.'));
+        /** Parses comma-separated optional token fields. */
+        getSwaps.includeQuery = Schema.includeQuery(getSwaps.Include, 'Comma-separated token fields to include, such as `token.logoUri,token.verified`.');
         /** Query parameters for swap feed requests. */
         getSwaps.Query = z
             .strictObject({
@@ -276,6 +408,7 @@ export var schema;
             'blockNumber.to': Schema.blockNumberBound('swaps', 'to'),
             chainId: Schema.ChainIdQuery,
             cursor: Schema.Cursor,
+            denomination: Schema.Denomination,
             include: getSwaps.includeQuery,
             limit: Schema.Limit,
             maker: z
@@ -297,20 +430,13 @@ export var schema;
             .check(z.describe('Query parameters for swap feed requests. Cursor-paginated only — a batched ' +
             'transaction expands one fill group into a variable number of swap rows, so a ' +
             'positional `page` has no stable meaning on this feed.'));
-        /**
-         * One side of a swap: a `PairToken` (address plus optional metadata when
-         * requested via `include=tokens`) annotated with the `amount` that moved
-         * on this side, as a decimal integer string in base units.
-         */
-        getSwaps.SwapSide = z
-            .extend(schema.PairToken, {
-            amount: Schema.DecimalString.check(z.describe('Amount moved on this side, returned as a decimal integer string in the token’s smallest units.'), z.meta({ examples: ['1000000'] })),
-        })
-            .check(z.describe('One side of a swap: the token and amount that moved.'));
+        /** One swap-side token with RPC metadata and optional curated fields. */
+        getSwaps.SwapSide = Schema.describe(Tokens.schema.TokenReference, 'A token referenced by one side of a swap.');
         /** A single maker-order fill within a swap, framed from the taker's perspective. */
         getSwaps.Fill = z
             .object({
-            destinationToken: getSwaps.SwapSide.check(z.describe('Token and amount the taker received in this fill, with token metadata when requested via `include=tokens`.')),
+            destinationAmount: ValuedAmount.check(z.describe('Amount the taker received in this fill.')),
+            destinationToken: getSwaps.SwapSide.check(z.describe('Token the taker received in this fill.')),
             logIndex: z
                 .number()
                 .check(z.int(), z.nonnegative(), z.describe('Log index of this fill within its block.'), z.meta({ examples: [0] })),
@@ -322,7 +448,8 @@ export var schema;
             price: z
                 .string()
                 .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Quote-per-base price at fill time, returned as a fixed-decimal string with 5 decimal places. This value is direction-independent and works well for charts.'), z.meta({ examples: ['1.00000'] })),
-            sourceToken: getSwaps.SwapSide.check(z.describe('Token and amount the taker sent in this fill, with token metadata when requested via `include=tokens`.')),
+            sourceAmount: ValuedAmount.check(z.describe('Amount the taker sent in this fill.')),
+            sourceToken: getSwaps.SwapSide.check(z.describe('Token the taker sent in this fill.')),
         })
             .check(z.describe('One maker-order fill within a swap, described from the taker’s perspective.'));
         /**
@@ -337,7 +464,8 @@ export var schema;
             blockNumber: z
                 .number()
                 .check(z.int(), z.nonnegative(), z.describe('Block number where the swap was included.'), z.meta({ examples: [23456789] })),
-            destinationToken: getSwaps.SwapSide.check(z.describe('Destination side of the swap: what the taker received, summed across the final hop.')),
+            destinationAmount: ValuedAmount.check(z.describe('Total amount the taker received in this swap.')),
+            destinationToken: getSwaps.SwapSide.check(z.describe('Destination token for the final hop.')),
             filledAt: z.iso
                 .datetime()
                 .check(z.describe('Block timestamp when the swap was filled onchain.'), z.meta({ examples: ['2024-01-01T00:00:00Z'] })),
@@ -359,7 +487,8 @@ export var schema;
             route: z
                 .array(Schema.TokenAddress)
                 .check(z.describe('Token path for the swap, from source through any intermediate tokens to destination. `route.length - 1` is the hop count; two entries means a direct swap.')),
-            sourceToken: getSwaps.SwapSide.check(z.describe('Source side of the swap: what the taker sent, summed across the first hop.')),
+            sourceAmount: ValuedAmount.check(z.describe('Total amount the taker sent in this swap.')),
+            sourceToken: getSwaps.SwapSide.check(z.describe('Source token for the first hop.')),
             taker: Schema.Address.check(z.describe('Taker address that initiated the swap.')),
             transactionHash: Schema.Hash.check(z.describe('Transaction hash for the transaction containing the swap.')),
         })
@@ -371,9 +500,21 @@ export var schema;
          * rows per page; a transaction batching several unrelated swaps by one
          * taker may have its rows split across consecutive pages.
          */
+        /** Page-level resources: valuation rate provenance. */
+        getSwaps.Meta = z
+            .object({
+            pricing: z
+                .optional(Valuation.schema.Pricing)
+                .check(z.describe('Rate provenance for amount valuations. Present when conversion rates were ' +
+                'consulted; absent when every value was identity-valued or rates were unavailable.')),
+        })
+            .check(z.describe('Page-level resources attached to this response.'));
         getSwaps.Response = z
             .object({
             data: z.array(getSwaps.Swap).check(z.describe('Swaps returned on this page.')),
+            meta: z
+                .optional(getSwaps.Meta)
+                .check(z.describe('Page-level resources, such as valuation rate provenance.')),
             nextCursor: Schema.NextCursor,
         })
             .check(z.describe('A paginated list of swaps on Tempo’s built-in stablecoin exchange.'));
@@ -802,8 +943,206 @@ export var schema;
  *   `token_balances_snapshot` row attribute cleanly to one pair. Pairs whose
  *   DEX-escrow balance is zero are excluded from the liquidity ranking.
  */
-export function exchanges() {
+export function exchanges(options = {}) {
+    const oracle = options.fx?.oracle ?? FxOracle.ecb();
     return new Hono()
+        .post('/v1/exchange/quotes', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('query', schema.createQuote.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.validate('json', schema.createQuote.Request, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+    }), OpenApi.describeRoute({
+        description: 'Creates a priced exchange preview on Tempo’s native stablecoin DEX with unsigned approval and swap calls. This endpoint does not submit a transaction.',
+        operationId: 'createExchangeQuote',
+        responses: OpenApi.responses({
+            errors: {
+                400: { codes: ['body_invalid', 'query_invalid', 'quote_amount_out_of_range'] },
+                404: {
+                    codes: ['quote_not_available'],
+                    description: 'The native DEX cannot price an executable exchange for these terms.',
+                },
+                502: 'The Tempo RPC could not quote the swap or resolve token metadata.',
+            },
+            success: {
+                description: 'A native DEX quote and the unsigned calls needed to execute it.',
+                schema: schema.createQuote.Response,
+            },
+        }),
+        summary: 'Create quote',
+        tags: ['Exchange'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid query parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'body_invalid',
+                message: 'Invalid request body',
+            });
+        const request = c.req.valid('json');
+        const options = c.req.valid('query');
+        const chainId = options.chainId ?? c.get('chainId');
+        const client = c.get('getClient')(chainId);
+        const amount = BigInt(request.amount);
+        const slippageBps = BigInt(request.slippageBps);
+        c.header('Cache-Control', 'no-store');
+        try {
+            // Value quoted amounts via their curated display currency; snapshot
+            // or rate failures degrade the values to `null`, never the quote.
+            const denomination = options.denomination ?? 'USD';
+            const snapshot = await VerifiedTokens.snapshot(c, chainId).catch(() => undefined);
+            const rates = await Valuation.ratesFor(c, {
+                currencies: snapshot
+                    ? [request.destinationToken, request.sourceToken].flatMap((address) => {
+                        const held = snapshot.byAddress.get(address.toLowerCase())?.currency;
+                        return held === undefined ? [] : [held];
+                    })
+                    : [],
+                denomination,
+                oracle,
+            });
+            const valued = (baseUnits, address, token) => ({
+                ...Value.tokenAmount({
+                    baseUnits,
+                    currency: token.currency,
+                    decimals: token.decimals,
+                }),
+                valuation: Valuation.valuationFor({
+                    amount: BigInt(baseUnits),
+                    denomination,
+                    rates,
+                    token: snapshot?.byAddress.get(address.toLowerCase()),
+                }),
+            });
+            if (request.mode === 'exactSource') {
+                const destinationAmount = await Actions.dex.getSellQuote(client, {
+                    amountIn: amount,
+                    tokenIn: request.sourceToken,
+                    tokenOut: request.destinationToken,
+                });
+                if (destinationAmount === 0n)
+                    return quoteNotAvailable(c);
+                const minimumAmount = (destinationAmount * (slippageDenominator - slippageBps) + slippageDenominator - 1n) /
+                    slippageDenominator;
+                const approve = Actions.token.approve.call(client, {
+                    amount,
+                    spender: Addresses.stablecoinDex,
+                    token: request.sourceToken,
+                });
+                const swap = Actions.dex.sell.call({
+                    amountIn: amount,
+                    minAmountOut: minimumAmount,
+                    tokenIn: request.sourceToken,
+                    tokenOut: request.destinationToken,
+                });
+                const tokensByAddress = await resolveTokensByAddress(c, {
+                    addresses: [request.destinationToken, request.sourceToken],
+                    chainId,
+                    include: options.include,
+                });
+                const destinationToken = tokensByAddress.get(request.destinationToken);
+                const sourceToken = tokensByAddress.get(request.sourceToken);
+                if (!destinationToken || !sourceToken)
+                    throw new Error('Unable to resolve exchange quote token metadata');
+                return c.json(Response.validated(schema.createQuote.Response, {
+                    destinationAmount: valued(destinationAmount, request.destinationToken, destinationToken),
+                    destinationAmountMin: valued(minimumAmount, request.destinationToken, destinationToken),
+                    destinationToken: {
+                        ...destinationToken,
+                        address: request.destinationToken,
+                    },
+                    ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+                    mode: request.mode,
+                    sourceAmount: valued(request.amount, request.sourceToken, sourceToken),
+                    sourceToken: {
+                        ...sourceToken,
+                        address: request.sourceToken,
+                    },
+                    transaction: {
+                        calls: [
+                            { data: approve.data, to: approve.to, value: '0x0' },
+                            { data: swap.data, to: swap.to, value: '0x0' },
+                        ],
+                        chainId,
+                    },
+                }), 200);
+            }
+            const sourceAmount = await Actions.dex.getBuyQuote(client, {
+                amountOut: amount,
+                tokenIn: request.sourceToken,
+                tokenOut: request.destinationToken,
+            });
+            if (sourceAmount === 0n)
+                return quoteNotAvailable(c);
+            const maximumAmount = (sourceAmount * (slippageDenominator + slippageBps)) / slippageDenominator;
+            if (maximumAmount > maxSwapAmount)
+                return Response.error(c, {
+                    code: 'quote_amount_out_of_range',
+                    message: 'Slippage-adjusted source amount exceeds the native DEX limit',
+                    status: 400,
+                });
+            const approve = Actions.token.approve.call(client, {
+                amount: maximumAmount,
+                spender: Addresses.stablecoinDex,
+                token: request.sourceToken,
+            });
+            const swap = Actions.dex.buy.call({
+                amountOut: amount,
+                maxAmountIn: maximumAmount,
+                tokenIn: request.sourceToken,
+                tokenOut: request.destinationToken,
+            });
+            const tokensByAddress = await resolveTokensByAddress(c, {
+                addresses: [request.destinationToken, request.sourceToken],
+                chainId,
+                include: options.include,
+            });
+            const destinationToken = tokensByAddress.get(request.destinationToken);
+            const sourceToken = tokensByAddress.get(request.sourceToken);
+            if (!destinationToken || !sourceToken)
+                throw new Error('Unable to resolve exchange quote token metadata');
+            return c.json(Response.validated(schema.createQuote.Response, {
+                destinationAmount: valued(request.amount, request.destinationToken, destinationToken),
+                destinationToken: {
+                    ...destinationToken,
+                    address: request.destinationToken,
+                },
+                ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+                mode: request.mode,
+                sourceAmount: valued(sourceAmount, request.sourceToken, sourceToken),
+                sourceAmountMax: valued(maximumAmount, request.sourceToken, sourceToken),
+                sourceToken: {
+                    ...sourceToken,
+                    address: request.sourceToken,
+                },
+                transaction: {
+                    calls: [
+                        { data: approve.data, to: approve.to, value: '0x0' },
+                        { data: swap.data, to: swap.to, value: '0x0' },
+                    ],
+                    chainId,
+                },
+            }), 200);
+        }
+        catch (cause) {
+            if (request.mode === 'exactSource' && isQuoteAmountOutOfRange(cause))
+                return Response.error(c, {
+                    code: 'quote_amount_out_of_range',
+                    message: 'Quote amount exceeds the native DEX limit',
+                    status: 400,
+                });
+            if (isQuoteUnavailable(cause))
+                return quoteNotAvailable(c);
+            if (cause instanceof Valuation.UnsupportedDenominationError)
+                return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 });
+            return Response.upstream(c, cause);
+        }
+    })
         .get('/v1/exchange/swaps', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('query', schema.getSwaps.Query, {
         code: 'query_invalid',
         message: 'Invalid query parameters',
@@ -812,7 +1151,7 @@ export function exchanges() {
         operationId: 'getSwaps',
         responses: OpenApi.responses({
             errors: {
-                502: 'The indexer could not serve the exchange data right now.',
+                502: 'The indexer or Tempo RPC could not serve the exchange data right now.',
             },
             success: {
                 description: 'A page of swaps from Tempo’s built-in stablecoin exchange.',
@@ -822,11 +1161,10 @@ export function exchanges() {
         summary: 'List swaps',
         tags: ['Exchange'],
     }), Cache.response({
-        // Exchanges are a newest-first feed; refresh quickly. The `v2` cache
-        // segment isolates the swap-level row shape from previously cached
-        // per-fill pages (cursor pages cache as `immutable`).
+        // Exchanges are a newest-first feed; refresh quickly. The `v3` cache
+        // segment isolates this response shape from earlier swap pages.
         cacheControl: Cache.policies.feed,
-        name: 'tempo-api:exchange:v2:swaps',
+        name: 'tempo-api:exchange:v3:swaps',
         key: (c) => Cache.urlKey(c, schema.getSwaps.Query),
     }), async (c) => {
         if (Auth.narrowAccess)
@@ -838,11 +1176,9 @@ export function exchanges() {
             });
         const options = c.req.valid('query');
         const chainId = options.chainId ?? c.get('chainId');
-        // Cursor pages anchor below the head and are effectively immutable, so
-        // upgrade their cache policy; the head page keeps the route's `feed`
-        // default.
+        // Cursor pages carry current valuations and curated verification data.
         if (options.cursor !== undefined)
-            Cache.setPolicy(c, Cache.policies.immutable);
+            Cache.setPolicy(c, Cache.policies.metadata);
         try {
             // The pair index (base address → pair) resolves each fill's book
             // orientation (the order events only carry the base-side `token`;
@@ -863,39 +1199,89 @@ export function exchanges() {
                 toTimestamp: options['timestamp.to'],
                 transactionHash: options.transactionHash,
             });
-            // Token metadata is opt-in. Collect every token address across the
-            // page (`route` spans each swap's source, intermediates, and
-            // destination — a superset of every fill side) and resolve each
-            // once, then spread it onto the swap-level sides and every fill
-            // side. Resolution is best-effort: a token whose metadata is
-            // unavailable keeps just `address`/`amount`.
-            let data = page.data;
-            if (options.include.includes('tokens') && data.length > 0) {
-                const tokensByAddress = await resolveTokensByAddress(c, {
-                    addresses: data.flatMap((swap) => swap.route),
-                    chainId,
-                });
-                const spread = (side) => {
-                    const token = tokensByAddress.get(side.address);
-                    return token ? { ...side, ...token } : side;
+            // `route` spans every swap and fill side, so one lookup resolves each
+            // token once for required RPC metadata and requested curated fields.
+            const tokensByAddress = await resolveTokensByAddress(c, {
+                addresses: page.data.flatMap((swap) => swap.route),
+                chainId,
+                include: options.include,
+            });
+            // Value amounts via their curated display currency; snapshot or rate
+            // failures degrade the values to `null`, never the feed.
+            const denomination = options.denomination ?? 'USD';
+            const snapshot = page.data.length > 0
+                ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+                : undefined;
+            const rates = await Valuation.ratesFor(c, {
+                currencies: snapshot
+                    ? page.data.flatMap((swap) => swap.route.flatMap((address) => {
+                        const held = snapshot.byAddress.get(address.toLowerCase())?.currency;
+                        return held === undefined ? [] : [held];
+                    }))
+                    : [],
+                denomination,
+                oracle,
+            });
+            const enrichSide = (side) => {
+                const token = tokensByAddress.get(side.address);
+                if (!token)
+                    throw new Error(`Token metadata unavailable for ${side.address}`);
+                return {
+                    amount: {
+                        ...Value.tokenAmount({
+                            baseUnits: side.amount,
+                            currency: token.currency,
+                            decimals: token.decimals,
+                        }),
+                        valuation: Valuation.valuationFor({
+                            amount: BigInt(side.amount),
+                            denomination,
+                            rates,
+                            token: snapshot?.byAddress.get(side.address.toLowerCase()),
+                        }),
+                    },
+                    token: {
+                        address: side.address,
+                        currency: token.currency,
+                        decimals: token.decimals,
+                        ...(token.logoUri !== undefined ? { logoUri: token.logoUri } : {}),
+                        name: token.name,
+                        symbol: token.symbol,
+                        ...(token.verified !== undefined ? { verified: token.verified } : {}),
+                    },
                 };
-                data = data.map((swap) => ({
+            };
+            const data = page.data.map((swap) => {
+                const destination = enrichSide(swap.destinationToken);
+                const source = enrichSide(swap.sourceToken);
+                return {
                     ...swap,
-                    destinationToken: spread(swap.destinationToken),
-                    fills: swap.fills.map((fill) => ({
-                        ...fill,
-                        destinationToken: spread(fill.destinationToken),
-                        sourceToken: spread(fill.sourceToken),
-                    })),
-                    sourceToken: spread(swap.sourceToken),
-                }));
-            }
+                    destinationAmount: destination.amount,
+                    destinationToken: destination.token,
+                    fills: swap.fills.map((fill) => {
+                        const destination_fill = enrichSide(fill.destinationToken);
+                        const source_fill = enrichSide(fill.sourceToken);
+                        return {
+                            ...fill,
+                            destinationAmount: destination_fill.amount,
+                            destinationToken: destination_fill.token,
+                            sourceAmount: source_fill.amount,
+                            sourceToken: source_fill.token,
+                        };
+                    }),
+                    sourceAmount: source.amount,
+                    sourceToken: source.token,
+                };
+            });
             return c.json(Response.validated(schema.getSwaps.Response, {
                 data,
+                ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
                 nextCursor: page.nextCursor,
             }), 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);
         }
     })
@@ -969,6 +1355,7 @@ export function exchanges() {
                 const tokensByAddress = await resolveTokensByAddress(c, {
                     addresses: data.flatMap((pair) => [pair.base.address, pair.quote.address]),
                     chainId,
+                    include: tokenFields,
                 });
                 data = data.map((pair) => {
                     const base = tokensByAddress.get(pair.base.address);
@@ -1053,6 +1440,7 @@ export function exchanges() {
                 const tokensByAddress = await resolveTokensByAddress(c, {
                     addresses: [target.base, target.quote],
                     chainId,
+                    include: tokenFields,
                 });
                 const baseMeta = tokensByAddress.get(target.base);
                 const quoteMeta = tokensByAddress.get(target.quote);
@@ -1150,6 +1538,7 @@ export function exchanges() {
                 const tokensByAddress = await resolveTokensByAddress(c, {
                     addresses: data.flatMap((o) => [o.pair.base.address, o.pair.quote.address]),
                     chainId,
+                    include: tokenFields,
                 });
                 data = data.map((o) => {
                     const base = tokensByAddress.get(o.pair.base.address);
@@ -1429,6 +1818,7 @@ export function exchanges() {
                 const tokensByAddress = await resolveTokensByAddress(c, {
                     addresses: [target.base, target.quote],
                     chainId,
+                    include: tokenFields,
                 });
                 const baseMeta = tokensByAddress.get(target.base);
                 const quoteMeta = tokensByAddress.get(target.quote);
@@ -1519,6 +1909,7 @@ export function exchanges() {
                 const tokensByAddress = await resolveTokensByAddress(c, {
                     addresses: [target.base, target.quote],
                     chainId,
+                    include: tokenFields,
                 });
                 const baseMeta = tokensByAddress.get(target.base);
                 const quoteMeta = tokensByAddress.get(target.quote);
@@ -1552,23 +1943,46 @@ function pairNotFoundError(c, options) {
         : 'Pair not found';
     return Response.error(c, { code: 'pair_not_found', message, status: 404 });
 }
-/**
- * Batch-resolves token metadata for a set of addresses, sharing one
- * verified-token snapshot and one created-at lookup across the whole set.
- * Best-effort: addresses whose metadata cannot be resolved are absent from
- * the returned map, so callers keep their bare `{ address }` shapes. Shared
- * by every `include=tokens` embed in this module.
- */
+/** Resolves RPC token metadata and explicitly requested enrichments. Unresolvable addresses are omitted. */
 async function resolveTokensByAddress(c, options) {
-    const { addresses, chainId } = options;
+    const { addresses, chainId, include } = options;
+    const includeLogoUri = include.includes('token.logoUri');
+    const includeVerified = include.includes('token.verified');
     const tokensByAddress = new Map();
     const uniqueTokens = [...new Set(addresses)];
     if (uniqueTokens.length === 0)
         return tokensByAddress;
-    const snapshot = await VerifiedTokens.snapshot(c, chainId);
-    const resolved = await Timing.time(c, 'tokens', () => Promise.all(uniqueTokens.map((token) => Tokens.resolveToken(c, { address: token, chainId, snapshot })
-        .then((metadata) => [token, metadata])
-        .catch(() => [token, undefined]))));
+    const snapshot = includeLogoUri || includeVerified
+        ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+        : undefined;
+    const resolved = await Timing.time(c, 'tokens', () => Promise.all(uniqueTokens.map(async (token) => {
+        try {
+            const [logoUri, metadata] = await Promise.all([
+                includeLogoUri
+                    ? Timing.time(c, 'token_logo', () => Tokens.getTokenLogo(c, { address: token, chainId })).catch(() => undefined)
+                    : undefined,
+                Timing.time(c, 'token_metadata', () => Tokens.getTokenMetadata(c, { address: token, chainId })),
+            ]);
+            return [
+                token,
+                {
+                    address: token,
+                    currency: metadata.currency,
+                    decimals: metadata.decimals,
+                    id: token,
+                    logoUri: includeLogoUri
+                        ? (logoUri ?? snapshot?.byAddress.get(token)?.logoUri ?? metadata.logoUri)
+                        : undefined,
+                    name: metadata.name,
+                    symbol: metadata.symbol,
+                    verified: includeVerified ? snapshot?.byAddress.has(token) : undefined,
+                },
+            ];
+        }
+        catch {
+            return [token, undefined];
+        }
+    })));
     for (const [token, metadata] of resolved)
         if (metadata)
             tokensByAddress.set(token, metadata);
@@ -3438,6 +3852,34 @@ function isOrderDoesNotExist(error) {
     return (revert instanceof ContractFunctionRevertedError &&
         revert.data?.errorName === 'OrderDoesNotExist');
 }
+/** Returns the native DEX 404 used when no executable quote is available. */
+function quoteNotAvailable(c) {
+    return Response.error(c, {
+        code: 'quote_not_available',
+        message: 'No executable quote is available on Tempo’s native DEX',
+        status: 404,
+    });
+}
+/** Distinguishes native DEX route failures from RPC transport failures. */
+function isQuoteUnavailable(error) {
+    if (!(error instanceof BaseError))
+        return false;
+    const revert = error.walk((e) => e instanceof ContractFunctionRevertedError);
+    if (!(revert instanceof ContractFunctionRevertedError))
+        return false;
+    return (revert.raw === contractPausedSelector ||
+        ['InsufficientLiquidity', 'InvalidBaseToken', 'InvalidToken', 'PairDoesNotExist'].includes(revert.data?.errorName ?? ''));
+}
+/** Detects uint128 arithmetic overflow from exact-source DEX quote calls. */
+function isQuoteAmountOutOfRange(error) {
+    if (!(error instanceof BaseError))
+        return false;
+    const revert = error.walk((e) => e instanceof ContractFunctionRevertedError);
+    if (!(revert instanceof ContractFunctionRevertedError))
+        return false;
+    const data = revert.data;
+    return data?.errorName === 'Panic' && data.args?.[0] === 0x11n;
+}
 /**
  * Resolves a single page of `OrderFilled` events for one order. Pagination is
  * keyset on `(block_num, log_idx)`, which is unique and append-only for the