tapimo 0.5.2 → 0.6.0

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

@@ -1,5 +1,5 @@
 import { Hono, type Context } from 'hono'
-import { AbiEvent, type Hex } from 'ox'
+import { AbiError, AbiEvent, type Hex } from 'ox'
 import {
   type Address,
   BaseError,
@@ -7,7 +7,7 @@ import {
   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 type * as App from '../../../App.js'
@@ -22,12 +22,16 @@ 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.
@@ -71,6 +75,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' as const
+const exampleSourceToken = '0x20c0000000000000000000008f5425160ebe5525' as const
+const exampleApprovalCall = Actions.token.approve.call({
+  amount: 1_000_000n,
+  spender: Addresses.stablecoinDex,
+  token: exampleSourceToken,
+})
+const exampleSwapCall = Actions.dex.sell.call({
+  amountIn: 1_000_000n,
+  minAmountOut: 995_000n,
+  tokenIn: exampleSourceToken,
+  tokenOut: exampleBase,
+})
 
 /**
  * Tick spacing enforced by the stablecoin DEX precompile: orders must be
@@ -105,6 +121,14 @@ const maxDepthLevels = 200
  */
 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 = 10_000n
+
+const tokenFields = ['token.logoUri', 'token.verified'] as const
+
 /** Converts the OHLC `interval` enum to a millisecond duration. */
 function intervalMs(interval: '1m' | '5m' | '15m' | '1h' | '4h' | '1d'): number {
   switch (interval) {
@@ -211,6 +235,195 @@ export namespace schema {
     '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. */
+  export namespace createQuote {
+    const DestinationTokenAddress = Schema.tokenAddress(exampleBase)
+    const SourceTokenAddress = Schema.tokenAddress(exampleSourceToken)
+
+    /** Positive token amount accepted by the DEX's uint128 arguments. */
+    export const 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. */
+    export const Include = z
+      .enum(tokenFields)
+      .check(z.describe('Additional token fields to include in the quote response.'))
+
+    /** Parses comma-separated optional token fields. */
+    export const includeQuery = Schema.includeQuery(
+      Include,
+      'Comma-separated token fields to include, such as `token.logoUri,token.verified`.',
+    )
+
+    /** Query parameters selecting the Tempo chain and optional token fields. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        denomination: Schema.Denomination,
+        include: includeQuery,
+      })
+      .check(z.describe('Query parameters for creating a native DEX exchange quote.'))
+
+    /** Quote request with one pinned side and caller-selected slippage. */
+    export const Request = z
+      .strictObject({
+        amount: 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. */
+    export const 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(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. */
+    export const 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. */
+    export const 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(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(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.'))
+  }
+
   /** Schemas for the getPairs operation. */
   export namespace getPairs {
     /**
@@ -368,23 +581,15 @@ export namespace schema {
 
   /** Schemas for the getSwaps operation (the swap feed, optionally pair-scoped). */
   export namespace 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. */
     export const Include = z
-      .enum(['tokens'])
-      .check(z.describe('Related resource you can opt into with `include`.'))
+      .enum(tokenFields)
+      .check(z.describe('Additional token fields to include in swap responses.'))
 
-    /**
-     * 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.
-     */
+    /** Parses comma-separated optional token fields. */
     export const includeQuery = Schema.includeQuery(
       Include,
-      'Comma-separated optional resources to embed, e.g. `tokens`.',
+      'Comma-separated token fields to include, such as `token.logoUri,token.verified`.',
     )
 
     /** Query parameters for swap feed requests. */
@@ -394,6 +599,7 @@ export namespace schema {
         'blockNumber.to': Schema.blockNumberBound('swaps', 'to'),
         chainId: Schema.ChainIdQuery,
         cursor: Schema.Cursor,
+        denomination: Schema.Denomination,
         include: includeQuery,
         limit: Schema.Limit,
         maker: z
@@ -428,30 +634,19 @@ export namespace schema {
         ),
       )
 
-    /**
-     * 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.
-     */
-    export const SwapSide = z
-      .extend(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. */
+    export const 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. */
     export const Fill = z
       .object({
-        destinationToken: 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: SwapSide.check(z.describe('Token the taker received in this fill.')),
         logIndex: z
           .number()
           .check(
@@ -479,11 +674,8 @@ export namespace schema {
             ),
             z.meta({ examples: ['1.00000'] }),
           ),
-        sourceToken: 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: 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.'),
@@ -506,11 +698,10 @@ export namespace schema {
             z.describe('Block number where the swap was included.'),
             z.meta({ examples: [23456789] }),
           ),
-        destinationToken: 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: SwapSide.check(z.describe('Destination token for the final hop.')),
         filledAt: z.iso
           .datetime()
           .check(
@@ -564,9 +755,8 @@ export namespace schema {
               '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: 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: 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.'),
@@ -581,9 +771,26 @@ export namespace 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. */
+    export const 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.'))
+
     export const Response = z
       .object({
         data: z.array(Swap).check(z.describe('Swaps returned on this page.')),
+        meta: z
+          .optional(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.'))
@@ -1309,8 +1516,238 @@ export namespace 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: exchanges.Options = {}) {
+  const oracle = options.fx?.oracle ?? FxOracle.ecb()
   return new Hono<App.Environment>()
+    .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: bigint | string,
+            address: string,
+            token: { currency: string; decimals: number },
+          ) => ({
+            ...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 }),
@@ -1324,7 +1761,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.',
@@ -1335,11 +1772,10 @@ export function exchanges() {
         tags: ['Exchange'],
       }),
       Cache.response<App.Environment>({
-        // 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) => {
@@ -1353,10 +1789,8 @@ 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.
-        if (options.cursor !== undefined) Cache.setPolicy(c, Cache.policies.immutable)
+        // Cursor pages carry current valuations and curated verification data.
+        if (options.cursor !== undefined) Cache.setPolicy(c, Cache.policies.metadata)
 
         try {
           // The pair index (base address → pair) resolves each fill's book
@@ -1380,43 +1814,94 @@ export function exchanges() {
             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,
-            })
-            type Side = (typeof data)[number]['sourceToken']
-            const spread = <side extends Side>(side: side): 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: getSwaps.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) => ({
-              ...swap,
-              destinationToken: spread(swap.destinationToken),
-              fills: swap.fills.map((fill) => ({
-                ...fill,
-                destinationToken: spread(fill.destinationToken),
-                sourceToken: spread(fill.sourceToken),
-              })),
-              sourceToken: spread(swap.sourceToken),
-            }))
           }
+          const data = page.data.map((swap) => {
+            const destination = enrichSide(swap.destinationToken)
+            const source = enrichSide(swap.sourceToken)
+            return {
+              ...swap,
+              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)
         }
       },
@@ -1500,6 +1985,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)
@@ -1596,6 +2082,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)
@@ -1704,6 +2191,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)
@@ -2027,6 +2515,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)
@@ -2128,6 +2617,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)
@@ -2146,6 +2636,14 @@ export function exchanges() {
     )
 }
 
+export declare namespace exchanges {
+  /** Options for the exchange handlers. */
+  type Options = {
+    /** FX configuration backing amount valuation. */
+    fx?: Valuation.addresses.Fx | undefined
+  }
+}
+
 // Hard cap on the curated pair index. Pair creation is rare (one event per
 // pair lifetime), so a few thousand bounds today's set comfortably; raise this
 // if the index ever exhausts.
@@ -2169,34 +2667,62 @@ function pairNotFoundError(
   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: Context<App.Environment>,
   options: {
     addresses: readonly z.output<typeof Schema.Address>[]
     chainId: z.output<typeof Schema.ChainId>
+    include: readonly (typeof tokenFields)[number][]
   },
 ) {
-  const { addresses, chainId } = options
-  type Token = Awaited<ReturnType<typeof Tokens.resolveToken>>
+  const { addresses, chainId, include } = options
+  const includeLogoUri = include.includes('token.logoUri')
+  const includeVerified = include.includes('token.verified')
+  type Token = Omit<z.output<typeof Tokens.schema.Token>, 'verified'> & {
+    verified?: boolean | undefined
+  }
   const tokensByAddress = new Map<string, Token>()
   const uniqueTokens = [...new Set(addresses)]
   if (uniqueTokens.length === 0) return tokensByAddress
+  const snapshot =
+    includeLogoUri || includeVerified
+      ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+      : undefined
 
-  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] as const)
-          .catch(() => [token, undefined] as const),
-      ),
+      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,
+            },
+          ] as const
+        } catch {
+          return [token, undefined] as const
+        }
+      }),
     ),
   )
   for (const [token, metadata] of resolved) if (metadata) tokensByAddress.set(token, metadata)
