# spanDEX

> DEX meta-aggregator library for optimal token swaps

## Advanced

#### Configuration

Deadlines, timeouts, retries, etc

#### Overrides

#### Promise Chaining


## Examples

If you build something cool with spanDEX, let us know.

* [spanDEX Swap Demo](https://demo.spandex.sh) - Swap interface which compares performance of multiple aggregators and continuously provides the best price
* [QuoteBench](https://benchmark.withfabric.xyz) - A benchmarking tool to compare stability, latency, accuracy, and price across aggregators and chains over time
* [Hono Proxy](https://github.com/withfabricxyz/spandex/tree/main/examples/hono) - A minimal meta-aggregator API server built with Hono and spanDEX


## Fees

This page moved to [Configuration > Fees](/configuration/fees).


import { Button } from 'vocs/components'

## Getting Started

Depending on your project stack and state, there are multiple ways to get started with spanDEX.

## Existing Projects

See [installation instructions](/installation.mdx) for details on how to add spanDEX to your existing project. For react applications, see the [React getting started guide](/react/getting-started.mdx). Otherwise, see the [Core getting started guide](/core/getting-started.mdx).

## New Projects

We currently don't have a CLI available, but we're working on it! In the meantime, you can follow the instructions in the [Core getting started guide](/core/getting-started.mdx) to set up spanDEX in your project.


## Installation

### Core

`@spandex/core` provides all the functionality to interact with multiple aggregators, simulate quotes onchain, and execute swaps. It depends on `viem` for blockchain interactions.

:::code-group
```bash [npm]
npm i viem @spandex/core
```

```bash [bun]
bun i viem @spandex/core
```

```bash [pnpm]
pnpm i viem @spandex/core
```
:::

### React

`@spandex/react` provides React hooks for integrating spanDEX into your React applications. It depends on `wagmi`.

:::code-group
```bash [npm]
npm i wagmi @spandex/react
```

```bash [bun]
bun i wagmi @spandex/react
```

```bash [pnpm]
pnpm i wagmi @spandex/react
```
:::

### Security Considerations

Given that spanDEX presents unsigned transaction data for execution, it's crucial have a security stance. Some recommended practices include:

* Lock or pin dependencies to specific versions to reduce supply chain attack risk.
* Use a package manager that supports integrity checks, such as npm or yarn, to verify the authenticity of packages.
* Require packages have a minimum age before updating, using pnpms minimumReleaseAge or similar features in other package managers.
* Ensure web apps have Content Security Policies (CSP) in place to mitigate risks from malicious scripts.
* Remember that supply chain attacks are real and the EVM is a ripe target.


## Why spanDEX

Let's clarify some key concepts in DeFi: DEX aggregators and meta aggregators.

### Why Aggregators?

Aggregators monitor liquidity across multiple DEXes. The benefits are numerous:

* **Better Prices**: By indexing liquidity from various sources, aggregators find better prices for swaps than any single DEX could offer.
* **Reduced Slippage**: Aggregators can split trades across multiple DEXes to minimize slippage, resulting in more favorable execution prices.
* **Atomic Swaps**: Aggregators can facilitate complex trades that involve multiple tokens or routes, allowing users to swap tokens that may not have direct liquidity pools.

### Why Meta Aggregators?

Meta aggregators automate the process of querying multiple DEX aggregators. The advantages include:

* **Expanded Liquidity**: Not all aggregators cover the same DEXes or tokens. By using a meta aggregator, users can access a broader range of liquidity sources.
* **Optimal Pricing**: Meta aggregators can compare quotes from different aggregators to ensure users receive the best possible price for their swaps.
* **Redundancy**: If one aggregator is down or experiencing issues, a meta aggregator can fall back to other aggregators, ensuring continuous service.

### And spanDEX?

spanDEX is an open-source meta aggregator library provides all the benefits of a meta aggregator in a developer-friendly package without any middlemen. Benefits:

* **Open Source**: spanDEX is fully open source, allowing developers to inspect, modify, and contribute to the codebase.
* **No Middlemen**: spanDEX interacts directly with DEX aggregators, eliminating a centralized meta-aggregation service that could introduce latency, fees, censorship, or single points of failure.
* **Customizable**: Developers can choose which aggregators to include, configure settings, and extend functionality to suit their specific use cases.
* **Onchain Simulation**: spanDEX supports onchain simulation of swaps, allowing developers to verify quote accuracy, gas costs, and potential reverts before executing transactions.

**The world is yours.**


## Onchain Simulation

### Overview

While fetched quotes provide a good estimate of swap costs, simulating a swap
can provide a more accurate picture of how the swap will perform when executed
onchain.

Simulation performs the swap and tracks state changes as if the transaction was executed onchain.
This allows us to:

* Confirm the accuracy of quotes by verifying that their quotes aren't stale or otherwise incorrect
* Include gas costs to compare real costs across different aggregators
* Verify swaps won't revert due to slippage, approvals, or insufficient balance

Additionally, there are edge cases such as contracts that have allowlists or other unexpected
behavior that can only be uncovered through simulation or a real transaction.

Ultimately, simulation allows us to compare quotes against their simulated onchain output, not just
quoted estimates.

### Configuration

> ⚠️ Some RPC providers do not support the underlying
> [`eth_simulateV1`](https://github.com/ethereum/execution-apis/pull/484) method required for
> simulation. Refer to your RPC provider's documentation to ensure that simulation is supported.

To enable onchain simulation, you'll need:

1. a viem `PublicClient` connected to the target chain
2. a `MetaAggregator` instance from the core spanDEX package with your desired aggregators configured


import ConfigParams from "../../snippets/params/config.mdx";

## ConfigParams

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

<ConfigParams />


import SwapParams from "../../snippets/params/swap.mdx";

## SwapParams

```ts
import type { SwapParams } from "@spandex/core";
```

<SwapParams />


## Getting Started - React

To get started we will create a shared meta aggregator instance with three providers, default settings, and support for base. Then, we will fetch the best quote for a swap and execute it.

### 1. Install

Install the core library:

:::code-group
```bash [npm]
npm i wagmi @spandex/react
```

```bash [bun]
bun i wagmi @spandex/react
```

```bash [pnpm]
pnpm i wagmi @spandex/react
```
:::

### 2. Configure

See the [configuration reference](/configuration) for all options.

```ts
import { WagmiProvider } from "wagmi";
import { wagmiConfig } from "./wagmiConfig.js";
import { SpandexProvider } from "@spandex/react";
import { fabric, zeroX } from "@spandex/core";

const config = {
  providers: [fabric({ appId: "YOUR_FABRIC_APP_ID" }), zeroX({ apiKey: "YOUR_0X_API_KEY" })],
};

export function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <SpandexProvider config={config}>
        <YourApp />
      </SpandexProvider>
    </WagmiProvider>
  );
}
```

### 3. Fetch Quotes

```ts
import { useQuotes } from "@spandex/react";

export function Quotes() {
  const { data, isLoading, error } = useQuotes({
    mode: "exactIn",
    inputToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
    outputToken: "0x4200000000000000000000000000000000000006", // WETH
    inputAmount: 1000000n, // 1 USDC
    slippageBps: 100, // 1%
  });


  if (isLoading) return <div>Fetching quotes...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <button onClick={handleFetch}>Get Quotes</button>
      {quotes?.map((quote) => (
        <div key={quote.provider}>
          {quote.provider}: {quote.outputAmount.toString()}
        </div>
      ))}
    </div>
  );
}
```


## useQuote

Fetch quotes from all configured aggregators, simulate them, and select a winner using a strategy.

### Example

```ts twoslash
import { useQuote } from "@spandex/react";

function App() {
  const { data, isLoading, error } = useQuote({
    swap: {
      inputToken: "0x4200000000000000000000000000000000000006", // WETH
      outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA", // USDbC
      mode: "exactIn",
      inputAmount: 1_000_000_000_000_000_000n, // 1 WETH
      slippageBps: 50, // Tolerance
    },
    strategy: "bestPrice",
  });
}
```

### Returns

```ts
{
  data: SuccessfulSimulatedQuote | null | undefined;
  isLoading: boolean;
  error: Error | null;
  // ...other React Query return values
}
```

### Params

#### swap

The swap parameters, with optional `chainId` and `swapperAccount` (inferred from the current
connection if omitted) and optional `recipientAccount` (defaults to `swapperAccount`).

##### swap params

* `inputToken: string` - The input token address.
* `outputToken: string` - The output token address.
* `mode: "exactIn" | "targetOut"` - The swap mode.
* `inputAmount?: bigint` - The input amount (required if mode is "exactIn").
* `outputAmount?: bigint` - The desired output amount (required if mode is "targetOut").
* `slippageBps: number` - The slippage tolerance in basis points.
* `recipientAccount?: string` - Optional output recipient address.

#### strategy

Defines how to choose the winning quote. Built-in strategies are `"fastest"`, `"bestPrice"`, `"estimatedGas"`, and `"priority"`. You can also supply a custom selection function.

#### query

Optional React Query overrides (for example `enabled`, `staleTime`, or `select`). queryKey and queryFn are managed by spanDEX and cannot be provided.


import { Callout } from 'vocs/components'

## useQuoteExecutor

<Callout type="warning">
  Coming soon
</Callout>


## useQuotes

Fetch quotes from all configured aggregators and simulate each quote.

### Example

```ts twoslash
import { useQuotes } from "@spandex/react";

function App() {
  const { data, isLoading, error } = useQuotes({
    swap: {
      inputToken: "0x4200000000000000000000000000000000000006", // WETH
      outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA", // USDbC
      mode: "exactIn",
      inputAmount: 1_000_000_000_000_000_000n, // 1 WETH
      slippageBps: 50, // Tolerance
    }
  });
}
```

### Returns

```ts
{
  data: SimulatedQuote[] | undefined;
  isLoading: boolean;
  error: Error | null;
  // ...other React Query return values
}
```

### Params

#### swap

The swap parameters, with optional `chainId` and `swapperAccount` (inferred from the current
connection if omitted) and optional `recipientAccount` (defaults to `swapperAccount`).

##### swap params

* `inputToken: string` - The input token address.
* `outputToken: string` - The output token address.
* `mode: "exactIn" | "targetOut"` - The swap mode.
* `inputAmount?: bigint` - The input amount (required if mode is "exactIn").
* `outputAmount?: bigint` - The desired output amount (required if mode is "targetOut").
* `slippageBps: number` - The slippage tolerance in basis points.
* `recipientAccount?: string` - Optional output recipient address.


import { Button } from 'vocs/components'
import { Callout } from 'vocs/components'

## 0x

<div className="flex flex-row gap-4">
  <Button href="https://0x.org">Homepage</Button>
  <Button href="https://0x.org/docs/0x-swap-api/introduction">Docs</Button>
</div>

### Configuration

<Callout type="warning">
  0x requires an API key for access. You can obtain one by [signing up](https://dashboard.0x.org/create-account).
</Callout>

Use the `zeroX` factory since JavaScript identifiers cannot start with a number.

```ts twoslash
import { createConfig, zeroX } from "@spandex/core";

export const config = createConfig({
  providers: [
    zeroX({
      // required!
      apiKey: "YOUR_0X_API_KEY",
      // If you have negotiated surplus sharing with 0x, override negotiatedOptions
      // negotiatedFeatures: ["integratorSurplus"],
    }),
    // ...
  ],
});
```


import { Button } from 'vocs/components'
import { Callout } from 'vocs/components'

## Fabric

<div className="flex flex-row gap-4">
  <Button href="https://spandex.sh">Homepage</Button>
  <Button href="https://spandex.sh/getting-started">Docs</Button>
</div>

### Configuration

```ts twoslash
import { createConfig, fabric } from "@spandex/core";

export const config = createConfig({
  providers: [
    fabric({
      appId: "YOUR_FABRIC_APP_ID",
      // Optional, use if you have negotiated service
      apiKey: "YOUR_FABRIC_API_KEY",
      // Optional, only set if you have a private Fabric deployment
      url: undefined,
    }),
    // ...
  ],
});
```


import { Button } from 'vocs/components'
import { Callout } from 'vocs/components'

## KyberSwap

<div className="flex flex-row gap-4">
  <Button href="https://kyber.network/">Homepage</Button>
  <Button href="https://docs.kyberswap.com/kyberswap-solutions/kyberswap-aggregator">Docs</Button>
</div>

### Configuration

```ts twoslash
import { createConfig, kyberswap } from "@spandex/core";

export const config = createConfig({
  providers: [
    kyberswap({
      // Required, you choose the value
      clientId: "myawesomeapp",
    }),
    // ...
  ],
});
```


import { Button } from 'vocs/components'

## LiFi

<div className="flex flex-row gap-4">
  <Button href="https://li.fi">Homepage</Button>
  <Button href="https://docs.li.fi/api-reference/get-a-quote-for-a-token-transfer">Docs</Button>
</div>

### Configuration

```ts twoslash
import { createConfig, lifi } from "@spandex/core";

export const config = createConfig({
  providers: [
    lifi({
      apiKey: undefined, // Optional. Use it if you got it
    }),
    // ...
  ],
});
```


import { Button } from 'vocs/components'
import { Callout } from 'vocs/components'

## Odos

<div className="flex flex-row gap-4">
  <Button href="https://www.odos.xyz/">Homepage</Button>
  <Button href="https://docs.odos.xyz/api/sor/quoter">Docs</Button>
</div>

### Configuration

```ts twoslash
import { createConfig, odos } from "@spandex/core";

export const config = createConfig({
  providers: [
    odos({
      // Optional. Use for attribution
      referralCode: undefined,
      // Optional. Use it if you got it
      apiKey: undefined,
      // Optional. Enable fees and surplus if negotiated with Odos.
      // negotiatedFeatures: ["integratorSurplus", "integratorFees"],
    }),
    // ...
  ],
});
```


import { Button } from 'vocs/components'

## Relay

<div className="flex flex-row gap-4">
  <Button href="https://relay.link">Homepage</Button>
  <Button href="https://docs.relay.link/references/api/get-quote">Docs</Button>
</div>

### Configuration

```ts twoslash
import { createConfig, relay } from "@spandex/core";

export const config = createConfig({
  providers: [
    relay({
      // Optional, override the API base URL
      url: undefined,
    }),
    // ...
  ],
});
```


import { Button } from 'vocs/components'
import { Callout } from 'vocs/components'

## Velora

<div className="flex flex-row gap-4">
  <Button href="https://velora.xyz">Homepage</Button>
  <Button href="https://developers.velora.xyz/api/velora-api/velora-market-api/get-rate-for-a-token-pair-1">Docs</Button>
</div>

### Configuration

<Callout type="info">
  Velora supports both `exactIn` and `targetOut` quotes, plus integrator fee and surplus options.
</Callout>

```ts twoslash
import { createConfig, velora } from "@spandex/core";

export const config = createConfig({
  providers: [
    velora({
      // Optional, override the API base URL
      baseUrl: undefined,
      // Optional, partner slug for attribution
      partner: undefined,
      // Optional, forwarded as `isDirectFeeTransfer` when fee/surplus capture is enabled
      // Default: true
      isDirectFeeTransfer: true,
    }),
    // ...
  ],
});
```

When using global aggregation options:

* `integratorSwapFeeBps` maps to Velora's `partnerFeeBps`
* `integratorSurplusBps` enables Velora's `takeSurplus`
* Velora uses a single partner recipient (`partnerAddress`) for both flows. If both fee and surplus
  are requested with different addresses, spanDEX prioritizes the fee recipient.
* `isDirectFeeTransfer` is configured on `velora({...})` setup and is only sent when
  `partnerAddress` is present.


## Getting Started - Core

To get started we will create a shared meta aggregator instance with three providers, default settings, and support for base. Then, we will fetch the best quote for a swap and execute it.

### 1. Install

Install the core library:

:::code-group
```bash [npm]
npm i viem @spandex/core
```

```bash [pnpm]
pnpm i viem @spandex/core
```

```bash [bun]
bun i viem @spandex/core
```
:::

### 2. Configure

See the [configuration reference](/configuration) for all options.

```ts filename="config.ts" twoslash
import { createConfig, fabric, kyberswap, odos } from "@spandex/core";
import { createPublicClient, http, type PublicClient } from "viem";
import { base } from "viem/chains";

// Create a base client for quote simulation
const baseClient = createPublicClient({
  chain: base,
  transport: http("https://base.drpc.org"),
});

// The aggregator instance can be shared across your application
export const config = createConfig({
  providers: [fabric({ appId: "test" }), odos({}), kyberswap({ clientId: "test" })],
  clients: [baseClient] as PublicClient[],
});
```

### 3. Fetch Quotes and Execute

```ts filename="quote.ts" twoslash
import { config } from "./config.js";
import { createWalletClient, http } from "viem";
import { executeQuote, getQuote } from "@spandex/core";
import { base } from "viem/chains";

const swapParams = {
  chainId: 8453,
  inputToken: "0x4200000000000000000000000000000000000006", // WETH
  outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA", // USDbC
  mode: "exactIn",
  inputAmount: 1_000_000_000_000_000_000n, // 1 WETH
  slippageBps: 50, // Tolerance
  swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
};

const quote = await getQuote({
  config,
  swap: swapParams,
  strategy: "bestPrice",
});

if (!quote) {
  throw new Error("No providers responded in time");
}

const walletClient = createWalletClient({
  account: "0xdead00000000000000000000000000000000beef",
  chain: base,
  transport: http(),
});

const { transactionHash } = await executeQuote({
  config,
  swap: swapParams,
  quote,
  walletClient,
});

console.log(`Swapped via ${quote.provider} @ ${transactionHash}`);

```


import ConfigParams from '../../../snippets/params/config.mdx'

## createConfig

Create a configuration object to customize providers and options for all aggregation functions.

```ts
import { createConfig, fabric, kyberswap, odos, zeroX } from "@spandex/core";

export const config = createConfig({
  providers: [
    zeroX({ apiKey: "YOUR_0X_API_KEY" }),
    fabric({ appId: "YOUR_FABRIC_APP_ID" }),
    odos({}),
    kyberswap({ clientId: "YOUR_KYBER_CLIENT_ID" }),
  ],
  options: {
    deadlineMs: 10000,
    numRetries: 2,
    initialRetryDelayMs: 200,
    integratorFeeAddress: "0xFee000",
    integratorSwapFeeBps: 25,
  },
  clients: [
    baseClient,
    mainnetClient
  ] as PublicClient[],
});
```

### Proxy configuration

Use a proxy when fetching quotes from a server (for example, to avoid browser CORS issues).
For a full architecture walkthrough, see [Configuration > Proxy Mode](/configuration/proxy).

```ts
import { createConfig, proxy } from "@spandex/core";
import { createPublicClient, http, type PublicClient } from "viem";
import { base } from "viem/chains";

const client = createPublicClient({
  chain: base,
  transport: http("https://base.drpc.org"),
});

export const config = createConfig({
  proxy: proxy({ pathOrUrl: "https://example.com/api/quotes" }),
  clients: [client] as PublicClient[],
});
```

<ConfigParams />

### Returns

`Config`

Aggregator configuration object to be passed to aggregation functions.


## decodeQuoteStream

Decode a quote stream produced by `newQuoteStream` into an array of quote promises.

### Example

```ts
import { decodeQuoteStream } from "@spandex/core";

const response = await fetch("/api/quotes");
if (!response.body) {
  throw new Error("No response body");
}

const quotePromises = await decodeQuoteStream(response.body);
const quotes = await Promise.all(quotePromises);

console.log(quotes.length);
```

### Params

#### stream

`ReadableStream<Uint8Array>`

Stream of serialized quotes produced by `newQuoteStream`.

### Returns

`Promise<Array<Promise<Quote>>>`

Promises that resolve to quotes as they stream in.


## executeQuote

Execute a simulated quote onchain using a wallet client. Handles approval requirements and supports EIP-5792 batch calls when available.

### Example

:::code-group
```ts [executeQuote] twoslash
import { executeQuote, getQuote } from "@spandex/core";
import { config, publicClient, walletClient } from "./config.js";

const swap = {
  chainId: 8453,
  inputToken: "0x4200000000000000000000000000000000000006", // WETH
  outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA", // USDbC
  mode: "exactIn",
  inputAmount: 1_000_000_000_000_000_000n, // 1 WETH
  slippageBps: 50, // Tolerance
  swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
};

const quote = await getQuote({
  config,
  swap,
  strategy: "bestPrice",
});

if (!quote) {
  throw new Error("No providers returned a successful quote");
}

const result = await executeQuote({
  config,
  swap,
  quote,
  walletClient,
  publicClient,
});

console.log(result.transactionHash);
```

```ts [config] filename="config.ts" twoslash
import { createConfig, fabric, odos } from "@spandex/core";
import { createPublicClient, createWalletClient, http, type PublicClient } from "viem";
import { base } from "viem/chains";

const publicClient = createPublicClient({
  chain: base,
  transport: http("https://base.drpc.org"),
});

const walletClient = createWalletClient({
  account: "0xdead00000000000000000000000000000000beef",
  chain: base,
  transport: http(),
});

export { publicClient, walletClient };

export const config = createConfig({
  providers: [fabric({ appId: "your app id" }), odos({})],
  clients: [publicClient] as PublicClient[],
});
```
:::

### Params

#### swap

`SwapParams`

Swap parameters used to build the approval + swap transactions.

#### quote

`SimulatedQuote`

The simulated quote to be executed. This should be obtained via [`getQuotes`](./getQuotes.mdx) or [`getQuote`](./getQuote.mdx). If the quote is not successful, `executeQuote` throws an `ExecutionError`.

#### config

`Config`

Aggregator configuration object created via [`createConfig`](./createConfig.mdx). Used to resolve clients and options.

#### walletClient

`WalletClient`

A Viem wallet client configured with the swapper's account and chain. This client is used to sign and send the transaction.

#### publicClient

`PublicClient | undefined`

Optional public client for onchain reads (allowance checks, gas estimation, and receipt polling). If omitted, the configured client for the swap chain is used.

### Returns

`Promise<ExecutedQuoteReturnType>`

A promise for an execution result containing the transaction hash.


import { Callout } from 'vocs/components'

## getPricing

<Callout type="warning">
  **Experimental:** This utility is still considered experimental and may change.
</Callout>

Extract pricing metadata from list of quotes to produce usd price estimates for input and output tokens.

### Example

```ts
import { getPricing, getRawQuotes } from "@spandex/core";
import { config } from "./config.js";

const quotes = await getRawQuotes({
  config,
  swap: {
    chainId: 8453,
    inputToken: "0x4200000000000000000000000000000000000006",
    outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA",
    mode: "exactIn",
    inputAmount: 1_000_000_000_000_000_000n,
    slippageBps: 50,
    swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
  },
});

const pricing = getPricing(quotes);

console.log(pricing.sources);
console.log(pricing.inputToken?.usdPrice, pricing.outputToken?.usdPrice);
```

### Params

#### quotes

`Quote[]`

Quotes to summarize. Failed quotes and quotes without pricing metadata are ignored.

### Returns

`PricingSummary`

Aggregated pricing summary including averaged USD prices and contributing providers.


## getQuote

Fetch quotes, simulate them, and return a single winning quote based on a selection strategy.

### Example

:::code-group
```ts [getQuote] twoslash
import { getQuote } from "@spandex/core";
import { config } from "./config.js";

const quote = await getQuote({
  config,
  swap: {
    chainId: 8453,
    inputToken: "0x4200000000000000000000000000000000000006", // WETH
    outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA", // USDbC
    mode: "exactIn",
    inputAmount: 1_000_000_000_000_000_000n, // 1 WETH
    slippageBps: 50,
    swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
  },
  strategy: "bestPrice",
});

if (!quote) {
  throw new Error("No providers returned a successful quote");
}

console.log(quote.provider, quote.simulation.outputAmount);
```

```ts [config] filename="config.ts" twoslash
import { createConfig, fabric, odos } from "@spandex/core";
import { createPublicClient, http, type PublicClient } from "viem";
import { base } from "viem/chains";

const client = createPublicClient({
  chain: base,
  transport: http("https://base.drpc.org"),
});

export const config = createConfig({
  providers: [fabric({ appId: "your app id" }), odos({})],
  clients: [client] as PublicClient[],
});
```
:::

### Params

#### config

`Config`

Aggregator configuration object created via [`createConfig`](./createConfig.mdx).

#### swap

`SwapParams`

Parameters defining the swap operation. See [SwapParams reference](/reference/SwapParams.mdx) for details.

#### strategy

`QuoteSelectionStrategy`

Selection strategy used to pick a winning quote. Built-in strategy names:

| Strategy       | Waits for All | Selection Criteria        | Best For             |
| -------------- | ------------- | ------------------------- | -------------------- |
| `bestPrice`    | ✓             | Highest simulated output  | Price optimization   |
| `estimatedGas` | ✓             | Lowest simulated gas used | Gas efficiency       |
| `fastest`      | ✗             | First success             | Lowest latency       |
| `priority`     | ✗             | Provider order            | Failover chains      |
| Custom         | Depends       | Your logic                | Special requirements |

Custom function signature:

```ts
type QuoteSelectionFn = (
  quotes: Array<Promise<SimulatedQuote>>
) => Promise<SuccessfulSimulatedQuote | null>
```

#### client

`PublicClient | undefined`

Optional custom PublicClient to use for onchain simulations. If not provided, the configured clients in the `config` will be used.

#### simulate

`typeof simulateQuote | undefined`

Optional override for the simulation function used on each quote.

### Returns

`Promise<SuccessfulSimulatedQuote | null>`

Winning simulated quote, or `null` if no provider succeeds.


## getQuotes

Fetches quotes from all configured providers and simulates the quote transactions to validate the swap operation and the final token output amount.

### Example

:::code-group
```ts [getQuotes] twoslash
import { getQuotes } from "@spandex/core";
import { config } from "./config.js";

const quotes = await getQuotes({
  config,
  swap: {
    chainId: 8453,
    inputToken: "0x4200000000000000000000000000000000000006", // WETH
    outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA", // USDbC
    mode: "exactIn",
    inputAmount: 1_000_000_000_000_000_000n, // 1 WETH
    slippageBps: 50, // Tolerance
    swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
  }
});

for (const quote of quotes) {
  if (quote.success && quote.simulation.success) {
    console.log(
      `${quote.provider} yields ${quote.simulation.outputAmount}`
    );
  }
}

/// @log: fabric yields 995000000n
/// @log: odos yields 994500000n
```

```ts [config] filename="config.ts" twoslash
import { createConfig, fabric, odos } from "@spandex/core";
import { createPublicClient, http, type PublicClient } from "viem";
import { base } from "viem/chains";

const client = createPublicClient({
  chain: base,
  transport: http("https://base.drpc.org"),
});

export const config = createConfig({
  providers: [fabric({ appId: "your app id" }), odos({})],
  clients: [client] as PublicClient[],
});
```
:::

### Params

#### config

`Config`

Aggregator configuration object created via [`createConfig`](./createConfig.mdx).

#### swap

`SwapParams`

Parameters defining the swap operation. See [SwapParams reference](/reference/SwapParams.mdx) for details.

#### client

`PublicClient | undefined`

Optional custom PublicClient to use for onchain simulations. If not provided, the configured clients in the `config` will be used.

### Returns

`Promise<SimulatedQuote[]>`

List of simulated quotes from all providers. Each quote includes the provider name, raw quote data, and the simulated output amount after onchain validation. Quotes that fail simulation are denoted by `success=false` and include an error message. Simulation may also fail, due to a revert, etc. See `SimulatedQuote` for details.


## getRawQuotes

Fetches quotes from all configured providers. This function does not perform any onchain simulation or validation. It is useful for scenarios where you plan to handle validation separately. Always simulate!

### Example

:::code-group
```ts [getRawQuotes] twoslash
import { getRawQuotes } from "@spandex/core";
import { config } from "./config.js";

const quotes = await getRawQuotes({
  config,
  swap: {
    chainId: 8453,
    inputToken: "0x4200000000000000000000000000000000000006", // WETH
    outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA", // USDbC
    mode: "exactIn",
    inputAmount: 1_000_000_000_000_000_000n, // 1 WETH
    slippageBps: 50, // Tolerance
    swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
  }
});
```

```ts [config] filename="config.ts" twoslash
import { createConfig, fabric, odos } from "@spandex/core";

export const config = createConfig({
  providers: [fabric({ appId: "your app id" }), odos({})],
});
```
:::

### Params

#### config

`Config`

Aggregator configuration object created via [`createConfig`](./createConfig.mdx).

#### swap

`SwapParams`

Parameters defining the swap operation. See [SwapParams reference](/reference/SwapParams.mdx) for details.

### Returns

`Promise<Quote[]>`

List of quotes from all providers. Quotes that resulted in failure are denoted by `success=false` and include an error message.


import { Callout } from 'vocs/components'

## netOutputs

<Callout type="warning">
  **Experimental:** This utility is still considered experimental and may be inaccurate for complex swaps.
</Callout>

Computes net input/output token allocations per recipient based on Transfer logs. This is useful for
spotting fee extractors (aggregator, app, relayer, etc.) by showing which accounts received how many
tokens during a swap.

Logs can come from a `TransactionReceipt` or `SuccessSimulationResult`.

### Example

```ts twoslash
import { netOutputs, type SwapParams } from "@spandex/core";
import type { TransactionReceipt } from "viem";

const swap: SwapParams = {} as SwapParams; // ...
const receipt: TransactionReceipt = {} as TransactionReceipt; // ...

const allocations = netOutputs({
  swap,
  logs: receipt.logs,
});

for (const [account, amount] of allocations.outputToken) {
  console.log("output recipient", account, amount.toString());
}
```

### Params

#### swap

`SwapParams`

Swap parameters that identify the input/output tokens and swapper. This should match the swap that
was used to build a quote, which was executed to produce logs. If `recipientAccount` is set on the
swap, output attribution is evaluated against that recipient.

#### logs

`Log[]`

Event logs from a transaction receipt or simulation output.

### Returns

`Allocations`

```ts
type Allocations = {
  inputToken: Map<Address, bigint>;
  outputToken: Map<Address, bigint>;
};
```

Each map is keyed by recipient address and contains the net amount of that token received by that
address (base units).


## newQuoteStream

Create a `ReadableStream` that emits serialized quotes as each promise resolves. This is useful for server-to-client streaming of quotes as they are fetched.

### Example

```ts
import { newQuoteStream, prepareQuotes } from "@spandex/core";
import { config, swap } from "./config.js";

export async function GET() {
  const promises = await prepareQuotes({
    config,
    swap,
    mapFn: async (quote) => quote,
  });

  return new Response(newQuoteStream(promises), {
    headers: {
      "Content-Type": "application/octet-stream",
    },
  });
}
```

### Params

#### promises

`Array<Promise<Quote>>`

Quote promises to resolve and stream.

### Returns

`ReadableStream<Uint8Array>`

Stream of serialized quote frames.


## prepareQuotes

Prepare a list of swap quote promise chains for quote fetching and secondary actions such as simulation. This is useful when custom behavior is required, such as racing quotes+simulation for multiple providers.

### Example

:::code-group
```ts [getQuotes]
import { prepareQuotes, type Quote } from "@spandex/core";
import { config } from "./config.ts";

// Identity fn
async function mapFn(quote: Quote): Promise<Quote> {
  return quote;
}

const promises = await prepareQuotes({
  config,
  swap: {
    chainId: 8453,
    inputToken: "0x4200000000000000000000000000000000000006", // WETH
    outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA", // USDbC
    mode: "exactIn",
    inputAmount: 1_000_000_000_000_000_000n, // 1 WETH
    slippageBps: 50, // Tolerance
    swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
  },
  mapFn,
});
```

```ts [config.ts] filename="config.ts" twoslash
import { createConfig, fabric, odos } from "@spandex/core";
import { createPublicClient, http, type PublicClient } from "viem";
import { base } from "viem/chains";

const client = createPublicClient({
  chain: base,
  transport: http("https://base.drpc.org"),
});

export const config = createConfig({
  providers: [fabric({ appId: "your app id" }), odos({})],
  clients: [client] as PublicClient[],
});
```
:::

### Params

#### config

`Config`

Aggregator configuration object created via [`createConfig`](./createConfig.mdx).

#### swap

`SwapParams`

Parameters defining the swap operation. See [SwapParams reference](/reference/SwapParams.mdx) for details.

#### mapFn

`(quote: Quote) => Promise<T>`

Function that maps each fetched quote to a promise of type `T`. This allows for custom processing of each quote, such as simulation or other enrichment. Identity function is also valid.

### Returns

`Array<Promise<T>>`

List of promises, each resolving to type `T` as defined by the `mapFn`.


## selectQuote

Pick the best simulated quote from a set of in-flight quote+simulation promises. This is useful when you want to stream quotes and simulations concurrently and only commit to the best result once enough data is available.

### Example

:::code-group
```ts [selectQuote]
import { prepareQuotes, selectQuote, simulateQuote } from "@spandex/core";
import { config, client, swap } from "./config.ts";

const quotes = await prepareQuotes({
  config,
  swap,
  mapFn: (quote) => simulateQuote({ quote, swap, client }),
});

const quote = await selectQuote({
  quotes,
  strategy: "bestPrice",
});
```
:::

### Params

#### quotes

`Array<Promise<SimulatedQuote>>`

A list of promises each resolving to a simulated quote. These can be created via the [`prepareQuotes`](./prepareQuotes.mdx) function.

#### strategy

`QuoteSelectionStrategy`

Strategy used to pick a winning quote.

| Strategy       | Waits for All | Selection Criteria        | Best For             |
| -------------- | ------------- | ------------------------- | -------------------- |
| `bestPrice`    | ✓             | Highest simulated output  | Price optimization   |
| `estimatedGas` | ✓             | Lowest simulated gas used | Gas efficiency       |
| `fastest`      | ✗             | First success             | Speed/latency        |
| `priority`     | ✗             | Provider order            | Fallback chains      |
| Custom         | Depends       | Your logic                | Special requirements |

**Custom**

```ts
type QuoteSelectionFn = (
  quotes: Array<Promise<SimulatedQuote>>
) => Promise<SuccessfulSimulatedQuote | null>
```

### Returns

`Promise<SuccessfulSimulatedQuote | null>`

A promise for a single simulated quote that offers the best outcome depending on the strategy.


## simulateQuote

Simulate a single quote onchain and decorate it with simulation results.

### Example

```ts
import { getRawQuotes, simulateQuote } from "@spandex/core";
import { config, client } from "./config.js";

const swap = {
  chainId: 8453,
  inputToken: "0x4200000000000000000000000000000000000006",
  outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA",
  mode: "exactIn",
  inputAmount: 1_000_000_000_000_000_000n,
  slippageBps: 50,
  swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
};

const quotes = await getRawQuotes({
  config,
  swap,
});

const first = quotes.find((quote) => quote.success);
if (!first) {
  throw new Error("No successful quotes to simulate");
}

const simulated = await simulateQuote({
  quote: first,
  swap,
  client,
});

if (simulated.success && simulated.simulation.success) {
  console.log(simulated.simulation.outputAmount);
}
```

### Params

#### client

`PublicClient`

Client used to perform the simulation.

#### swap

`SwapParams`

Swap parameters associated with the quote. See [SwapParams reference](/reference/SwapParams.mdx) for details.

#### quote

`Quote`

Quote to simulate.

### Returns

`Promise<SimulatedQuote>`

The quote decorated with simulation results. Simulation failures are returned in the `simulation` field (for example `SimulationRevertError`).


## simulateQuotes

Simulate a batch of quotes given shared swap parameters and a client.

### Example

```ts
import { getRawQuotes, simulateQuotes } from "@spandex/core";
import { config, client } from "./config.js";

const swap = {
  chainId: 8453,
  inputToken: "0x4200000000000000000000000000000000000006",
  outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA",
  mode: "exactIn",
  inputAmount: 1_000_000_000_000_000_000n,
  slippageBps: 50,
  swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
};

const quotes = await getRawQuotes({ config, swap });

const simulated = await simulateQuotes({
  client,
  swap,
  quotes,
});

for (const quote of simulated) {
  if (quote.success && quote.simulation.success) {
    console.log(quote.provider, quote.simulation.outputAmount);
  }
}
```

### Params

#### client

`PublicClient`

Client used to perform the simulations.

#### swap

`SwapParams`

Swap parameters shared across all quotes. See [SwapParams reference](/reference/SwapParams.mdx) for details.

#### quotes

`Quote[]`

Quotes to simulate.

### Returns

`Promise<SimulatedQuote[]>`

Quotes decorated with simulation results. Simulation failures are represented in the `simulation` field.


## sortQuotesByPerformance

Sort successful simulated quotes by a selected performance metric.

### Example

```ts
import {
  getRawQuotes,
  simulateQuotes,
  sortQuotesByPerformance,
  type SuccessfulSimulatedQuote,
} from "@spandex/core";
import { config, client } from "./config.js";

const swap = {
  chainId: 8453,
  inputToken: "0x4200000000000000000000000000000000000006",
  outputToken: "0xd9AAEC86B65D86f6A7B5B1b0c42FFA531710b6CA",
  mode: "exactIn",
  inputAmount: 1_000_000_000_000_000_000n,
  slippageBps: 50,
  swapperAccount: "0x1234567890abcdef1234567890abcdef12345678",
};

const quotes = await getRawQuotes({ config, swap });
const simulated = await simulateQuotes({ quotes, swap, client });
const successful = simulated.filter(
  (quote) => quote.success && quote.simulation.success,
) as SuccessfulSimulatedQuote[];

const sorted = sortQuotesByPerformance({
  quotes: successful,
  metric: "accuracy",
  ascending: true,
});

console.log(sorted[0]?.performance);
```

### Params

#### quotes

`SuccessfulSimulatedQuote[]`

Quotes to sort. Only successful simulated quotes include performance metrics.

#### metric

`keyof QuotePerformance`

Metric to sort by. Supported metrics include `latency`, `gasUsed`, `outputAmount`, `priceDelta`, and `accuracy`.

#### ascending

`boolean | undefined`

Sort order (default: `true`). When `false`, the list is sorted descending.

### Returns

`SuccessfulSimulatedQuote[]`

New array of quotes sorted by the selected performance metric.


import { Callout } from "vocs/components";

## Fees

There are several fee layers to consider in spanDEX, even though spanDEX itself does not impose fees:

* **Provider fees**: costs imposed by the upstream provider and included in the quote.
* **Integrator fee capture**: fee/surplus you choose to request because your product is
  sourcing order flow. This is activated by the provider on your behalf and included in the quote.
* **LP fees**: fees paid to market makers (AMM, RFQ, etc) and included in the quote.
* **Network fees**: gas costs, which scale with route complexity. They are not included in the
  quote output amount, but are estimated during simulation.

### Provider Fees

These values represent default settings for each provider (new account or anonymous access) and are
subject to negotiation.

| Provider  | Swap Fee              | Surplus       | More                                                                                |
| --------- | --------------------- | ------------- | ----------------------------------------------------------------------------------- |
| Fabric    | 0-0.1%                | 0-100%        | -                                                                                   |
| 0x        | 0.15%                 | 100% (1% Cap) | [Details](https://0x.org/pricing)                                                   |
| KyberSwap | 0%                    | 100%          | [Details](https://docs.kyberswap.com/kyberswap-solutions/fee-schedule)              |
| Odos      | 0.03%                 | 100%          | [Details](https://docs.odos.xyz/build/api_pricing)                                  |
| LI.FI     | 0.25%                 | 100%          | [Details](https://docs.li.fi/faqs/fees-monetization)                                |
| Relay     | 25% of Integrator Fee | 100%          | [Details](https://docs.relay.link/references/api/api_core_concepts/fees)            |
| Velora    | 15% of Integrator Fee | 100% (1% Cap) | [Details](https://docs.velora.xyz/intro-to-velora/velora-overview/protocol-revenue) |

Additionally, each swap has network fees, which are not included in `outputTokens`. Gas estimates
can still be factored in when selecting quotes.

### Integrator Fee Capture (Optional)

spanDEX supports two integrator fee-capture controls for applications that source order flow from end users:

* Fixed swap fee (`integratorSwapFeeBps`)
* Surplus share (`integratorSurplusBps`)

These requests are passed optimistically to providers. Each quote reports `activatedFeatures` so
selection can prefer quotes that actually activated requested features.

<Callout type="info">
  If you set `integratorSwapFeeBps` or `integratorSurplusBps`, you must also set
  `integratorFeeAddress`.
</Callout>

### Fixed Rate Swap Fees

Use a fixed bps fee when you want predictable revenue on eligible swaps.

```ts
import { createConfig, fabric, relay } from "@spandex/core";

const config = createConfig({
  providers: [fabric({ appId: "YOUR_FABRIC_APP_ID" }), relay({})],
  options: {
    integratorFeeAddress: "0xFee00000000000000000000000000000000000fee",
    integratorSwapFeeBps: 25, // 0.25%
  },
});
```

### Surplus Capture

Surplus can be requested with `integratorSurplusBps` for providers that support it. If
`integratorSurplusAddress` is omitted, the fallback is typically `integratorFeeAddress`.

<Callout type="info">
  This is not widely supported via API controls, but may be negotiated with providers.
</Callout>

```ts
import { createConfig, fabric, velora } from "@spandex/core";

const config = createConfig({
  providers: [fabric({ appId: "YOUR_FABRIC_APP_ID" }), velora({})],
  options: {
    integratorFeeAddress: "0xFee00000000000000000000000000000000000fee",
    integratorSwapFeeBps: 20,
    integratorSurplusBps: 1000, // 10%
  },
});
```

### Integrator Fee Support by Provider

This table summarizes what a developer can control in the API today. Commercial enablement can
still depend on provider plans/terms.

| Provider  | Swap Fee Control | Surplus Control | Negotiability |
| --------- | ---------------- | --------------- | ------------- |
| Fabric    | ✓                | ✓               | ✓             |
| 0x        | ✓                | x               | ✓             |
| KyberSwap | ✓                | x               | ✓             |
| Odos      | x                | x               | ✓             |
| LI.FI     | ✓                | x               | ✓             |
| Relay     | ✓                | x               | ✓             |
| Velora    | ✓                | ✓               | ✓             |

Swap fee requests are configured with `integratorSwapFeeBps`, and surplus requests are configured
with `integratorSurplusBps`.

### How Selection Uses Integrator Fee Requests

* Requested fees are optimistic; providers without support can still return valid quotes.
* `activatedFeatures` indicates which requested features were actually active.
* Selection strategies (other than `fastest`) prioritize higher feature activation count before
  the secondary criterion (best price, lowest gas, etc).

<Callout type="info">
  If you have negotiated features like surplus for a given provider, you can activate that feature
  for any provider using the `negotiatedFeatures` option.
</Callout>


## Configuration

Use configuration to tune how your meta-aggregator behaves in production: which providers are active,
how quote economics and optional integrator fee capture work, and what latency/retry behavior you
want globally.

### What You Can Configure

#### Provider Mix

Choose one or more providers and define per-provider settings (keys, referral IDs, timeouts, negotiated
features, and more).

* [Provider strategy and comparison](/configuration/providers)
* [Provider-specific setup docs](/providers/fabric)

#### Fees and Integrator Capture

Understand provider-imposed quote fees and configure optional integrator fee capture (swap fee and
surplus) for supported providers.

* [Fees and integrator fee capture](/configuration/fees)

#### Runtime Controls

Tune global aggregation behavior in `options`:

* `deadlineMs`
* `numRetries`
* `initialRetryDelayMs`

#### Execution Environment

Set clients, logging, or proxy mode depending on your app architecture:

* `clients` for simulation/validation support
* `logging` for info/debug/trace
* `proxy` when quote fetching runs server-side
* [Proxy mode architecture and streaming](/configuration/proxy)

### API Reference

* [ConfigParams reference](/reference/ConfigParams)
* [createConfig function](/core/functions/createConfig)


import { Callout } from "vocs/components";
import { Logo0x } from "../../components/logo/0x";
import { FabricLogo } from "../../components/logo/fabric";
import { KyberSwapLogo } from "../../components/logo/kyberswap";
import { LifiLogo } from "../../components/logo/lifi";
import { OdosLogo } from "../../components/logo/odos";
import { RelayLogo } from "../../components/logo/relay";
import { VeloraLogo } from "../../components/logo/velora";

## Providers

Your provider set is the most important configuration decision in spanDEX. Think in terms of a
portfolio: you want enough provider diversity to improve route quality, resilience, and throughput
under real load. No single aggregator wins every trade or delivers 100% uptime.

### Supported Providers

<div className="provider-grid">
  <a className="provider-card" href="/providers/fabric">
    <span className="provider-card__logo">
      <FabricLogo />
    </span>

    <span className="provider-card__name">Fabric</span>
  </a>

  <a className="provider-card" href="/providers/0x">
    <span className="provider-card__logo">
      <Logo0x />
    </span>

    <span className="provider-card__name">0x</span>
  </a>

  <a className="provider-card" href="/providers/kyberswap">
    <span className="provider-card__logo">
      <KyberSwapLogo />
    </span>

    <span className="provider-card__name">KyberSwap</span>
  </a>

  <a className="provider-card" href="/providers/odos">
    <span className="provider-card__logo">
      <OdosLogo />
    </span>

    <span className="provider-card__name">Odos</span>
  </a>

  <a className="provider-card" href="/providers/lifi">
    <span className="provider-card__logo">
      <LifiLogo />
    </span>

    <span className="provider-card__name">LI.FI</span>
  </a>

  <a className="provider-card" href="/providers/relay">
    <span className="provider-card__logo">
      <RelayLogo />
    </span>

    <span className="provider-card__name">Relay</span>
  </a>

  <a className="provider-card" href="/providers/velora">
    <span className="provider-card__logo">
      <VeloraLogo />
    </span>

    <span className="provider-card__name">Velora</span>
  </a>
</div>

<Callout type="info">
  If you would like to include your aggregator in spanDEX, [submit a PR](https://github.com/withfabricxyz/spandex/blob/main/CONTRIBUTING.md).
</Callout>

### Why Use Multiple Providers

* Better fill quality: different routers are stronger on different chains, pools, and token pairs.
* Better uptime: provider outages, brownouts, or temporary API issues do not fully block quoting.
* Better fee opportunities: providers differ in integrator fee/surplus support and commercial terms.
* Better latency under load: requests can race in parallel and still respect a global deadline.

### What Differs Across Providers

When choosing providers, compare these dimensions:

* Functionality (`exactIn` only vs `exactIn` + `targetOut`)
* Provider-imposed fees (surplus taking or swap fees)
* Integrator fee and surplus support ([see fees page](/configuration/fees))
* Base API requirements (keys, partner IDs, referral codes)
* Rate limits and plan capacity
* Chain and token coverage

### Production Planning

In production with real volume, configure multiple providers and choose provider plans that match
your expected quote throughput. A single free-tier or low-rate plan is usually a bottleneck.

### Multi-Region and Edge Deployment

If you run spanDEX as an edge service, you can use dynamic provider configuration by
region to keep quote latency lower and improve reliability. If you have any regional latency
data for providers, please contribute.

```ts
import { createConfig, fabric, relay, velora } from "@spandex/core";

export function configForRegion(region: string) {
  if (region.startsWith("eu")) {
    return createConfig({
      providers: [fabric({ appId: "..." }), relay({})],
    });
  }

  return createConfig({
    providers: [fabric({ appId: "..." }), velora({})],
  });
}
```


import { Callout } from "vocs/components";

## Proxy Mode

Use proxy mode when your meta-aggregation layer runs as a service and clients fetch quotes from
that service, instead of calling provider APIs directly from the client.

### When to Use It

* You want provider API keys and provider-selection logic on the server.
* You want a single policy point for rate limits, allowlists, and request validation.
* You run multi-region services and want region-aware provider configuration.

### Client Configuration

```ts
import { proxy } from "@spandex/core";
import { SpandexProvider } from "@spandex/react";

<SpandexProvider
  config={{
    proxy: proxy({ pathOrUrl: "/api/quotes" }),
  }}
>
  {children}
</SpandexProvider>;
```

With `proxy` configured, the client delegates quote fetching to your service endpoint.

### How It Works

1. Client calls quote APIs/hooks (`getQuotes`, `useQuotes`, etc).
2. `AggregatorProxy` serializes swap params into a query string and performs a GET to your endpoint.
3. Service fetches provider quotes and streams them immediately as each one resolves via
   `newQuoteStream(...)`.
4. Client decodes the stream with `decodeQuoteStream(...)` into quote promises.
5. Those promises resolve incrementally, so UI/state can update as results arrive.

Related APIs:

* [`newQuoteStream`](/core/functions/newQuoteStream)
* [`decodeQuoteStream`](/core/functions/decodeQuoteStream)

### Hono Service Example

This pattern is implemented in `examples/hono/src/index.ts`.

```ts
import { Hono } from "hono";
import { stream } from "hono/streaming";
import { zValidator } from "@hono/zod-validator";
import { newQuoteStream, prepareQuotes, type Quote, type SwapParams } from "@spandex/core";

const app = new Hono();

app.get("/quotes/stream", zValidator("query", querySchema), async (c) => {
  const swap = c.req.valid("query") satisfies SwapParams;
  return stream(c, async (streamWriter) => {
    const prepared = await prepareQuotes<Quote>({
      swap,
      config,
      mapFn: (quote: Quote) => Promise.resolve(quote),
    });
    await streamWriter.pipe(newQuoteStream(prepared));
  });
});
```

### React Streaming and AsyncIterators

`useQuotes` defaults to streamed results (`streamResults: true`) and uses TanStack
`streamedQuery`. Internally, quote/simulation promises are exposed as an `AsyncIterable` so each
result can be yielded as soon as it is ready.

This is what enables progressive quote rendering instead of waiting for all providers to finish.

### Simulation Placement Today

Today, with the built-in proxy path, quote fetching is server-side but simulation still runs on the
client (using the configured `PublicClient`).

<Callout type="info">
  You can move simulation to the service layer with a custom endpoint/contract if you want full
  server-side execution, but the default proxy flow is quote streaming first, client simulation
  second.
</Callout>


## Move along... nothing to see here!