tapimo 0.7.1 → 0.7.2

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

@@ -1,11 +1,12 @@
 import { Hono } from 'hono';
 import { AbiError, AbiEvent } from 'ox';
-import { BaseError, ContractFunctionRevertedError, decodeFunctionData, parseAbi, } from 'viem';
+import { BaseError, ContractFunctionRevertedError, decodeFunctionData, parseAbi, parseEventLogs, } from 'viem';
 import { Abis, Actions, Addresses, Tick } from 'viem/tempo';
 import * as z from 'zod/mini';
 import * as Auth from '../../../internal/Auth.js';
 import * as Cache from '../../../internal/Cache.js';
 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';
@@ -21,6 +22,8 @@ import * as Valuation from './valuation.js';
 // 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'));
+/** 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.
@@ -181,19 +184,19 @@ export var schema;
     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 ' +
+            .check(z.describe('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. */
     let createQuote;
     (function (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. */
         createQuote.Amount = Schema.DecimalString.check(z.refine((value) => {
             const amount = BigInt(value);
-            return amount > 0n && amount <= maxSwapAmount;
-        }, { error: 'Amount must be between 1 and the maximum uint128 value.' }), z.describe('Positive token amount in the token’s smallest unit, encoded as a decimal string.'), z.meta({ examples: ['1000000'] }));
+            return amount > 0n && amount <= maxProviderAmount;
+        }, { error: 'Amount must be a positive uint256.' }), z.describe('Positive token amount in the token’s smallest unit, encoded as a decimal string.'), z.meta({ examples: ['1000000'] }));
         /** Optional token fields that require sources beyond RPC metadata. */
         createQuote.Include = z
             .enum(tokenFields)
