tapimo 0.7.0 → 0.7.2

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

@@ -6,6 +6,7 @@ import {
   ContractFunctionRevertedError,
   decodeFunctionData,
   parseAbi,
+  parseEventLogs,
 } from 'viem'
 import { Abis, Actions, Addresses, Tick } from 'viem/tempo'
 import * as z from 'zod/mini'
@@ -14,6 +15,7 @@ import type * as App from '../../../App.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as Cache from '../../../internal/Cache.js'
 import * as Cursor from '../../../internal/Cursor.js'
+import * as ExchangeProvider from '../../../internal/exchange/Provider.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
@@ -22,6 +24,7 @@ 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 type * as Viem from '../../../internal/Viem.js'
 import * as FxOracle from '../FxOracle.js'
 import * as Tokens from './tokens.js'
 import * as Valuation from './valuation.js'
@@ -32,6 +35,9 @@ const stablecoinDex = Addresses.stablecoinDex.toLowerCase()
 
 const contractPausedSelector = AbiError.getSelector(AbiError.fromAbi(Abis.tip20, 'ContractPaused'))
 
+/** Largest amount accepted by TIP-20 and external uint256 provider contracts. */
+const maxProviderAmount = 2n ** 256n - 1n
+
 // `OrderCancelled(uint128 orderId)` — emitted when a maker cancels a resting
 // order. Used by the orders endpoint to exclude cancelled orders from the
 // resting set.
