@gibs/quotes 1.13.0

package/dist/carriers/lifi.js

@@ -0,0 +1,217 @@
+import { lifiEndpoints } from '@gibs/bridge-sdk/consolidated-quote';
+import { buildLifiPreQuoteRequest, lifiQuoteUrl, parseLifiPreQuote } from '@gibs/bridge-sdk/pre-quote';
+import { readLifiRefusal } from '../quote-refusals.js';
+import { createCalibrationStore } from './calibration.js';
+import { createLifiPriceCatalogue, estimateDeliveredAmount } from './price-catalogue.js';
+/** Headers for a LI.FI request FROM THIS CARRIER — never `@gibs/bridge-sdk/consolidated-quote`'s `lifiRequestHeaders`, which deliberately NEVER sends an api key because it is written for the browser bundle. This carrier can run on a server, where `LifiProviderConfig.apiKey` is a real secret meant to travel in this header. */
+const lifiCarrierHeaders = (apiKey) => ({
+    'Content-Type': 'application/json',
+    ...(apiKey === undefined ? {} : { 'x-lifi-api-key': apiKey }),
+});
+const cannotCarryAnswer = (reason) => ({
+    ok: false,
+    refusal: { kind: 'cannot-carry', reason, minimumAmount: null },
+});
+const couldNotAskAnswer = (reason) => ({
+    ok: false,
+    refusal: { kind: 'could-not-ask', reason, minimumAmount: null },
+});
+/**
+ * Builds LI.FI as a {@link ProviderAsker}.
+ *
+ * @param options - see {@link CreateLifiCarrierOptions}
+ * @returns the carrier
+ */
+export const createLifiCarrier = (options) => {
+    const { config, probeAddresses, chainList } = options;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const priceCatalogue = options.priceCatalogue ?? createLifiPriceCatalogue({ baseUrl: config?.baseUrl, fetchImpl });
+    const calibrationStore = options.calibrationStore ?? createCalibrationStore();
+    /**
+     * A provider-model estimate for this edge — see `types.ts`'s
+     * `Carrier.estimate` doc and `price-catalogue.ts`'s `estimateDeliveredAmount`
+     * for the shared arithmetic.
+     *
+     * FEE MODEL, READ FROM LI.FI'S OWN DOCUMENTATION
+     * (`docs.li.fi/introduction/integrating-lifi/monetizing-integration`,
+     * read 2026-09-24): the `fee` query parameter is "a float number e.g 0.02
+     * refers to 2% of the transaction volume" — {@link LifiProviderConfig.fee}
+     * is forwarded there verbatim by `ask()`, so it is the one percentage
+     * charge this estimate can price EXACTLY, because it is this host's own
+     * configured number, not a guess about LI.FI's.
+     *
+     * WHAT IS NOT MODELED, ON PURPOSE. LI.FI's own "LIFI Fixed Fee" and the
+     * chosen bridge/tool's own fee (a "Relayer fee" and "Relayer gas fee" on
+     * the across-bridge quote recorded in
+     * `packages/bridge-sdk/src/__fixtures__/lifi/contract-quote-success-eth-to-base-usdc.json`,
+     * together about 0.27% of that quote) are NOT standardized: LI.FI
+     * aggregates upwards of twenty bridges, each pricing its own crossing
+     * differently, and which one a given quote picks is not known ahead of a
+     * live `ask()`. Left to {@link calibrationStore}, keyed by
+     * (`'lifi'`, `edge.from.chainId`, `edge.to.chainId`) — for a repeatedly
+     * quoted chain pair, the SAME bridge tends to win, so the gap this leaves
+     * is close to constant and calibration converges to it quickly.
+     *
+     * Destination gas is not subtracted either: the recorded fixture's own
+     * `estimate.gasCosts` entry is `"type": "SEND"` — gas the READER's wallet
+     * pays directly, in the origin chain's native currency, never taken out of
+     * `toAmount`. So there is no fixed cost, in the OUTPUT token, to subtract.
+     */
+    const estimate = (edge, amountIn) => {
+        const priceFromUsd = priceCatalogue.priceUsd(edge.from);
+        const priceToUsd = priceCatalogue.priceUsd(edge.to);
+        if (priceFromUsd === null || priceToUsd === null)
+            return null;
+        const integratorFee = config?.fee !== undefined && config.fee > 0 ? config.fee : 0;
+        const calibrationFactor = calibrationStore.factor({
+            providerId: 'lifi',
+            fromChainId: edge.from.chainId,
+            toChainId: edge.to.chainId,
+        });
+        return {
+            deliveredAmount: estimateDeliveredAmount({
+                amountIn,
+                fromDecimals: edge.from.decimals,
+                toDecimals: edge.to.decimals,
+                priceFromUsd,
+                priceToUsd,
+                percentageFee: integratorFee,
+                fixedCostUsd: 0,
+                calibrationFactor,
+            }),
+        };
+    };
+    const edgesFrom = (from, to) => {
+        // LI.FI quotes Ethereum-Virtual-Machine chains only, on both sides — see
+        // `PreQuoteRequest`'s own doc and `buildLifiPreQuoteRequest`'s non-Ethereum-origin refusal.
+        if (from.ecosystem !== 'evm' || to.ecosystem !== 'evm')
+            return [];
+        const chainIds = chainList.chainIds('lifi');
+        if (chainIds === null)
+            return [];
+        if (!chainIds.has(from.chainId) || !chainIds.has(to.chainId))
+            return [];
+        return [{ carrier: 'lifi', from, to, fusesNext: false, origin: 'wallet', floors: [] }];
+    };
+    const ask = async ({ edge, inputAmount }) => {
+        if (inputAmount <= 0n)
+            return cannotCarryAnswer('non-positive input amount');
+        const fromAddress = probeAddresses?.[edge.from.ecosystem];
+        const recipientAddress = probeAddresses?.evm;
+        if (fromAddress === undefined || recipientAddress === undefined) {
+            return cannotCarryAnswer('no probe address configured for this ecosystem');
+        }
+        const request = {
+            fromChainId: edge.from.chainId,
+            fromTokenAddress: edge.from.address,
+            fromAddress,
+            toChainId: edge.to.chainId,
+            toTokenAddress: edge.to.address,
+            amount: inputAmount,
+            recipient: recipientAddress,
+            ...(edge.from.ecosystem === 'evm' ? {} : { originVmType: edge.from.ecosystem }),
+            // ALWAYS SET, NEVER LEFT `undefined`. `buildLifiPreQuoteRequest` falls
+            // back to `@gibs/bridge-sdk/consolidated-quote`'s `lifiIntegrator`
+            // constant ('gibs.finance') when `lifiIntegrator` is `undefined` —
+            // exactly the gibs default this package must never send unconfigured.
+            // `null` (not `''`) tells the builder to OMIT the query parameter
+            // entirely when the host configured none — an empty string would still
+            // be a literal, present `integrator=` LI.FI could record or reject.
+            lifiIntegrator: config?.integrator ?? null,
+        };
+        const query = buildLifiPreQuoteRequest(request);
+        if (query === null)
+            return cannotCarryAnswer(null);
+        // NEVER ASK A PROVIDER ABOUT A CHAIN IT DOES NOT LIST. `chainList.chainIds`
+        // returns null while the list has never loaded (or has aged out past its
+        // stale grace window) — that is a `could-not-ask`, distinct from a chain
+        // the list has genuinely never carried, which is `cannot-carry`.
+        const chainIds = chainList.chainIds('lifi');
+        if (chainIds === null)
+            return couldNotAskAnswer('LI.FI chain list not loaded');
+        if (!chainIds.has(edge.from.chainId) || !chainIds.has(edge.to.chainId)) {
+            return cannotCarryAnswer("LI.FI does not list one of this hop's chains");
+        }
+        const params = new URLSearchParams(query);
+        if (config?.fee !== undefined && config.fee > 0) {
+            params.set('fee', config.fee.toString());
+        }
+        const quoteUrl = config?.baseUrl === undefined ? lifiQuoteUrl : lifiEndpoints(config.baseUrl).quote;
+        let response;
+        try {
+            response = await fetchImpl(`${quoteUrl}?${params.toString()}`, {
+                headers: lifiCarrierHeaders(config?.apiKey),
+            });
+        }
+        catch (error) {
+            return couldNotAskAnswer(error instanceof Error ? error.message : null);
+        }
+        if (!response.ok) {
+            const body = await response.json().catch(() => null);
+            const refusal = readLifiRefusal(response.status, body);
+            return {
+                ok: false,
+                refusal: {
+                    // `CarrierRefusalKind` has no `invalid-api-key` member — see
+                    // `types.ts`'s `CarrierRefusalKind` doc; a rejected key means the
+                    // ask never got a real answer, the same fact `could-not-ask` carries.
+                    kind: refusal.kind === 'invalid-api-key' ? 'could-not-ask' : refusal.kind,
+                    reason: refusal.reason,
+                    minimumAmount: refusal.minimumAmount ?? null,
+                },
+            };
+        }
+        const result = parseLifiPreQuote(await response.json());
+        if (result === null)
+            return couldNotAskAnswer('LI.FI pre-quote response had an unexpected shape');
+        // CALIBRATES `estimate()` AGAINST THIS CONFIRMED QUOTE, when a prior
+        // catalogue price makes a comparison possible — see `estimate`'s own doc
+        // and `calibration.ts`'s head note. A `null` estimate (no price loaded
+        // for this edge yet) simply records nothing; there is no ratio to learn.
+        const priorEstimate = estimate(edge, inputAmount);
+        if (priorEstimate !== null) {
+            calibrationStore.record({ providerId: 'lifi', fromChainId: edge.from.chainId, toChainId: edge.to.chainId }, result.expectedAmount, priorEstimate.deliveredAmount);
+        }
+        return {
+            ok: true,
+            deliveredAmount: result.expectedAmount,
+            minimumDeliveredAmount: result.minimumAmount,
+            claimedDurationSeconds: null,
+        };
+    };
+    return {
+        id: 'lifi',
+        edgesFrom,
+        ask,
+        // Warms `priceCatalogue` for every node the search might branch through,
+        // so `estimate()` (a synchronous read — see `types.ts`) never has to ask
+        // the network itself. See `price-catalogue.ts`'s `LifiPriceCatalogue.ensureLoaded`.
+        //
+        // FILTERED TO CHAINS LI.FI ITSELF LISTS, FIRST — the SAME
+        // "never ask a provider about a chain it does not list" gate `ask` uses
+        // a few lines up, applied here too. `nodes` is the WHOLE search's node
+        // universe (see `types.ts`'s `Carrier.prepare` doc), which on this
+        // codebase's own host includes PulseChain — a chain neither LI.FI nor
+        // Relay lists (`chainList.chainIds('lifi')` never contains it; see
+        // `packages/bridge-sdk/src/__fixtures__/relay/README.md`'s identical
+        // note for Relay). Filtering here, rather than trusting
+        // `ensureLoaded` never to be asked about an unlisted chain, is what
+        // keeps this carrier from ever naming that chain to LI.FI at all.
+        prepare: async (nodes) => {
+            const chainIds = chainList.chainIds('lifi');
+            if (chainIds === null)
+                return;
+            const listedNodes = nodes.filter((node) => chainIds.has(node.chainId));
+            await priceCatalogue.ensureLoaded(listedNodes);
+        },
+        estimate,
+        isRateLimited: true,
+        depositMode: 'wallet-signed',
+        sender: 'aggregator',
+        // A provisional prior for pre-quote scoring, not a measured figure —
+        // LI.FI itself only ever reports a duration per-quote (this carrier's
+        // own `ask` answers `claimedDurationSeconds: null`, above), because it
+        // routes through whichever underlying bridge a given quote picks.
+        settlementSeconds: 300,
+    };
+};

