ConfigParams

import type { ConfigParams } from "@spandex/core";

Params

providers

Aggregator[]

List of active provider aggregators. Each provider has a factory function that returns an Aggregator instance with its configuration. You can include multiple instances for the same provider to test alternate configurations.

Example:

import { fabric, zeroX } from "@spandex/core";
 
const providers = [
  zeroX({
    apiKey: "YOUR_0X_API_KEY",
    timeoutMs: 12_000,
    negotiatedFeatures: ["integratorFees"],
  }),
  fabric({
    appId: "YOUR_FABRIC_APP_ID",
  }),
];

proxy

AggregatorProxy

Proxy instance used to delegate quote fetching to a server endpoint. When proxy is set, you cannot set providers or options in the same config.

See Proxy Mode guide for service architecture and streaming details. In proxy mode, you must provide at least one delegatedActions entry. Those names match both the delegated function names and the route suffixes on the service. getQuotes and getQuote compose locally on the client. For the managed deployment helper, see Cloud Mode (beta).

Example:

import { createConfig, proxy } from "@spandex/core";
 
const config = createConfig({
  proxy: proxy({
    pathOrUrl: "https://example.com/api",
    delegatedActions: ["prepareSimulatedQuotes"],
  }),
});

options (optional)

AggregationOptions

options.deadlineMs

number | undefined

Maximum duration for the entire aggregation process before aborting pending requests. Defaults to 15,000 ms. Set a lower value for faster responses with potentially fewer quotes.

options.numRetries

number | undefined

Number of retry attempts per provider. Defaults to 1.

options.initialRetryDelayMs

number | undefined

Initial delay before retrying failed requests (exponential backoff applied). Defaults to 100 ms.

options.integratorFeeAddress

Address | undefined

Address that should receive the integrator fee. Use this if your application collects fees on swaps from end users. Only applicable if the provider supports integrator fees. Some providers may require a custom API key tied to your integrator fee address.

options.integratorSwapFeeBps

number | undefined

Swap fee for the integrator (in basis points). Only applicable if the provider supports integrator fees.

options.integratorSurplusBps

number | undefined

Surplus share for the integrator (in basis points). Only applicable if the provider supports surplus sharing.

Fee and surplus settings are optimistic: providers that do not support the requested features may still return quotes, and selection will prefer quotes with more activated fee features before applying the secondary strategy (best price, lowest gas, etc).

clients (optional)

PublicClient[] | ((chainId: number) => PublicClient | undefined)

A list of viem/wagmi clients or a lookup function to get the client for a specific chain ID. This is used to fetch on-chain data for quote simulation and validation. If not provided, getQuotes, getQuote, and simulation utilities will fail. If you wish to only get quotes without validating onchain, use getRawQuotes instead. When using SpandexProvider, the wagmi clients from the provider will be used automatically.

When using proxy mode, server-streamed simulated quotes do not require a local client for getQuotes/getQuote. Local clients are still useful if you call lower-level simulation utilities directly.

Note: The public client is used to simulate quotes and validate them onchain. This requires an RPC provider which supports this, and many public providers do not. Please ensure your viem client is setup with a compatible RPC provider (e.g. Alchemy, Infura, etc). Additionally, you can setup RPC failover in your client configuration to improve reliability of quote fetching and simulation. See viem documentation for more details.

logging (optional)

{ level: "info" | "debug" | "trace"; fn?: (level, ...args) => void }

Enables the optional global logger used by the core library. This is helpful when you want to understand quote retries, deadlines, or simulation failures without wiring a full logging system. If fn is omitted, spanDEX logs to console.log using the format [level] - ....

logging.level

"info" | "debug" | "trace"

Minimum level to emit. For example, "info" logs info only, "debug" logs info + debug, and "trace" logs everything.

logging.fn (optional)

(level: "info" | "debug" | "trace", ...args: unknown[]) => void

Custom logging function. The first argument is the log level, followed by the structured log arguments from the library.

Example:

import { createConfig, fabric } from "@spandex/core";
 
const config = createConfig({
  providers: [fabric({ appId: "YOUR_FABRIC_APP_ID" })],
  logging: {
    level: "debug",
    fn: (level, ...args) => {
      myLogger.log({ level, event: "spandex", args });
    },
  },
});