@@ -204,13 +207,16 @@ export var schema;
         createQuote.Query = z
             .strictObject({
             chainId: Schema.ChainIdQuery,
-            denomination: Schema.Denomination,
             include: createQuote.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. */
         createQuote.Request = z
             .strictObject({
+            account: z
+                .optional(Schema.Address)
+                .check(z.describe('Wallet that will sign and execute the swap.'), z.meta({ examples: ['0x1111111111111111111111111111111111111111'] })),
             amount: createQuote.Amount.check(z.describe('Pinned amount in base units: source amount for `exactSource`, destination amount for `exactDestination`.')),
             destinationToken: DestinationTokenAddress.check(z.describe('TIP-20 token the swap receives.')),
             mode: z
@@ -223,13 +229,13 @@ export var schema;
         })
             .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.'));
+        }), z.describe('Request for an executable quote from the configured exchange providers.'));
         /** One call in the unsigned Tempo transaction plan. */
         createQuote.Call = z
             .object({
-            data: Schema.Hex.check(z.describe('ABI-encoded call data.')),
-            to: Schema.Address.check(z.describe('Contract or precompile that receives the call.')),
-            value: Schema.Quantity.check(z.describe('Native token value sent with the call; native DEX swap calls use `0x0`.'), z.meta({ examples: ['0x0'] })),
+            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.'), 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 }), {
@@ -242,9 +248,9 @@ export var schema;
         const SourceToken = z.extend(QuoteToken, {
             address: SourceTokenAddress.check(z.describe('TIP-20 token the swap spends.')),
         });
-        const Transaction = z
+        createQuote.Transaction = z
             .object({
-            calls: z.array(createQuote.Call).check(z.length(2), z.describe('Approval followed by the native DEX swap call.'), z.meta({
+            calls: z.array(createQuote.Call).check(z.minLength(1), z.describe('Calls to execute in order.'), z.meta({
                 examples: [
                     [
                         {
@@ -262,41 +268,161 @@ export var schema;
         /** Response-level valuation rate provenance. */
         createQuote.Meta = z
             .object({
-            pricing: z
+            valuation: z
                 .optional(Valuation.schema.Pricing)
                 .check(z.describe('Rate provenance for amount valuations. Present when conversion rates were consulted.')),
         })
             .check(z.describe('Response-level resources attached to this quote.'));
-        /** Native DEX quote plus the approval and swap calls needed to execute it. */
-        createQuote.Response = z
-            .discriminatedUnion('mode', [
-            z.object({
-                destinationAmount: ValuedAmount.check(z.describe('Quoted destination amount.')),
-                destinationAmountMin: ValuedAmount.check(z.describe('Minimum destination amount after slippage.')),
-                destinationToken: DestinationToken,
-                meta: z.optional(createQuote.Meta).check(z.describe('Valuation rate provenance for this quote.')),
-                mode: z
-                    .literal('exactSource')
-                    .check(z.describe('The source amount is fixed and the destination has a minimum.'), z.meta({ examples: ['exactSource'] })),
-                sourceAmount: ValuedAmount.check(z.describe('Exact source amount.')),
-                sourceToken: SourceToken.check(z.describe('Token spent by the swap.')),
-                transaction: Transaction,
-            }),
-            z.object({
-                destinationAmount: ValuedAmount.check(z.describe('Exact destination amount.')),
-                destinationToken: DestinationToken.check(z.describe('Token received by the swap.')),
-                meta: z.optional(createQuote.Meta).check(z.describe('Valuation rate provenance for this quote.')),
-                mode: z
-                    .literal('exactDestination')
-                    .check(z.describe('The destination amount is fixed and the source has a maximum.'), z.meta({ examples: ['exactDestination'] })),
-                sourceAmount: ValuedAmount.check(z.describe('Quoted source amount.')),
-                sourceAmountMax: ValuedAmount.check(z.describe('Maximum source amount after slippage.')),
-                sourceToken: SourceToken,
-                transaction: Transaction,
+        /** Provider-neutral EIP-712 payload to sign before finalizing a quote. */
+        createQuote.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(),
+            })))
+                .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(createQuote.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: createQuote.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: createQuote.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(createQuote.Meta).check(z.describe('Valuation rate provenance for this quote.')),
+            mode: z
+                .literal('exactSource')
+                .check(z.describe('The source amount is fixed and the destination has a minimum.'), z.meta({ examples: ['exactSource'] })),
+            sourceAmount: ValuedAmount.check(z.describe('Exact source amount.')),
+            sourceToken: SourceToken.check(z.describe('Token spent by the swap.')),
+        };
+        const ExactDestination = {
+            destinationAmount: ValuedAmount.check(z.describe('Exact destination amount.')),
+            destinationToken: DestinationToken.check(z.describe('Token received by the swap.')),
+            meta: z.optional(createQuote.Meta).check(z.describe('Valuation rate provenance for this quote.')),
+            mode: z
+                .literal('exactDestination')
+                .check(z.describe('The destination amount is fixed and the source has a maximum.'), z.meta({ examples: ['exactDestination'] })),
+            sourceAmount: ValuedAmount.check(z.describe('Quoted source amount.')),
+            sourceAmountMax: ValuedAmount.check(z.describe('Maximum source amount after slippage.')),
+            sourceToken: SourceToken,
+        };
+        /** Provider-neutral quote and the action needed to execute it. */
+        createQuote.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.'));
     })(createQuote = schema.createQuote || (schema.createQuote = {}));
+    /** Schemas for finishing a quote after a provider-requested signature. */
+    let executeQuote;
+    (function (executeQuote) {
+        /** Signed continuation request. */
+        executeQuote.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. */
+        executeQuote.Response = z.object({
+            provider: z
+                .string()
+                .check(z.describe('Provider that built the transaction.'), z.meta({ examples: ['uniswap'] })),
+            transaction: createQuote.Transaction,
+        });
+    })(executeQuote = schema.executeQuote || (schema.executeQuote = {}));
     /** Schemas for the getPairs operation. */
     let getPairs;
     (function (getPairs) {
@@ -408,7 +534,6 @@ export var schema;
             'blockNumber.to': Schema.blockNumberBound('swaps', 'to'),
             chainId: Schema.ChainIdQuery,
             cursor: Schema.Cursor,
-            denomination: Schema.Denomination,
             include: getSwaps.includeQuery,
             limit: Schema.Limit,
             maker: z
@@ -426,6 +551,7 @@ export var schema;
             transactionHash: z
                 .optional(Schema.Hash)
                 .check(z.describe('Only include swaps included in this transaction hash.')),
+            'valuation.currency': Schema.Denomination,
         })
             .check(z.describe('Query parameters for swap feed requests. Cursor-paginated only — a batched ' +
             'transaction expands one fill group into a variable number of swap rows, so a ' +
@@ -503,7 +629,7 @@ export var schema;
         /** Page-level resources: valuation rate provenance. */
         getSwaps.Meta = z
             .object({
-            pricing: z
+            valuation: 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.')),
@@ -953,19 +1079,19 @@ export function exchanges(options = {}) {
         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.',
+        description: '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,
             },
         }),
@@ -985,8 +1111,8 @@ export function exchanges(options = {}) {
                 message: 'Invalid request body',
             });
         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);
@@ -994,7 +1120,7 @@ export function 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
@@ -1019,6 +1145,8 @@ export function exchanges(options = {}) {
                     token: snapshot?.byAddress.get(address.toLowerCase()),
                 }),
             });
+            if (options.nativeDex === false || amount > maxSwapAmount)
+                throw new ExchangeProvider.RouteUnavailableError();
             if (request.mode === 'exactSource') {
                 const destinationAmount = await Actions.dex.getSellQuote(client, {
                     amountIn: amount,
@@ -1026,7 +1154,7 @@ export function exchanges(options = {}) {
                     tokenOut: request.destinationToken,
                 });
                 if (destinationAmount === 0n)
-                    return quoteNotAvailable(c);
+                    throw new ExchangeProvider.RouteUnavailableError();
                 const minimumAmount = (destinationAmount * (slippageDenominator - slippageBps) + slippageDenominator - 1n) /
                     slippageDenominator;
                 const approve = Actions.token.approve.call(client, {
@@ -1040,10 +1168,19 @@ export function 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 },
+                ];
+                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);
@@ -1056,18 +1193,18 @@ export function 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' })),
                         chainId,
                     },
                 }), 200);
@@ -1078,14 +1215,11 @@ export function exchanges(options = {}) {
                 tokenOut: request.destinationToken,
             });
             if (sourceAmount === 0n)
-                return quoteNotAvailable(c);
-            const maximumAmount = (sourceAmount * (slippageDenominator + slippageBps)) / slippageDenominator;
+                throw new ExchangeProvider.RouteUnavailableError();
+            const maximumAmount = (sourceAmount * (slippageDenominator + slippageBps) + slippageDenominator - 1n) /
+                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,
-                });
+                throw new NativeDexAmountOutOfRangeError();
             const approve = Actions.token.approve.call(client, {
                 amount: maximumAmount,
                 spender: Addresses.stablecoinDex,
@@ -1097,10 +1231,19 @@ export function 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 },
+            ];
+            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);
@@ -1112,34 +1255,184 @@ export function 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' })),
                     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))