package/dist/carriers/near-intents.d.ts

@@ -0,0 +1,91 @@
+import type { Ecosystem } from '@gibs/bridge-sdk/ecosystems';
+import { type NearIntentsAsset } from '@gibs/bridge-sdk/near-intents';
+import type { ChainListRegistry } from '../chain-lists.js';
+import { type CalibrationStore } from './calibration.js';
+import type { CarrierHopEdge, NearIntentsProviderConfig, ProviderAsker } from '../types.js';
+/**
+ * NEAR Intents as a built-in {@link ProviderAsker}: ALWAYS a `dry: true`
+ * `POST /v0/quote` — never a live one — ported from
+ * `packages/ui/src/lib/state/route-search-quotes.ts`'s `askNearIntentsEdge`.
+ * See `docs/quote-service.md`'s "Rules that never bend": "Binding quotes
+ * (... NEAR live quote reserving a deposit address) are never cached or
+ * shared" — this carrier exists for DISPLAY only, and a live quote is a
+ * separate, deliberately un-built concern this package leaves to whichever
+ * caller executes a route. See `carriers/lifi.ts`'s head note for why every
+ * request here should go through `UpstreamFunnel.guardedFetch` bound to
+ * `'near-intents'`.
+ *
+ * READS ITS ASSET LIST FROM THE CHAIN-LIST REGISTRY, NOT A SEPARATE FETCH.
+ * `chain-lists.ts`'s `nearIntentsChainListSource` already fetches
+ * `GET /v0/tokens` on the shared refresh cadence and keeps the full parsed
+ * asset list as its `capability` payload — this carrier reads that rather
+ * than fetching the same endpoint a second time under a second schedule.
+ */
+/** What {@link createNearIntentsCarrier} needs beyond the edge and amount it is asked about. */
+export type CreateNearIntentsCarrierOptions = {
+    /** NEAR Intents' own configuration — the host's partner key, referral tag, and base url override. */
+    readonly config?: NearIntentsProviderConfig;
+    /** A server-held address, per ecosystem — see `carriers/lifi.ts`'s identical field for the full contract. */
+    readonly probeAddresses?: Readonly<Partial<Record<Ecosystem, string>>>;
+    /**
+     * The chain-list registry `chain-lists.ts` builds — read under the
+     * `'near-intents'` key for BOTH the chain-id gate and, via `capability`,
+     * the asset list a request is built from.
+     */
+    readonly chainList: Pick<ChainListRegistry, 'chainIds' | 'capability'>;
+    /** The `fetch` this carrier's own request goes through — see `carriers/lifi.ts`'s identical field. */
+    readonly fetchImpl?: typeof fetch;
+    /**
+     * This carrier's own {@link CalibrationStore}, correcting {@link Carrier.estimate}
+     * against confirmed `ask()` results. Defaults to an in-memory
+     * `createCalibrationStore()` — see `carriers/lifi.ts`'s identical field.
+     */
+    readonly calibrationStore?: CalibrationStore;
+};
+/**
+ * Whether an edge is the "stable-same-asset" tier
+ * {@link nearIntentsAuthenticatedStablecoinFeeBasisPoints} names: "a
+ * stablecoin pair OR a same-asset multi-chain route" (that constant's own
+ * doc, read from `docs.near-intents.org/integration/distribution-channels/1click-api/authentication`
+ * on 2026-09-18). MODELED AS "same symbol on both ends," never a stablecoin
+ * whitelist: {@link NearIntentsAsset} carries a `symbol` this service itself
+ * assigned, so two assets sharing one symbol across chains is exactly the
+ * literal "same-asset multi-chain route" the discount names, measured
+ * rather than guessed. A DIFFERENT-SYMBOL stablecoin pair (say USD Coin
+ * into Tether) is NOT caught by this check and prices at the ordinary
+ * authenticated rate instead of the discount — a documented gap
+ * {@link CalibrationStore} absorbs per chain pair, same as the other two
+ * built-in carriers' own unmodeled tiers.
+ *
+ * @param options.assets - the parsed asset list
+ * @param options.edge - the candidate hop
+ * @returns whether both ends resolve to the same service-reported symbol
+ */
+export declare const isNearIntentsStableSameAsset: ({ assets, edge, }: {
+    readonly assets: readonly NearIntentsAsset[];
+    readonly edge: CarrierHopEdge;
+}) => boolean;
+/**
+ * NEAR Intents' own percentage fee for an edge, in basis points — read from
+ * `@gibs/bridge-sdk/near-intents`'s own constants, sourced from
+ * `docs.near-intents.org/integration/distribution-channels/1click-api/authentication`
+ * (2026-09-18): 25 basis points with no partner key, 20 with one, 1 on a
+ * partner-key stable-same-asset route (see {@link isNearIntentsStableSameAsset}).
+ * `withdrawFee` — the service's other real charge, quoted live per quote —
+ * is NOT modeled here; see `estimate`'s own doc.
+ *
+ * @param options.authenticated - whether a partner key is configured (`config.apiKey !== undefined`)
+ * @param options.stableSameAsset - {@link isNearIntentsStableSameAsset}'s own answer for this edge
+ * @returns the fee, in basis points
+ */
+export declare const nearIntentsFeeBasisPoints: ({ authenticated, stableSameAsset, }: {
+    readonly authenticated: boolean;
+    readonly stableSameAsset: boolean;
+}) => number;
+/**
+ * Builds NEAR Intents as a {@link ProviderAsker}.
+ *
+ * @param options - see {@link CreateNearIntentsCarrierOptions}
+ * @returns the carrier
+ */
+export declare const createNearIntentsCarrier: (options: CreateNearIntentsCarrierOptions) => ProviderAsker;