@@ -241,25 +247,25 @@ export namespace schema {
       .optional(z.nullable(Valuation.schema.Value))
       .check(
         z.describe(
-          'The amount’s nominal value in the requested `denomination`. `null` when the token is ' +
+          'The amount’s nominal value in the requested `valuation.currency`. `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. */
+  /** Schemas for creating an executable 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. */
+    /** Positive token amount accepted by exchange providers. */
     export const Amount = Schema.DecimalString.check(
       z.refine(
         (value) => {
           const amount = BigInt(value)
-          return amount > 0n && amount <= maxSwapAmount
+          return amount > 0n && amount <= maxProviderAmount
         },
-        { error: 'Amount must be between 1 and the maximum uint128 value.' },
+        { error: 'Amount must be a positive uint256.' },
       ),
       z.describe(
         'Positive token amount in the token’s smallest unit, encoded as a decimal string.',
@@ -282,14 +288,20 @@ export namespace schema {
     export const Query = z
       .strictObject({
         chainId: Schema.ChainIdQuery,
-        denomination: Schema.Denomination,
         include: includeQuery,
+        'valuation.currency': Schema.Denomination,
       })
-      .check(z.describe('Query parameters for creating a native DEX exchange quote.'))
+      .check(z.describe('Query parameters for creating an exchange quote.'))
 
     /** Quote request with one pinned side and caller-selected slippage. */
     export const Request = z
       .strictObject({
+        account: z
+          .optional(Schema.Address)
+          .check(
+            z.describe('Wallet that will sign and execute the swap.'),
+            z.meta({ examples: ['0x1111111111111111111111111111111111111111'] }),
+          ),
         amount: Amount.check(
           z.describe(
             'Pinned amount in base units: source amount for `exactSource`, destination amount for `exactDestination`.',
@@ -319,16 +331,22 @@ export namespace schema {
         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.'),
+        z.describe('Request for an executable quote from the configured exchange providers.'),
       )
 
     /** 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.')),
+        data: Schema.Hex.check(
+          z.describe('ABI-encoded call data.'),
+          z.meta({ examples: ['0x095ea7b3'] }),
+        ),
+        to: Schema.Address.check(
+          z.describe('Contract or precompile that receives the call.'),
+          z.meta({ examples: [Addresses.stablecoinDex] }),
+        ),
         value: Schema.Quantity.check(
-          z.describe('Native token value sent with the call; native DEX swap calls use `0x0`.'),
+          z.describe('Native token value sent with the call.'),
           z.meta({ examples: ['0x0'] }),
         ),
       })
@@ -350,11 +368,11 @@ export namespace schema {
       address: SourceTokenAddress.check(z.describe('TIP-20 token the swap spends.')),
     })
 
-    const Transaction = z
+    export const Transaction = z
       .object({
         calls: z.array(Call).check(
-          z.length(2),
-          z.describe('Approval followed by the native DEX swap call.'),
+          z.minLength(1),
+          z.describe('Calls to execute in order.'),
           z.meta({
             examples: [
               [
@@ -375,7 +393,7 @@ export namespace schema {
     /** Response-level valuation rate provenance. */
     export const Meta = z
       .object({
-        pricing: z
+        valuation: z
           .optional(Valuation.schema.Pricing)
           .check(
             z.describe(
@@ -385,43 +403,225 @@ export namespace schema {
       })
       .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'] }),
+    /** Provider-neutral EIP-712 payload to sign before finalizing a quote. */
+    export const TypedData = z
+      .object({
+        domain: z.record(z.string(), z.unknown()).check(
+          z.describe('EIP-712 signing domain.'),
+          z.meta({
+            examples: [
+              {
+                chainId: 4217,
+                name: 'Permit2',
+                verifyingContract: '0x000000000022d473030f116ddee9f6b43ac78ba3',
+              },
+            ],
+          }),
+        ),
+        message: z.record(z.string(), z.unknown()).check(
+          z.describe('Values encoded by the primary EIP-712 type.'),
+          z.meta({
+            examples: [
+              {
+                details: {
+                  amount: '1000000',
+                  expiration: '4102444800',
+                  nonce: '0',
+                  token: exampleSourceToken,
+                },
+                sigDeadline: '4102444800',
+                spender: '0x1febb76be10aaf3a1402f04e8e835f2c382f7914',
+              },
+            ],
+          }),
+        ),
+        primaryType: z
+          .string()
+          .check(z.minLength(1))
+          .check(z.describe('Root EIP-712 type.'), z.meta({ examples: ['PermitSingle'] })),
+        types: z
+          .record(
+            z.string(),
+            z.array(
+              z.strictObject({
+                name: z.string(),
+                type: z.string(),
+              }),
             ),
-          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('EIP-712 type definitions keyed by type name.'),
+            z.meta({
+              examples: [
+                {
+                  PermitDetails: [
+                    { name: 'token', type: 'address' },
+                    { name: 'amount', type: 'uint160' },
+                    { name: 'expiration', type: 'uint48' },
+                    { name: 'nonce', type: 'uint48' },
+                  ],
+                  PermitSingle: [
+                    { name: 'details', type: 'PermitDetails' },
+                    { name: 'spender', type: 'address' },
+                    { name: 'sigDeadline', type: 'uint256' },
+                  ],
+                },
+              ],
+            }),
+          ),
+      })
+      .check(z.describe('EIP-712 payload the wallet must sign before execution can continue.'))
+
+    const Provider = z
+      .string()
+      .check(z.describe('Provider selected for this route.'), z.meta({ examples: ['nativeDex'] }))
+
+    const Quote = {
+      gasEstimate: Schema.DecimalString.check(
+        z.describe('Estimated network fee in the chain native token’s base unit.'),
+        z.meta({ examples: ['150000000000000'] }),
+      ),
+      provider: Provider,
+    }
+
+    const ApprovalRequired = {
+      approval: z.object({
+        calls: z.array(Call).check(
+          z.minLength(1),
+          z.describe('Approval calls to confirm before requesting a fresh quote.'),
+          z.meta({
+            examples: [
+              [
+                {
+                  data: exampleApprovalCall.data,
+                  to: exampleApprovalCall.to,
+                  value: '0x0',
+                },
+              ],
+            ],
+          }),
+        ),
+      }),
+      status: z
+        .literal('approvalRequired')
+        .check(
+          z.describe('Confirm the approvals, then request a fresh quote.'),
+          z.meta({ examples: ['approvalRequired'] }),
+        ),
+    }
+
+    const Ready = {
+      status: z
+        .literal('ready')
+        .check(
+          z.describe('The returned calls can be executed now.'),
+          z.meta({ examples: ['ready'] }),
+        ),
+      transaction: Transaction,
+    }
+
+    const SignatureRequired = {
+      continuation: z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe('Opaque state supplied to the finalization endpoint within 30 seconds.'),
+          z.meta({ examples: ['eyJwcm92aWRlciI6InVuaXN3YXAifQ'] }),
+        ),
+      status: z
+        .literal('signatureRequired')
+        .check(
+          z.describe('Sign the typed data before final calldata can be built.'),
+          z.meta({ examples: ['signatureRequired'] }),
+        ),
+      typedData: TypedData,
+    }
+
+    const ExactSource = {
+      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.')),
+    }
+
+    const ExactDestination = {
+      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,
+    }
+
+    /** Provider-neutral quote and the action needed to execute it. */
+    export const Response = z
+      .union([
+        z.object({ ...ApprovalRequired, ...ExactSource, ...Quote }),
+        z.object({ ...ExactSource, ...Quote, ...Ready }),
+        z.object({ ...ExactSource, ...Quote, ...SignatureRequired }),
+        z.object({ ...ApprovalRequired, ...ExactDestination, ...Quote }),
+        z.object({ ...ExactDestination, ...Quote, ...Ready }),
+        z.object({ ...ExactDestination, ...Quote, ...SignatureRequired }),
       ])
-      .check(z.describe('Executable native DEX quote with slippage-protected calls.'))
+      .check(z.describe('Provider-neutral exchange quote with its next execution action.'))
+  }
+
+  /** Schemas for finishing a quote after a provider-requested signature. */
+  export namespace executeQuote {
+    /** Signed continuation request. */
+    export const Request = z.strictObject({
+      account: Schema.Address.check(
+        z.describe('Wallet that signed and will execute the swap.'),
+        z.meta({ examples: ['0x1111111111111111111111111111111111111111'] }),
+      ),
+      continuation: z
+        .string()
+        .check(
+          z.minLength(1),
+          z.maxLength(100_000),
+          z.describe('Opaque state returned by the quote request.'),
+          z.meta({ examples: ['eyJwcm92aWRlciI6InVuaXN3YXAifQ'] }),
+        ),
+      provider: z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe('Provider that issued the continuation.'),
+          z.meta({ examples: ['uniswap'] }),
+        ),
+      signature: Schema.Hex.check(
+        z.refine((value) => value.length === 132, { error: 'Signature must be 65 bytes.' }),
+        z.describe('65-byte EIP-712 signature requested by the quote.'),
+        z.meta({ examples: [`0x${'11'.repeat(65)}`] }),
+      ),
+    })
+
+    /** Final transaction plan. */
+    export const Response = z.object({
+      provider: z
+        .string()
+        .check(
+          z.describe('Provider that built the transaction.'),
+          z.meta({ examples: ['uniswap'] }),
+        ),
+      transaction: createQuote.Transaction,
+    })
   }
 
   /** Schemas for the getPairs operation. */
@@ -599,7 +799,6 @@ 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
@@ -625,6 +824,7 @@ export namespace schema {
         transactionHash: z
           .optional(Schema.Hash)
           .check(z.describe('Only include swaps included in this transaction hash.')),
+        'valuation.currency': Schema.Denomination,
       })
       .check(
         z.describe(
@@ -774,7 +974,7 @@ export namespace schema {
     /** Page-level resources: valuation rate provenance. */
     export const Meta = z
       .object({
-        pricing: z
+        valuation: z
           .optional(Valuation.schema.Pricing)
           .check(
             z.describe(
@@ -1532,19 +1732,20 @@ export function exchanges(options: exchanges.Options = {}) {
       }),
       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.',
+          'Attempts exchange providers in priority order and returns the first executable quote. 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.',
+              description:
+                'No configured provider can 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.',
+            description: 'A provider-neutral quote and its next execution action.',
             schema: schema.createQuote.Response,
           },
         }),
@@ -1565,8 +1766,8 @@ export function exchanges(options: exchanges.Options = {}) {
           })
 
         const request = c.req.valid('json')
-        const options = c.req.valid('query')
-        const chainId = options.chainId ?? c.get('chainId')
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
         const client = c.get('getClient')(chainId)
         const amount = BigInt(request.amount)
         const slippageBps = BigInt(request.slippageBps)
@@ -1575,7 +1776,7 @@ export function exchanges(options: exchanges.Options = {}) {
         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 denomination = query['valuation.currency'] ?? 'USD'
           const snapshot = await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
           const rates = await Valuation.ratesFor(c, {
             currencies: snapshot
@@ -1605,13 +1806,16 @@ export function exchanges(options: exchanges.Options = {}) {
             }),
           })
 
+          if (options.nativeDex === false || amount > maxSwapAmount)
+            throw new ExchangeProvider.RouteUnavailableError()
+
           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)
+            if (destinationAmount === 0n) throw new ExchangeProvider.RouteUnavailableError()
 
             const minimumAmount =
               (destinationAmount * (slippageDenominator - slippageBps) + slippageDenominator - 1n) /
@@ -1627,10 +1831,19 @@ export function exchanges(options: exchanges.Options = {}) {
               tokenIn: request.sourceToken,
               tokenOut: request.destinationToken,
             })
-            const tokensByAddress = await resolveTokensByAddress(c, {
+            const calls = [
+              { data: approve.data, to: approve.to, value: 0n },
+              { data: swap.data, to: swap.to, value: 0n },
+            ] as const
+            const gasUnits = await client.estimateGas({
+              ...(request.account ? { account: request.account } : {}),
+              calls,
+            })
+            const gasPrice = await client.getGasPrice()
+            const tokensByAddress = await Tokens.resolveTokens(c, {
               addresses: [request.destinationToken, request.sourceToken],
               chainId,
-              include: options.include,
+              include: query.include,
             })
             const destinationToken = tokensByAddress.get(request.destinationToken)
             const sourceToken = tokensByAddress.get(request.sourceToken)
@@ -1653,18 +1866,18 @@ export function exchanges(options: exchanges.Options = {}) {
                   ...destinationToken,
                   address: request.destinationToken,
                 },
-                ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+                ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
+                gasEstimate: gasCost({ gasPrice, gasUnits }),
                 mode: request.mode,
+                provider: 'nativeDex',
                 sourceAmount: valued(request.amount, request.sourceToken, sourceToken),
                 sourceToken: {
                   ...sourceToken,
                   address: request.sourceToken,
                 },
+                status: 'ready',
                 transaction: {
-                  calls: [
-                    { data: approve.data, to: approve.to, value: '0x0' },
-                    { data: swap.data, to: swap.to, value: '0x0' },
-                  ],
+                  calls: calls.map((call) => ({ ...call, value: '0x0' as const })),
                   chainId,
                 },
               }),
@@ -1677,16 +1890,12 @@ export function exchanges(options: exchanges.Options = {}) {
             tokenIn: request.sourceToken,
             tokenOut: request.destinationToken,
           })
-          if (sourceAmount === 0n) return quoteNotAvailable(c)
+          if (sourceAmount === 0n) throw new ExchangeProvider.RouteUnavailableError()
 
           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,
-            })
+            (sourceAmount * (slippageDenominator + slippageBps) + slippageDenominator - 1n) /
+            slippageDenominator
+          if (maximumAmount > maxSwapAmount) throw new NativeDexAmountOutOfRangeError()
 
           const approve = Actions.token.approve.call(client, {
             amount: maximumAmount,
@@ -1699,10 +1908,19 @@ export function exchanges(options: exchanges.Options = {}) {
             tokenIn: request.sourceToken,
             tokenOut: request.destinationToken,
           })
-          const tokensByAddress = await resolveTokensByAddress(c, {
+          const calls = [
+            { data: approve.data, to: approve.to, value: 0n },
+            { data: swap.data, to: swap.to, value: 0n },
+          ] as const
+          const gasUnits = await client.estimateGas({
+            ...(request.account ? { account: request.account } : {}),
+            calls,
+          })
+          const gasPrice = await client.getGasPrice()
+          const tokensByAddress = await Tokens.resolveTokens(c, {
             addresses: [request.destinationToken, request.sourceToken],
             chainId,
-            include: options.include,
+            include: query.include,
           })
           const destinationToken = tokensByAddress.get(request.destinationToken)
           const sourceToken = tokensByAddress.get(request.sourceToken)
@@ -1716,34 +1934,209 @@ export function exchanges(options: exchanges.Options = {}) {
                 ...destinationToken,
                 address: request.destinationToken,
               },
-              ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+              ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
+              gasEstimate: gasCost({ gasPrice, gasUnits }),
               mode: request.mode,
+              provider: 'nativeDex',
               sourceAmount: valued(sourceAmount, request.sourceToken, sourceToken),
               sourceAmountMax: valued(maximumAmount, request.sourceToken, sourceToken),
               sourceToken: {
                 ...sourceToken,
                 address: request.sourceToken,
               },
+              status: 'ready',
               transaction: {
-                calls: [
-                  { data: approve.data, to: approve.to, value: '0x0' },
-                  { data: swap.data, to: swap.to, value: '0x0' },
-                ],
+                calls: calls.map((call) => ({ ...call, value: '0x0' as const })),
                 chainId,
               },
             }),
             200,
           )
         } catch (cause) {
-          if (request.mode === 'exactSource' && isQuoteAmountOutOfRange(cause))
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          const amountOutOfRange =
+            cause instanceof NativeDexAmountOutOfRangeError ||
+            (request.mode === 'exactSource' && isQuoteAmountOutOfRange(cause))
+          const providers = c.get('providers').filter(ExchangeProvider.is)
+          if (amountOutOfRange && providers.length === 0)
             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 })
+          if (
+            !(cause instanceof ExchangeProvider.RouteUnavailableError) &&
+            !isQuoteUnavailable(cause) &&
+            !amountOutOfRange
+          )
+            return Response.upstream(c, cause)
+
+          if (!request.account) return quoteNotAvailable(c)
+
+          for (const provider of providers)
+            try {
+              const quote = await provider.quote(
+                {
+                  account: request.account,
+                  amount: request.amount,
+                  chainId,
+                  destinationToken: request.destinationToken,
+                  mode: request.mode,
+                  slippageBps: request.slippageBps,
+                  sourceToken: request.sourceToken,
+                },
+                c.req.raw.signal,
+              )
+              if (quote.status === 'ready')
+                await validateProviderCalls(client, {
+                  account: request.account,
+                  calls: quote.transaction.calls,
+                  execution: providerExecution({ quote, request }),
+                })
+              const [gasPrice, gasUnits] = await Promise.all([
+                client.getGasPrice(),
+                quote.status === 'approvalRequired'
+                  ? client.estimateGas({
+                      account: request.account,
+                      calls: quote.approval.calls.map((call) => ({
+                        data: call.data,
+                        to: call.to,
+                        value: BigInt(call.value),
+                      })),
+                    })
+                  : Promise.resolve(BigInt(quote.gasUnits)),
+              ])
+              return c.json(
+                Response.validated(
+                  schema.createQuote.Response,
+                  await providerQuoteResponse(c, {
+                    chainId,
+                    gasPrice,
+                    gasUnits,
+                    include: query.include,
+                    oracle,
+                    query,
+                    quote,
+                    request,
+                    provider,
+                  }),
+                ),
+                200,
+              )
+            } catch (error) {
+              if (error instanceof ExchangeProvider.RouteUnavailableError) continue
+              const failure = ExchangeProvider.failure(error, {
+                chainId,
+                operation: 'quote',
+                provider,
+              })
+              if (failure) c.set('providerFailure', failure)
+              return Response.upstream(c, error)
+            }
+
+          return quoteNotAvailable(c)
+        }
+      },
+    )
+    .post(
+      '/v1/exchange/quotes/execute',
+      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.executeQuote.Request, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Finishes a provider quote after the wallet supplies the requested typed-data signature. This endpoint does not submit a transaction.',
+        operationId: 'finalizeExchangeQuote',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: [
+                'body_invalid',
+                'query_invalid',
+                'swap_continuation_invalid',
+                'swap_provider_invalid',
+              ],
+            },
+            502: 'The selected provider could not build the swap right now.',
+          },
+          success: {
+            description: 'The final unsigned calls needed to execute the swap.',
+            schema: schema.executeQuote.Response,
+          },
+        }),
+        summary: 'Finalize 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 chainId = c.req.valid('query').chainId ?? c.get('chainId')
+        const provider = c
+          .get('providers')
+          .filter(ExchangeProvider.is)
+          .find((candidate) => candidate.id === request.provider && candidate.finalizeQuote)
+        if (!provider?.finalizeQuote)
+          return Response.error(c, {
+            code: 'swap_provider_invalid',
+            message: 'The selected swap provider is not configured',
+            status: 400,
+          })
+
+        c.header('Cache-Control', 'no-store')
+        try {
+          const client = c.get('getClient')(chainId)
+          const result = await provider.finalizeQuote(
+            {
+              account: request.account,
+              chainId,
+              continuation: request.continuation,
+              signature: request.signature,
+            },
+            c.req.raw.signal,
+          )
+          await validateProviderCalls(client, {
+            account: request.account,
+            calls: result.calls,
+            execution: result.execution,
+          })
+          return c.json(
+            Response.validated(schema.executeQuote.Response, {
+              provider: provider.id,
+              transaction: { calls: result.calls, chainId },
+            }),
+            200,
+          )
+        } catch (cause) {
+          if (cause instanceof ExchangeProvider.ProviderContinuationError)
+            return Response.error(c, {
+              code: 'swap_continuation_invalid',
+              message: 'Invalid swap continuation',
+              status: 400,
+            })
+          const failure = ExchangeProvider.failure(cause, {
+            chainId,
+            operation: 'finalize',
+            provider,
+          })
+          if (failure) c.set('providerFailure', failure)
           return Response.upstream(c, cause)
         }
       },