+            if (!(cause instanceof ExchangeProvider.RouteUnavailableError) &&
+                !isQuoteUnavailable(cause) &&
+                !amountOutOfRange)
+                return Response.upstream(c, cause);
+            if (!request.account)
                 return quoteNotAvailable(c);
-            if (cause instanceof Valuation.UnsupportedDenominationError)
-                return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 });
+            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);
         }
     })
@@ -1180,10 +1473,6 @@ export function 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,
@@ -1192,7 +1481,6 @@ export function exchanges(options = {}) {
                 limit: options.limit,
                 maker: options.maker,
                 order: options.order,
-                pairIndex,
                 participant: options.participant,
                 taker: options.taker,
                 toBlock: options['blockNumber.to'],
@@ -1201,14 +1489,14 @@ export function 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)
                 : undefined;
@@ -1275,7 +1563,7 @@ export function 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);
         }
@@ -1352,7 +1640,7 @@ export function 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,
@@ -1437,7 +1725,7 @@ export function exchanges(options = {}) {
             let baseToken = { address: target.base };
             let quoteToken = { 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,
@@ -1503,18 +1791,19 @@ export function exchanges(options = {}) {
         const options = c.req.valid('query');
         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;
             if (options.base !== undefined) {
-                const target = pairIndex.get(options.base);
+                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 });
+                    return pairNotFoundError(c, {
+                        base: options.base,
+                        pairIndex: await getPairIndex(c, { chainId }),
+                    });
                 pair = target;
             }
             const page = await getOrders(c, {
@@ -1525,7 +1814,6 @@ export function exchanges(options = {}) {
                 order: options.order,
                 page: options.page,
                 pair,
-                pairIndex,
                 side: options.side,
                 sort: options.sort,
             });
@@ -1535,7 +1823,7 @@ export function 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,
@@ -1815,7 +2103,7 @@ export function exchanges(options = {}) {
             let base = { address: target.base };
             let quote = { 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,
@@ -1906,7 +2194,7 @@ export function exchanges(options = {}) {
             let base = { address: target.base };
             let quote = { 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,
@@ -1943,51 +2231,6 @@ function pairNotFoundError(c, options) {
         : 'Pair not found';
     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, options) {
-    const { addresses, chainId, include } = options;
-    const includeLogoUri = include.includes('token.logoUri');
-    const includeVerified = include.includes('token.verified');
-    const tokensByAddress = new Map();
-    const uniqueTokens = [...new Set(addresses)];
-    if (uniqueTokens.length === 0)
-        return tokensByAddress;
-    const snapshot = includeLogoUri || includeVerified
-        ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
-        : undefined;
-    const resolved = await Timing.time(c, 'tokens', () => Promise.all(uniqueTokens.map(async (token) => {
-        try {
-            const [logoUri, metadata] = await Promise.all([
-                includeLogoUri
-                    ? Timing.time(c, 'token_logo', () => Tokens.getTokenLogo(c, { address: token, chainId })).catch(() => undefined)
-                    : undefined,
-                Timing.time(c, 'token_metadata', () => Tokens.getTokenMetadata(c, { address: token, chainId })),
-            ]);
-            return [
-                token,
-                {
-                    address: token,
-                    currency: metadata.currency,
-                    decimals: metadata.decimals,
-                    id: token,
-                    logoUri: includeLogoUri
-                        ? (logoUri ?? snapshot?.byAddress.get(token)?.logoUri ?? metadata.logoUri)
-                        : undefined,
-                    name: metadata.name,
-                    symbol: metadata.symbol,
-                    verified: includeVerified ? snapshot?.byAddress.has(token) : undefined,
-                },
-            ];
-        }
-        catch {
-            return [token, undefined];
-        }
-    })));
-    for (const [token, metadata] of resolved)
-        if (metadata)
-            tokensByAddress.set(token, metadata);
-    return tokensByAddress;
-}
 async function getPairs(c, options) {
     if (options.sort === 'liquidity')
         return getPairsByLiquidity(c, options);
@@ -2187,6 +2430,86 @@ async function getPairIndex(c, options) {
         ttl: Ttl.minutes(5),
     })).then((entries) => new Map(entries));
 }
+/**
+ * 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, options) {
+    const { bases, chainId } = options;
+    const pairs = new Map();
+    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
+        `,
+            });
+            // 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;
+    });
+}
+/**
+ * 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, 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
+      `,
+        });
+        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 };
+    });
+}
 /**
  * Validates and shapes one `PairCreated` row into the internal pair shape.
  * Returns `undefined` for malformed rows so the caller can drop them without
@@ -2248,7 +2571,7 @@ function parsePairRow(row) {
  * no candidate is discarded after the query runs.
  */
 async function getSwaps(c, options) {
-    const { chainId, cursor: cursorToken, fromBlock, fromTimestamp, limit, maker, order, pairIndex, participant, taker, toBlock, toTimestamp, transactionHash, } = options;
+    const { chainId, cursor: cursorToken, fromBlock, fromTimestamp, limit, maker, order, participant, taker, toBlock, toTimestamp, transactionHash, } = options;
     const tidx = c.get('getTidx')(chainId);
     const direction = order === 'asc' ? 'ASC' : 'DESC';
     // Keyset cursor on `(block_num, group first_idx, row first log_idx)`: the
@@ -2370,16 +2693,17 @@ async function getSwaps(c, options) {
                     ...new Set(groups.flatMap((group) => group.fills.map((fill) => fill.orderId))),
                 ],
             }));
-            // 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();
             for (const bookBase of bases) {
-                const indexed = pairIndex.get(bookBase);
+                const indexed = pairs.get(bookBase);
                 if (indexed)
                     quoteByBase.set(bookBase, indexed.quote);
             }
@@ -3212,11 +3536,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, 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 () => {
         // Snapshot is invariant in `(chainId, base?, maker?)`; sort/side/order are
@@ -3238,9 +3562,11 @@ async function getOrders(c, options) {
             side,
             sort,
         });
+        const bases = pair ? [] : [...new Set(pageRows.map((row) => row.token))];
+        const pairsByBase = await getPairsByBase(c, { bases, chainId });
         const data = [];
         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);
@@ -3470,11 +3796,17 @@ async function loadRestingOrders(c, options) {
     });
     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 = [];