@@ -2646,7 +3172,7 @@ async function getSwaps(c: Context<App.Environment>, options: getSwaps.Options)
       })
     }
 
-    type Candidate = { group: parseGroupRow.Group; swap: z.output<typeof schema.getSwaps.Swap> }
+    type Candidate = { group: parseGroupRow.Group; swap: getSwaps.Swap }
 
     // A row's keyset position is `(block, group first_idx, its first fill
     // logIndex)`; rows at or before the active cursor's row anchor were already
@@ -2949,6 +3475,36 @@ async function getSwaps(c: Context<App.Environment>, options: getSwaps.Options)
 }
 
 declare namespace getSwaps {
+  /** Swap side before RPC metadata and structured amount enrichment. */
+  type Side = {
+    address: z.output<typeof Schema.TokenAddress>
+    amount: z.output<typeof Schema.DecimalString>
+  }
+
+  /** Maker fill before RPC metadata and structured amount enrichment. */
+  type Fill = Omit<
+    z.output<typeof schema.getSwaps.Fill>,
+    'destinationAmount' | 'destinationToken' | 'sourceAmount' | 'sourceToken'
+  > & {
+    /** Destination token and raw base-unit amount. */
+    destinationToken: Side
+    /** Source token and raw base-unit amount. */
+    sourceToken: Side
+  }
+
+  /** Logical swap before RPC metadata and structured amount enrichment. */
+  type Swap = Omit<
+    z.output<typeof schema.getSwaps.Swap>,
+    'destinationAmount' | 'destinationToken' | 'fills' | 'sourceAmount' | 'sourceToken'
+  > & {
+    /** Destination token and raw base-unit amount. */
+    destinationToken: Side
+    /** Maker fills that compose this swap. */
+    fills: Fill[]
+    /** Source token and raw base-unit amount. */
+    sourceToken: Side
+  }
+
   /** Options for the swap page query. */
   type Options = {
     chainId: z.output<typeof Schema.ChainId>
@@ -3317,7 +3873,7 @@ declare namespace resolveSwapModes {
   type Options = {
     chainId: z.output<typeof Schema.ChainId>
     /** The final page's swap rows; `mode` is mutated in place. */
-    swaps: z.output<typeof schema.getSwaps.Swap>[]
+    swaps: getSwaps.Swap[]
   }
 }
 
@@ -3392,13 +3948,13 @@ declare namespace resolveBookQuotes {
 function buildSwapRows(
   group: parseGroupRow.Group,
   options: buildSwapRows.Options,
-): z.output<typeof schema.getSwaps.Swap>[] {
+): getSwaps.Swap[] {
   const { order, quoteByBase, states } = options
   const priceScale = BigInt(Tick.priceScale)
 
   type Oriented = {
     destination: { address: z.output<typeof Schema.TokenAddress>; amount: bigint }
-    fill: z.output<typeof schema.getSwaps.Fill>
+    fill: getSwaps.Fill
     source: { address: z.output<typeof Schema.TokenAddress>; amount: bigint }
   }
   const oriented: Oriented[] = []
@@ -3533,8 +4089,8 @@ declare namespace buildSwapRows {
     destination: z.output<typeof Schema.TokenAddress>
     /** Total received on this leg, in base units. */
     destinationAmount: bigint
-    /** The leg's fills (public shape). */
-    fills: z.output<typeof schema.getSwaps.Fill>[]
+    /** The leg's fills before metadata enrichment. */
+    fills: getSwaps.Fill[]
     /** Token the taker sent on this leg. */
     source: z.output<typeof Schema.TokenAddress>
     /** Total sent on this leg, in base units. */
@@ -4595,6 +5151,37 @@ function isOrderDoesNotExist(error: unknown): boolean {
   )
 }
 
+/** Returns the native DEX 404 used when no executable quote is available. */
+function quoteNotAvailable(c: Context<App.Environment>) {
+  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: unknown): boolean {
+  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: unknown): boolean {
+  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