@@ -1793,11 +2186,6 @@ export function exchanges(options: exchanges.Options = {}) {
         if (options.cursor !== undefined) 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`;
-          // the quote is intrinsic to it).
-          const pairIndex = await getPairIndex(c, { chainId })
-
           const page = await getSwaps(c, {
             chainId,
             cursor: options.cursor,
@@ -1806,7 +2194,6 @@ export function exchanges(options: exchanges.Options = {}) {
             limit: options.limit,
             maker: options.maker,
             order: options.order,
-            pairIndex,
             participant: options.participant,
             taker: options.taker,
             toBlock: options['blockNumber.to'],
@@ -1816,14 +2203,14 @@ export function exchanges(options: exchanges.Options = {}) {
 
           // `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, {
+          const tokensByAddress = await Tokens.resolveTokens(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 denomination = options['valuation.currency'] ?? 'USD'
           const snapshot =
             page.data.length > 0
               ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
@@ -1894,7 +2281,7 @@ export function exchanges(options: exchanges.Options = {}) {
           return c.json(
             Response.validated(schema.getSwaps.Response, {
               data,
-              ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+              ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
               nextCursor: page.nextCursor,
             }),
             200,
@@ -1982,7 +2369,7 @@ export function exchanges(options: exchanges.Options = {}) {
             transactionHash: pair.transactionHash,
           }))
           if (options.include.includes('tokens') && data.length > 0) {
-            const tokensByAddress = await resolveTokensByAddress(c, {
+            const tokensByAddress = await Tokens.resolveTokens(c, {
               addresses: data.flatMap((pair) => [pair.base.address, pair.quote.address]),
               chainId,
               include: tokenFields,
@@ -2079,7 +2466,7 @@ export function exchanges(options: exchanges.Options = {}) {
           let baseToken: z.output<typeof schema.PairToken> = { address: target.base }
           let quoteToken: z.output<typeof schema.PairToken> = { address: target.quote }
           if (options.include.includes('tokens')) {
-            const tokensByAddress = await resolveTokensByAddress(c, {
+            const tokensByAddress = await Tokens.resolveTokens(c, {
               addresses: [target.base, target.quote],
               chainId,
               include: tokenFields,
@@ -2154,18 +2541,21 @@ export function exchanges(options: exchanges.Options = {}) {
         const chainId = options.chainId ?? c.get('chainId')
 
         try {
-          // The pair index (base address → pair) resolves the `base` selector
-          // and each order's pair; the OrderPlaced scan only carries the
-          // base-side `token`.
-          const pairIndex = await getPairIndex(c, { chainId })
-
           // `base` selects the single pair it identifies — a pair's quote is
           // intrinsic to its base token on-chain, so the base address alone
           // is a complete selector.
-          let pair: getPairs.Row | undefined
+          let pair: getPairsByBase.Pair | undefined
           if (options.base !== undefined) {
-            const target = pairIndex.get(options.base)
-            if (!target) return pairNotFoundError(c, { base: options.base, pairIndex })
+            const target = (await getPairsByBase(c, { bases: [options.base], chainId })).get(
+              options.base,
+            )
+            // The 404's quote-token hint scans the full pair index; fetch it
+            // only on this miss path so page requests never pay for it.
+            if (!target)
+              return pairNotFoundError(c, {
+                base: options.base,
+                pairIndex: await getPairIndex(c, { chainId }),
+              })
             pair = target
           }
 
@@ -2177,7 +2567,6 @@ export function exchanges(options: exchanges.Options = {}) {
             order: options.order,
             page: options.page,
             pair,
-            pairIndex,
             side: options.side,
             sort: options.sort,
           })
@@ -2188,7 +2577,7 @@ export function exchanges(options: exchanges.Options = {}) {
           // unavailable keeps just `address`.
           let data = page.data
           if (options.include.includes('tokens') && data.length > 0) {
-            const tokensByAddress = await resolveTokensByAddress(c, {
+            const tokensByAddress = await Tokens.resolveTokens(c, {
               addresses: data.flatMap((o) => [o.pair.base.address, o.pair.quote.address]),
               chainId,
               include: tokenFields,
@@ -2512,7 +2901,7 @@ export function exchanges(options: exchanges.Options = {}) {
           let base: z.output<typeof schema.PairToken> = { address: target.base }
           let quote: z.output<typeof schema.PairToken> = { address: target.quote }
           if (options.include.includes('tokens')) {
-            const tokensByAddress = await resolveTokensByAddress(c, {
+            const tokensByAddress = await Tokens.resolveTokens(c, {
               addresses: [target.base, target.quote],
               chainId,
               include: tokenFields,
@@ -2614,7 +3003,7 @@ export function exchanges(options: exchanges.Options = {}) {
           let base: z.output<typeof schema.PairToken> = { address: target.base }
           let quote: z.output<typeof schema.PairToken> = { address: target.quote }
           if (options.include.includes('tokens')) {
-            const tokensByAddress = await resolveTokensByAddress(c, {
+            const tokensByAddress = await Tokens.resolveTokens(c, {
               addresses: [target.base, target.quote],
               chainId,
               include: tokenFields,
@@ -2641,6 +3030,8 @@ export declare namespace exchanges {
   type Options = {
     /** FX configuration backing amount valuation. */
     fx?: Valuation.addresses.Fx | undefined
+    /** Whether to try Tempo's native stablecoin DEX first. Enabled by default. */
+    nativeDex?: boolean | undefined
   }
 }
 
@@ -2667,68 +3058,6 @@ function pairNotFoundError(
   return Response.error(c, { code: 'pair_not_found', message, status: 404 })
 }
 
-/** 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, 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 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,
-            },
-          ] as const
-        } catch {
-          return [token, undefined] as const
-        }
-      }),
-    ),
-  )
-  for (const [token, metadata] of resolved) if (metadata) tokensByAddress.set(token, metadata)
-  return tokensByAddress
-}
-
 async function getPairs(c: Context<App.Environment>, options: getPairs.Options) {
   if (options.sort === 'liquidity') return getPairsByLiquidity(c, options)
   return getPairsByCreation(c, options)
@@ -2974,6 +3303,110 @@ declare namespace getPairIndex {
   }
 }
 
+/**
+ * Base-address chunk size for {@link getPairsByBase}. `tidx.fetch` transmits
+ * queries as GET, so an unbounded `IN (...)` could overflow the request URI.
+ */
+const pairLookupBatchSize = 200
+
+/**
+ * Resolves the pairs for a set of book base addresses with one targeted
+ * `dex_pairs` lookup, avoiding the full pair-index fetch (1MB+ on large
+ * chains).
+ */
+async function getPairsByBase(c: Context<App.Environment>, options: getPairsByBase.Options) {
+  const { bases, chainId } = options
+  const pairs = new Map<string, getPairsByBase.Pair>()
+  if (bases.length === 0) return pairs
+  const tidx = c.get('getTidx')(chainId)
+
+  return Timing.time(c, 'pair_lookup', async () => {
+    for (let i = 0; i < bases.length; i += pairLookupBatchSize) {
+      const list = bases
+        .slice(i, i + pairLookupBatchSize)
+        .map((base) => `'${base}'`)
+        .join(', ')
+      // `LIMIT 1 BY base` with the ascending sort picks each base's oldest
+      // row, the row the pair index's last-entry-wins `Map` build selects.
+      const result = await tidx.fetch({
+        chainId,
+        engine: 'clickhouse',
+        query: `
+          SELECT key, base, quote
+          FROM dex_pairs
+          WHERE address = '${stablecoinDex}' AND base IN (${list})
+          ORDER BY block_num ASC, log_idx ASC
+          LIMIT 1 BY base
+        ` as string,
+      })
+      // Drop malformed rows, mirroring `parsePairRow`.
+      for (const row of result.rows) {
+        const key = Schema.Hash.safeParse(row['key'])
+        const base = Schema.TokenAddress.safeParse(row['base'])
+        const quote = Schema.TokenAddress.safeParse(row['quote'])
+        if (key.success && base.success && quote.success)
+          pairs.set(base.data, { base: base.data, key: key.data, quote: quote.data })
+      }
+    }
+    return pairs
+  })
+}
+
+declare namespace getPairsByBase {
+  type Options = {
+    /** Book base addresses to resolve (lowercase). */
+    bases: readonly string[]
+    chainId: z.output<typeof Schema.ChainId>
+  }
+  /** Pair fields consumed by the swap and order feeds. */
+  type Pair = {
+    base: z.output<typeof Schema.TokenAddress>
+    key: z.output<typeof Schema.Hash>
+    quote: z.output<typeof Schema.TokenAddress>
+  }
+}
+
+/**
+ * Resolves one pair by its book key with a targeted `dex_pairs` lookup,
+ * covering books the bounded pair index ages out of its newest window.
+ */
+async function getPairByKey(c: Context<App.Environment>, options: getPairByKey.Options) {
+  const { chainId, key } = options
+  const tidx = c.get('getTidx')(chainId)
+
+  return Timing.time(c, 'pair_lookup', async () => {
+    // The ascending sort picks the key's oldest row, matching the pair
+    // index's last-entry-wins `Map` build.
+    const result = await tidx.fetch({
+      chainId,
+      engine: 'clickhouse',
+      query: `
+        SELECT key, base, quote
+        FROM dex_pairs
+        WHERE address = '${stablecoinDex}' AND key = '${key}'
+        ORDER BY block_num ASC, log_idx ASC
+        LIMIT 1
+      ` as string,
+    })
+    const row = result.rows[0]
+    if (!row) return undefined
+    // Drop malformed rows, mirroring `parsePairRow`.
+    const parsedKey = Schema.Hash.safeParse(row['key'])
+    const base = Schema.TokenAddress.safeParse(row['base'])
+    const quote = Schema.TokenAddress.safeParse(row['quote'])
+    if (!parsedKey.success || !base.success || !quote.success) return undefined
+    return { base: base.data, key: parsedKey.data, quote: quote.data }
+  })
+}
+
+declare namespace getPairByKey {
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    /** Book key (lowercase). */
+    key: string
+  }
+}
+
 /**
  * Validates and shapes one `PairCreated` row into the internal pair shape.
  * Returns `undefined` for malformed rows so the caller can drop them without
@@ -3075,7 +3508,6 @@ async function getSwaps(c: Context<App.Environment>, options: getSwaps.Options)
     limit,
     maker,
     order,
-    pairIndex,
     participant,
     taker,
     toBlock,
@@ -3221,16 +3653,17 @@ async function getSwaps(c: Context<App.Environment>, options: getSwaps.Options)
         }),
       )
 
-      // Each fill's book quote: from the `dex_pairs` index when present, else
-      // the base token's on-chain `quoteToken()` — some books predate the
-      // indexer's `PairCreated` decode (genesis system books) and have no
-      // `dex_pairs` row.
+      // Each fill's book quote: from a targeted `dex_pairs` lookup of this
+      // batch's bases when indexed, else the base token's on-chain
+      // `quoteToken()` — some books predate the indexer's `PairCreated`
+      // decode (genesis system books) and have no `dex_pairs` row.
       const bases = [
         ...new Set([...states.values()].flatMap((events) => events.map((event) => event.token))),
       ]
+      const pairs = await getPairsByBase(c, { bases, chainId })
       const quoteByBase = new Map<string, z.output<typeof Schema.TokenAddress>>()
       for (const bookBase of bases) {
-        const indexed = pairIndex.get(bookBase)
+        const indexed = pairs.get(bookBase)
         if (indexed) quoteByBase.set(bookBase, indexed.quote)
       }
       const fallback = await Timing.time(c, 'swap_quotes', () =>
@@ -3517,8 +3950,6 @@ declare namespace getSwaps {
     maker?: z.output<typeof Schema.Address> | undefined
     /** Sort direction over `(block_num, first fill log_idx)`. */
     order: 'asc' | 'desc'
-    /** Pair index (base address → pair) used to orient each fill's book. */
-    pairIndex: Map<string, getPairs.Row>
     /** Either-side filter — the taker or any fill's maker. */
     participant?: z.output<typeof Schema.Address> | undefined
     taker?: z.output<typeof Schema.Address> | undefined
@@ -4321,11 +4752,11 @@ const orderCursorTickBias = 32768
  * `remaining = OrderPlaced.amount - sum(OrderFilled.amountFilled)`; orders
  * with an `OrderCancelled` event are excluded outright. Each row is annotated
  * with its pair: the scoped feed reuses the resolved `pair`, the unscoped
- * feed resolves per row from the supplied pair index (rows whose pair is
- * unknown are dropped).
+ * feed resolves the page's base tokens with one targeted `dex_pairs` lookup
+ * (rows whose pair is unknown are dropped).
  */
 async function getOrders(c: Context<App.Environment>, options: getOrders.Options) {
-  const { chainId, cursor, limit, maker, order, page, pair, pairIndex, side, sort } = options
+  const { chainId, cursor, limit, maker, order, page, pair, side, sort } = options
   const store = c.get('store')
 
   return Timing.time(c, 'orders', async () => {
@@ -4357,9 +4788,12 @@ async function getOrders(c: Context<App.Environment>, options: getOrders.Options
       sort,
     })
 
+    const bases = pair ? [] : [...new Set(pageRows.map((row) => row.token))]
+    const pairsByBase = await getPairsByBase(c, { bases, chainId })
+
     const data: z.output<typeof schema.getOrders.Order>[] = []
     for (const row of pageRows) {
-      const rowPair = pair ?? pairIndex.get(row.token)
+      const rowPair = pair ?? pairsByBase.get(row.token)
       if (!rowPair) continue
       const shaped = shapeRestingOrder(row)
       if (!shaped) continue
@@ -4391,9 +4825,7 @@ declare namespace getOrders {
     /** Sort direction applied to whatever `sort` selects. */
     order: 'asc' | 'desc'
     /** When set, scope the snapshot to this resolved pair. */
-    pair?: getPairs.Row | undefined
-    /** Pair index (base address → pair) used to resolve unscoped rows. */
-    pairIndex: Map<string, getPairs.Row>
+    pair?: getPairsByBase.Pair | undefined
     /** Restrict to one side of the book. */
     side?: 'bid' | 'ask' | undefined
     /** Sort key. `tick` ranks by price; `time` orders by placement (block, log). */
@@ -4696,10 +5128,16 @@ async function loadRestingOrders(
 
   const truncated = result.rows.length > scanCap
   const placedRows = result.rows.slice(0, scanCap)
+  // `dex_orders` can carry duplicate rows per placement; keep the first
+  // (newest) copy so pages emit each order once and a duplicate straddling an
+  // IN-batch boundary can't double-count fills.
   const placed: RestingOrder[] = []
+  const seen = new Set<string>()
   for (const row of placedRows) {
     const parsed = parsePlacedRow(row)
-    if (parsed) placed.push(parsed)
+    if (!parsed || seen.has(parsed.orderId)) continue
+    seen.add(parsed.orderId)
+    placed.push(parsed)
   }
   if (placed.length === 0) return { orders: [], truncated }
 
@@ -4765,12 +5203,14 @@ export async function resolveBookReserves(
   const tidx = c.get('getTidx')(chainId)
 
   // Scan the newest `scanCap` `OrderPlaced` rows per base. `LIMIT ... BY token`
-  // is the ClickHouse fair cap; the app-side `perToken` guard re-applies it
-  // across chunks (a base can't span chunks, but the guard also flips
-  // `truncated` consistently) and against the `scanCap + 1` probe row.
+  // is the ClickHouse fair cap over raw rows; `rawPerToken` flips `truncated`
+  // when a token's window overflows, since unfetched older rows may hold unique
+  // placements even when duplicates keep the unique count under the cap.
   let truncated = false
   const placed: RestingOrder[] = []
   const perToken = new Map<string, number>()
+  const rawPerToken = new Map<string, number>()
+  const seen = new Set<string>()
   for (let i = 0; i < unique.length; i += reserveBaseInBatchSize) {
     const group = unique.slice(i, i + reserveBaseInBatchSize)
     const list = group.map((base) => `'${base}'`).join(', ')
@@ -4788,11 +5228,15 @@ export async function resolveBookReserves(
     for (const row of result.rows) {
       const parsed = parsePlacedRow(row)
       if (!parsed) continue
+      const raw = (rawPerToken.get(parsed.token) ?? 0) + 1
+      rawPerToken.set(parsed.token, raw)
+      if (raw > scanCap) truncated = true
+      // Duplicate placement rows (see `loadRestingOrders`) can't add the same
+      // order's remaining liquidity twice; the raw probe above still counts them.
+      if (seen.has(parsed.orderId)) continue
       const count = perToken.get(parsed.token) ?? 0
-      if (count >= scanCap) {
-        truncated = true
-        continue
-      }
+      if (count >= scanCap) continue
+      seen.add(parsed.orderId)
       perToken.set(parsed.token, count + 1)
       placed.push(parsed)
     }
@@ -4908,6 +5352,9 @@ async function fetchCancelledByIds(
   const cancelled = new Set<string>()
   if (orderIds.length === 0) return cancelled
   const tidx = c.get('getTidx')(chainId)
+  // Chunks resolve serially: the managed indexer rejects bursts of concurrent
+  // chunk queries (~2-3 in flight), and the cancel/fill helpers already
+  // overlap via `Promise.all`.
   for (let i = 0; i < orderIds.length; i += orderInBatchSize) {
     const batch = orderIds.slice(i, i + orderInBatchSize)
     const result = await tidx.fetch({
@@ -4942,6 +5389,9 @@ async function fetchFillSumsByIds(
   const sums = new Map<string, bigint>()
   if (orderIds.length === 0) return sums
   const tidx = c.get('getTidx')(chainId)
+  // Chunks resolve serially: the managed indexer rejects bursts of concurrent
+  // chunk queries (~2-3 in flight), and the cancel/fill helpers already
+  // overlap via `Promise.all`.
   for (let i = 0; i < orderIds.length; i += orderInBatchSize) {
     const batch = orderIds.slice(i, i + orderInBatchSize)
     const result = await tidx.fetch({
@@ -5055,31 +5505,28 @@ async function getOrder(c: Context<App.Environment>, options: getOrder.Options)
     Store.memoize(
       async () => {
         // The on-chain DEX exposes the full order struct (placement params
-        // plus current `remaining`) in one view call. We resolve the pair
-        // off the returned `bookKey` concurrently with the RPC; on a warm
-        // pair-index cache that's effectively free.
-        const [chainOrder, pairsByKey] = await Promise.all([
-          Timing.time(c, 'order_dex_get', () =>
-            // The DEX reverts with `OrderDoesNotExist()` for ids it no longer
-            // holds (never placed, or filled/cancelled and cleared), rather
-            // than returning the zero struct. Map that revert to not-found so
-            // the route answers 404 instead of bubbling up as a 502.
-            client.dex.getOrder({ orderId: BigInt(orderId) }).catch((cause) => {
-              if (isOrderDoesNotExist(cause)) return undefined
-              throw cause
-            }),
-          ),
-          getPairIndexByKey(c, { chainId }),
-        ])
+        // plus current `remaining`) in one view call.
+        const chainOrder = await Timing.time(c, 'order_dex_get', () =>
+          // The DEX reverts with `OrderDoesNotExist()` for ids it no longer
+          // holds (never placed, or filled/cancelled and cleared), rather
+          // than returning the zero struct. Map that revert to not-found so
+          // the route answers 404 instead of bubbling up as a 502.
+          client.dex.getOrder({ orderId: BigInt(orderId) }).catch((cause) => {
+            if (isOrderDoesNotExist(cause)) return undefined
+            throw cause
+          }),
+        )
 
         // The DEX returns the zero struct (or reverts, handled above) when an
         // order id is unknown.
         if (!chainOrder || chainOrder.orderId === 0n) return undefined
 
-        // Pair index miss is a soft consistency floor (the index is bounded
-        // by `pairIndexLimit`); without `(base, quote)` we cannot frame the
-        // order, so surface as not-found.
-        const pair = pairsByKey.get(chainOrder.bookKey.toLowerCase())
+        // Targeted lookup off the returned `bookKey`; the bounded pair index
+        // misses books outside its newest window, 404ing live orders.
+        const pair = await getPairByKey(c, {
+          chainId,
+          key: chainOrder.bookKey.toLowerCase(),
+        })
         if (!pair) return undefined
 
         const tick = chainOrder.tick
@@ -5151,11 +5598,187 @@ function isOrderDoesNotExist(error: unknown): boolean {
   )
 }
 
-/** Returns the native DEX 404 used when no executable quote is available. */
+async function providerQuoteResponse(
+  c: Context<App.Environment>,
+  options: {
+    chainId: number
+    gasPrice: bigint
+    gasUnits: bigint
+    include: readonly z.output<typeof schema.createQuote.Include>[]
+    oracle: FxOracle.Oracle
+    provider: ExchangeProvider.Provider
+    query: z.output<typeof schema.createQuote.Query>
+    quote: ExchangeProvider.QuoteResult
+    request: z.output<typeof schema.createQuote.Request>
+  },
+) {
+  const { chainId, gasPrice, gasUnits, oracle, provider, query, quote, request } = options
+  const tokensByAddress = await Tokens.resolveTokens(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')
+
+  const denomination = query['valuation.currency'] ?? '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()),
+    }),
+  })
+  const execution =
+    quote.status === 'ready'
+      ? {
+          status: quote.status,
+          transaction: { calls: [...quote.transaction.calls], chainId },
+        }
+      : quote.status === 'approvalRequired'
+        ? { approval: { calls: [...quote.approval.calls] }, status: quote.status }
+        : {
+            continuation: quote.continuation,
+            status: quote.status,
+            typedData: quote.typedData,
+          }
+  const common = {
+    destinationToken: { ...destinationToken, address: request.destinationToken },
+    ...execution,
+    ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
+    gasEstimate: gasCost({ gasPrice, gasUnits }),
+    provider: provider.id,
+    sourceToken: { ...sourceToken, address: request.sourceToken },
+  }
+
+  if (request.mode === 'exactSource') {
+    if (!quote.minimumDestinationAmount) throw new ExchangeProvider.ProviderPayloadError()
+    return {
+      ...common,
+      destinationAmount: valued(
+        quote.destinationAmount,
+        request.destinationToken,
+        destinationToken,
+      ),
+      destinationAmountMin: valued(
+        quote.minimumDestinationAmount,
+        request.destinationToken,
+        destinationToken,
+      ),
+      mode: request.mode,
+      sourceAmount: valued(quote.sourceAmount, request.sourceToken, sourceToken),
+    }
+  }
+
+  if (!quote.maximumSourceAmount) throw new ExchangeProvider.ProviderPayloadError()
+  return {
+    ...common,
+    destinationAmount: valued(quote.destinationAmount, request.destinationToken, destinationToken),
+    mode: request.mode,
+    sourceAmount: valued(quote.sourceAmount, request.sourceToken, sourceToken),
+    sourceAmountMax: valued(quote.maximumSourceAmount, request.sourceToken, sourceToken),
+  }
+}
+
+function providerExecution(options: providerExecution.Options): ExchangeProvider.Execution {
+  const { quote, request } = options
+  return {
+    destinationAmount: quote.destinationAmount,
+    destinationToken: request.destinationToken,
+    gasUnits: quote.gasUnits,
+    ...(quote.maximumSourceAmount ? { maximumSourceAmount: quote.maximumSourceAmount } : {}),
+    ...(quote.minimumDestinationAmount
+      ? { minimumDestinationAmount: quote.minimumDestinationAmount }
+      : {}),
+    mode: request.mode,
+    sourceAmount: quote.sourceAmount,
+    sourceToken: request.sourceToken,
+  }
+}
+
+declare namespace providerExecution {
+  type Options = {
+    quote: ExchangeProvider.QuoteResult
+    request: z.output<typeof schema.createQuote.Request>
+  }
+}
+
+async function validateProviderCalls(
+  client: Viem.getClient.ReturnType,
+  options: validateProviderCalls.Options,
+) {
+  try {
+    const { results } = await Actions.simulate.simulateCalls(client, {
+      account: options.account,
+      calls: options.calls.map((call) => ({
+        data: call.data,
+        to: call.to,
+        value: BigInt(call.value),
+      })),
+      traceTransfers: true,
+    })
+    if (results.some((result) => result.status !== 'success'))
+      throw new ExchangeProvider.ProviderPayloadError()
+
+    const logs = results.flatMap((result) => result.logs ?? [])
+    const transfers = parseEventLogs({
+      abi: [AbiEvent.fromAbi(Abis.tip20, 'Transfer')],
+      eventName: 'Transfer',
+      logs,
+    }).map((log) => ({
+      amount: log.args.amount,
+      from: log.args.from,
+      to: log.args.to,
+      token: log.address,
+    }))
+    ExchangeProvider.validateExecution({
+      account: options.account,
+      execution: options.execution,
+      transfers,
+    })
+  } catch (cause) {
+    if (cause instanceof ExchangeProvider.ProviderPayloadError) throw cause
+    throw new ExchangeProvider.ProviderPayloadError()
+  }
+}
+
+declare namespace validateProviderCalls {
+  type Options = {
+    account: `0x${string}`
+    calls: readonly ExchangeProvider.Call[]
+    execution: ExchangeProvider.Execution
+  }
+}
+
+/** Converts estimated gas units to a native-token base-unit fee. */
+function gasCost(options: { gasPrice: bigint; gasUnits: bigint }) {
+  return (options.gasPrice * options.gasUnits).toString()
+}
+
+/** Returns the 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',
+    message: 'No configured exchange provider has an executable quote',
     status: 404,
   })
 }
@@ -5309,18 +5932,6 @@ declare namespace countOrderFills {
   }
 }
 
-/**
- * Per-key pair index derived from the existing per-base index. Built once
- * and memoized at the same cadence as the pair index itself so chained
- * `getOrder` lookups stay an O(1) `Map.get`.
- */
-async function getPairIndexByKey(c: Context<App.Environment>, options: getPairIndex.Options) {
-  const pairsByBase = await getPairIndex(c, options)
-  const pairsByKey = new Map<string, getPairs.Row>()
-  for (const pair of pairsByBase.values()) pairsByKey.set(pair.key.toLowerCase(), pair)
-  return pairsByKey
-}
-
 /**
  * Validates and shapes one `OrderFilled` row into the public `Fill` shape.
  * Drops the row when any required column is malformed so the caller can omit
@@ -5358,3 +5969,7 @@ function parseOrderFillRow(
     transactionHash: transactionHash.data,
   }
 }
+
+class NativeDexAmountOutOfRangeError extends Error {
+  override name = 'Exchanges.NativeDexAmountOutOfRangeError'
+}