+    const seen = new Set();
     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 };
@@ -3534,12 +3866,14 @@ export async function resolveBookReserves(c, options) {
         return { reserves, truncated: false };
     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 = [];
     const perToken = new Map();
+    const rawPerToken = new Map();
+    const seen = new Set();
     for (let i = 0; i < unique.length; i += reserveBaseInBatchSize) {
         const group = unique.slice(i, i + reserveBaseInBatchSize);
         const list = group.map((base) => `'${base}'`).join(', ');
@@ -3558,11 +3892,18 @@ export async function resolveBookReserves(c, options) {
             const parsed = parsePlacedRow(row);
             if (!parsed)
                 continue;
-            const count = perToken.get(parsed.token) ?? 0;
-            if (count >= scanCap) {
+            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)
+                continue;
+            seen.add(parsed.orderId);
             perToken.set(parsed.token, count + 1);
             placed.push(parsed);
         }
@@ -3649,6 +3990,9 @@ async function fetchCancelledByIds(c, options) {
     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({
@@ -3681,6 +4025,9 @@ async function fetchFillSumsByIds(c, options) {
     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({
@@ -3773,30 +4120,27 @@ async function getOrder(c, options) {
     const client = c.get('getClient')(chainId);
     return Timing.time(c, 'order', () => 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;
@@ -3852,11 +4196,139 @@ function isOrderDoesNotExist(error) {
     return (revert instanceof ContractFunctionRevertedError &&
         revert.data?.errorName === 'OrderDoesNotExist');
 }
-/** Returns the native DEX 404 used when no executable quote is available. */
+async function providerQuoteResponse(c, options) {
+    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, address, token) => ({
+        ...Value.tokenAmount({ baseUnits, currency: token.currency, decimals: token.decimals }),
+        valuation: Valuation.valuationFor({
+            amount: BigInt(baseUnits),
+            denomination,
+            rates,
+            token: snapshot?.byAddress.get(address.toLowerCase()),
+        }),
+    });
+    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) {
+    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,
+    };
+}
+async function validateProviderCalls(client, 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();
+    }
+}
+/** Converts estimated gas units to a native-token base-unit fee. */
+function gasCost(options) {
+    return (options.gasPrice * options.gasUnits).toString();
+}
+/** Returns the 404 used when no executable quote is available. */
 function quoteNotAvailable(c) {
     return Response.error(c, {
         code: 'quote_not_available',
-        message: 'No executable quote is available on Tempo’s native DEX',
+        message: 'No configured exchange provider has an executable quote',
         status: 404,
     });
 }
@@ -3964,18 +4436,6 @@ async function countOrderFills(c, options) {
         ttl: Ttl.seconds(10),
     }));
 }
-/**
- * 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, options) {
-    const pairsByBase = await getPairIndex(c, options);
-    const pairsByKey = new Map();
-    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
@@ -4009,4 +4469,7 @@ function parseOrderFillRow(row) {
         transactionHash: transactionHash.data,
     };
 }
+class NativeDexAmountOutOfRangeError extends Error {
+    name = 'Exchanges.NativeDexAmountOutOfRangeError';
+}
 //# sourceMappingURL=exchanges.js.map