package/dist/carriers/near-intents.js

@@ -0,0 +1,249 @@
+import { buildNearIntentsQuoteRequest, findNearIntentsAsset, nearIntentsAuthenticatedFeeBasisPoints, nearIntentsAuthenticatedStablecoinFeeBasisPoints, nearIntentsQuoteUrl, nearIntentsRequestHeaders, nearIntentsUnauthenticatedFeeBasisPoints, parseNearIntentsPreQuote, } from '@gibs/bridge-sdk/near-intents';
+import { readNearIntentsRefusal } from '../quote-refusals.js';
+import { createCalibrationStore } from './calibration.js';
+import { estimateDeliveredAmount, nearIntentsPriceCatalogueFromAssets } from './price-catalogue.js';
+const cannotCarryAnswer = (reason) => ({
+    ok: false,
+    refusal: { kind: 'cannot-carry', reason, minimumAmount: null },
+});
+const couldNotAskAnswer = (reason) => ({
+    ok: false,
+    refusal: { kind: 'could-not-ask', reason, minimumAmount: null },
+});
+/**
+ * Reads the asset list `nearIntentsChainListSource` cached, narrowed to its
+ * real shape. `capability` is `unknown` at the registry's own boundary (see
+ * `chain-lists.ts`'s `ChainListLoadResult` doc for why); this is the one
+ * place that narrows it back, because only this carrier's own source
+ * produces it.
+ */
+const assetsFrom = (chainList) => {
+    const capability = chainList.capability('near-intents');
+    return Array.isArray(capability) ? capability : [];
+};
+/**
+ * Whether an edge is the "stable-same-asset" tier
+ * {@link nearIntentsAuthenticatedStablecoinFeeBasisPoints} names: "a
+ * stablecoin pair OR a same-asset multi-chain route" (that constant's own
+ * doc, read from `docs.near-intents.org/integration/distribution-channels/1click-api/authentication`
+ * on 2026-09-18). MODELED AS "same symbol on both ends," never a stablecoin
+ * whitelist: {@link NearIntentsAsset} carries a `symbol` this service itself
+ * assigned, so two assets sharing one symbol across chains is exactly the
+ * literal "same-asset multi-chain route" the discount names, measured
+ * rather than guessed. A DIFFERENT-SYMBOL stablecoin pair (say USD Coin
+ * into Tether) is NOT caught by this check and prices at the ordinary
+ * authenticated rate instead of the discount — a documented gap
+ * {@link CalibrationStore} absorbs per chain pair, same as the other two
+ * built-in carriers' own unmodeled tiers.
+ *
+ * @param options.assets - the parsed asset list
+ * @param options.edge - the candidate hop
+ * @returns whether both ends resolve to the same service-reported symbol
+ */
+export const isNearIntentsStableSameAsset = ({ assets, edge, }) => {
+    const originAsset = findNearIntentsAsset({
+        assets,
+        chainId: edge.from.chainId,
+        tokenAddress: edge.from.address,
+        ecosystem: edge.from.ecosystem,
+    });
+    const destinationAsset = findNearIntentsAsset({
+        assets,
+        chainId: edge.to.chainId,
+        tokenAddress: edge.to.address,
+        ecosystem: edge.to.ecosystem,
+    });
+    if (originAsset === null || destinationAsset === null)
+        return false;
+    return originAsset.symbol.toLowerCase() === destinationAsset.symbol.toLowerCase();
+};
+/**
+ * NEAR Intents' own percentage fee for an edge, in basis points — read from
+ * `@gibs/bridge-sdk/near-intents`'s own constants, sourced from
+ * `docs.near-intents.org/integration/distribution-channels/1click-api/authentication`
+ * (2026-09-18): 25 basis points with no partner key, 20 with one, 1 on a
+ * partner-key stable-same-asset route (see {@link isNearIntentsStableSameAsset}).
+ * `withdrawFee` — the service's other real charge, quoted live per quote —
+ * is NOT modeled here; see `estimate`'s own doc.
+ *
+ * @param options.authenticated - whether a partner key is configured (`config.apiKey !== undefined`)
+ * @param options.stableSameAsset - {@link isNearIntentsStableSameAsset}'s own answer for this edge
+ * @returns the fee, in basis points
+ */
+export const nearIntentsFeeBasisPoints = ({ authenticated, stableSameAsset, }) => {
+    if (!authenticated)
+        return nearIntentsUnauthenticatedFeeBasisPoints;
+    return stableSameAsset ? nearIntentsAuthenticatedStablecoinFeeBasisPoints : nearIntentsAuthenticatedFeeBasisPoints;
+};
+/**
+ * Builds NEAR Intents as a {@link ProviderAsker}.
+ *
+ * @param options - see {@link CreateNearIntentsCarrierOptions}
+ * @returns the carrier
+ */
+export const createNearIntentsCarrier = (options) => {
+    const { config, probeAddresses, chainList } = options;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const calibrationStore = options.calibrationStore ?? createCalibrationStore();
+    /**
+     * A provider-model estimate for this edge — see `types.ts`'s
+     * `Carrier.estimate` doc, `price-catalogue.ts`'s `estimateDeliveredAmount`
+     * for the shared arithmetic, and `nearIntentsFeeBasisPoints` for the fee
+     * model and its sources.
+     *
+     * NO FIXED COST IS MODELED. `withdrawFee` is real (the recorded fixture
+     * `packages/bridge-sdk/src/__fixtures__/near-intents/contract-quote-dry-success-base-to-eth-usdc.json`
+     * charges 300000 base units of destination USD Coin, about 1.1% of that
+     * quote's output) but the service prices it live, per quote, tracking its
+     * own operating cost — there is no published flat figure to read ahead of
+     * an `ask()`. Left to {@link CalibrationStore}, same as the other two
+     * built-in carriers' own unmodeled fixed costs.
+     */
+    const estimate = (edge, amountIn) => {
+        const assets = assetsFrom(chainList);
+        const priceCatalogue = nearIntentsPriceCatalogueFromAssets(assets);
+        const priceFromUsd = priceCatalogue.priceUsd(edge.from);
+        const priceToUsd = priceCatalogue.priceUsd(edge.to);
+        if (priceFromUsd === null || priceToUsd === null)
+            return null;
+        const feeBasisPoints = nearIntentsFeeBasisPoints({
+            authenticated: config?.apiKey !== undefined,
+            stableSameAsset: isNearIntentsStableSameAsset({ assets, edge }),
+        });
+        const calibrationFactor = calibrationStore.factor({
+            providerId: 'near-intents',
+            fromChainId: edge.from.chainId,
+            toChainId: edge.to.chainId,
+        });
+        return {
+            deliveredAmount: estimateDeliveredAmount({
+                amountIn,
+                fromDecimals: edge.from.decimals,
+                toDecimals: edge.to.decimals,
+                priceFromUsd,
+                priceToUsd,
+                percentageFee: feeBasisPoints / 10_000,
+                fixedCostUsd: 0,
+                calibrationFactor,
+            }),
+        };
+    };
+    const edgesFrom = (from, to) => {
+        // Every route this carrier expresses lands on an Ethereum-Virtual-Machine
+        // entry chain — see `ConsolidatedQuoteRequest.toTokenAddress`'s `Hex` type.
+        if (to.ecosystem !== 'evm')
+            return [];
+        const chainIds = chainList.chainIds('near-intents');
+        if (chainIds === null)
+            return [];
+        if (!chainIds.has(from.chainId) || !chainIds.has(to.chainId))
+            return [];
+        return [{ carrier: 'near-intents', from, to, fusesNext: false, origin: 'wallet', floors: [] }];
+    };
+    const ask = async ({ edge, inputAmount }) => {
+        if (inputAmount <= 0n)
+            return cannotCarryAnswer('non-positive input amount');
+        const assets = assetsFrom(chainList);
+        if (assets.length === 0)
+            return couldNotAskAnswer('NEAR Intents asset list not loaded');
+        const fromAddress = probeAddresses?.[edge.from.ecosystem];
+        const evmProbeAddress = probeAddresses?.evm;
+        if (fromAddress === undefined || evmProbeAddress === undefined) {
+            return cannotCarryAnswer('no probe address configured for this ecosystem');
+        }
+        // NEVER ASK ABOUT A CHAIN NEAR INTENTS DOES NOT LIST — see
+        // `carriers/lifi.ts`'s identical guard. Checked against the SAME derived
+        // chain-id set `edgesFrom` reads, so an ask this carrier was never
+        // offered as an edge is refused identically when asked directly.
+        const chainIds = chainList.chainIds('near-intents');
+        if (chainIds === null)
+            return couldNotAskAnswer('NEAR Intents chain list not loaded');
+        if (!chainIds.has(edge.from.chainId) || !chainIds.has(edge.to.chainId)) {
+            return cannotCarryAnswer("NEAR Intents does not list one of this hop's chains");
+        }
+        const request = {
+            fromChainId: edge.from.chainId,
+            fromTokenAddress: edge.from.address,
+            fromAddress,
+            connectedEthereumAccount: evmProbeAddress,
+            toChainId: edge.to.chainId,
+            toTokenAddress: edge.to.address,
+            toAmount: 0n,
+            fromAmount: inputAmount,
+            recipient: evmProbeAddress,
+            fallbackAddress: evmProbeAddress,
+            ...(edge.from.ecosystem === 'evm' ? {} : { originVmType: edge.from.ecosystem }),
+        };
+        const context = {
+            nearIntentsAssets: assets,
+            now: new Date(),
+            ...(config?.referral === undefined ? {} : { referral: config.referral }),
+        };
+        // ALWAYS dry — see this module's head note.
+        const body = buildNearIntentsQuoteRequest(request, context, { dry: true });
+        if (body === null)
+            return cannotCarryAnswer('NEAR Intents cannot express this pair');
+        const quoteUrl = config?.baseUrl === undefined ? nearIntentsQuoteUrl : `${config.baseUrl.replace(/\/+$/, '')}/v0/quote`;
+        let response;
+        try {
+            response = await fetchImpl(quoteUrl, {
+                method: 'POST',
+                body: JSON.stringify(body),
+                headers: nearIntentsRequestHeaders(config?.apiKey),
+            });
+        }
+        catch (error) {
+            return couldNotAskAnswer(error instanceof Error ? error.message : null);
+        }
+        if (!response.ok) {
+            const payload = await response.json().catch(() => null);
+            const refusal = readNearIntentsRefusal(response.status, payload);
+            return {
+                ok: false,
+                refusal: {
+                    kind: refusal.kind === 'invalid-api-key' ? 'could-not-ask' : refusal.kind,
+                    reason: refusal.reason,
+                    minimumAmount: refusal.minimumAmount ?? null,
+                },
+            };
+        }
+        const result = parseNearIntentsPreQuote(await response.json());
+        if (result === null)
+            return couldNotAskAnswer('NEAR Intents response had an unexpected shape');
+        // CALIBRATES `estimate()` AGAINST THIS CONFIRMED QUOTE — see `lifi.ts`'s
+        // identical note.
+        const priorEstimate = estimate(edge, inputAmount);
+        if (priorEstimate !== null) {
+            calibrationStore.record({ providerId: 'near-intents', fromChainId: edge.from.chainId, toChainId: edge.to.chainId }, result.expectedAmount, priorEstimate.deliveredAmount);
+        }
+        return {
+            ok: true,
+            deliveredAmount: result.expectedAmount,
+            minimumDeliveredAmount: result.minimumAmount,
+            claimedDurationSeconds: null,
+        };
+    };
+    return {
+        id: 'near-intents',
+        edgesFrom,
+        ask,
+        // No `prepare` — this carrier's own `estimate` derives its price
+        // catalogue synchronously from the asset list `chainList.capability`
+        // already carries (see `assetsFrom` and
+        // `price-catalogue.ts`'s `nearIntentsPriceCatalogueFromAssets`), fetched
+        // once on `chain-lists.ts`'s own refresh cadence — never a fetch of
+        // this carrier's own.
+        estimate,
+        isRateLimited: true,
+        // The one built-in carrier that can open a pay-by-hand origin's first
+        // hop, AND still runs as an ordinary wallet-signed aggregator mid-route
+        // — see `types.ts`'s own `CarrierDepositMode` doc for why this is
+        // `'either'` rather than a boolean.
+        depositMode: 'either',
+        sender: 'aggregator',
+        // A provisional prior for pre-quote scoring, not a measured figure — see
+        // `lifi.ts`'s own note; this carrier's own `ask` answers
+        // `claimedDurationSeconds: null` per-quote, above.
+        settlementSeconds: 120,
+    };
+};