> ## Documentation Index
> Fetch the complete documentation index at: https://docs.o1.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Quote and execute optimal swaps on Base through a single REST endpoint, backed by the O1Router contract and a multi-venue routing engine.

<Note>
  The DEX Aggregator API is currently **Base mainnet only** (`chainId: 8453`). Multi-chain support is on the roadmap.
</Note>

The o1.exchange DEX Aggregator API gives you institutional-grade swap pricing on Base in two HTTP calls. The routing engine searches across 20+ on-chain venues, splits trades when it improves output, and returns broadcast-ready calldata for the canonical `O1Router` contract.

<CardGroup cols={3}>
  <Card title="Multi-venue routing" icon="route">
    Quotes pulled from Uniswap V2/V3/V4, Aerodrome, PancakeSwap, Curve, DODO, WooFi, Hydrex, and proprietary on-chain PMMs.
  </Card>

  <Card title="Split optimization" icon="chart-line">
    A convex solver allocates input across multiple paths when the marginal output beats a single-route quote.
  </Card>

  <Card title="Permit-enabled swaps" icon="signature">
    Optional EIP-2612 permit payload lets the router pull tokens in the same transaction as the swap, no separate approval needed.
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="POST /quote">
    Send `chainId`, `tokenIn`, `tokenOut`, `amountIn`, and `slippageBps`. Receive a `quoteId`, an `expectedAmountOut`, and a `routePlan` describing which venues will be used.
  </Step>

  <Step title="POST /submit">
    Echo the `quoteId` plus the user's wallet address. Receive `{ to, data, value }`, ready to hand to any EVM signer.
  </Step>

  <Step title="Broadcast">
    The user's wallet signs and submits the transaction. The router executes all legs atomically and emits the configured slippage check.
  </Step>
</Steps>

If you don't need a price preview step, [`POST /execute`](/api/dex-aggregator/endpoints/execute) collapses quote and submit into one call.

## What you get

<CardGroup cols={2}>
  <Card title="Atomic split routes" icon="object-group">
    Up to 3 hops per route, multiple routes per swap. Slippage is checked per-leg and globally inside the router contract.
  </Card>

  <Card title="Native ETH support" icon="ethereum">
    Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` (or the zero address) as the `tokenIn` / `tokenOut` to swap raw ETH; the router handles the wrap and unwrap automatically.
  </Card>

  <Card title="Integrator fees" icon="coins">
    Pass `feeBps` on the quote request to take a cut of the output. The fee is enforced inside the router contract, not the API.
  </Card>
</CardGroup>

## Architecture at a glance

```mermaid theme={null} theme={null}
flowchart LR
  C[Client] -->|POST /quote| API[o1 API]
  API -->|quoteId + routePlan| C
  C -->|POST /submit| API
  API -->|to, data, value| C
  C -->|sendTransaction| W[Wallet]
  W -->|swapExactIn| R[O1Router]
  R --> V[(On-chain venues)]
```

The aggregator has three layers:

1. **Routing engine:** `packages/sdk/src/router` runs beam-search path finding plus split optimization. It calls a pool repository (live Codex queries by default) to fetch reserves and tick state.
2. **HTTP API:** Exposed by Convex HTTP actions in production and a Fastify service for self-hosting. Handles auth, rate limiting, quote storage, and calldata assembly.
3. **On-chain layer:** `O1Router.swapExactIn(...)` dispatches each leg to a venue adapter, enforces slippage, and optionally wraps or unwraps native ETH.

For the algorithmic details (beam search, convex split solver, AMM math per venue), see [`docs/ALGORITHM.md`](https://github.com/o1exchange/o1-dex-agg/blob/main/docs/ALGORITHM.md) in the source repo.

## Choose your integration pattern

<Tabs>
  <Tab title="Two-step (recommended for swap UIs)">
    Best when the user reviews the price before committing.

    ```
    POST /quote     →  show quote, poll until user clicks "Swap"
    POST /submit    →  build the tx
    sign + send     →  user wallet broadcasts
    ```

    See the [Quickstart](/api/dex-aggregator/quickstart) for full code.
  </Tab>

  <Tab title="One-step (instant swap)">
    Best for one-click flows, bots, and server-side integrations where there's no price preview.

    ```
    POST /execute   →  returns quote + calldata in one call
    sign + send     →  user wallet broadcasts
    ```

    See [`POST /execute`](/api/dex-aggregator/endpoints/execute) for the full request shape.
  </Tab>
</Tabs>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api/dex-aggregator/quickstart">
    Your first quote and swap in 30 lines of TypeScript.
  </Card>

  <Card title="Authentication" icon="key" href="/api/dex-aggregator/authentication">
    How to obtain and use an API key.
  </Card>

  <Card title="Endpoint reference" icon="code" href="/api/dex-aggregator/endpoints/quote">
    Request and response schemas for every endpoint.
  </Card>

  <Card title="Supported DEXes" icon="diagram-project" href="/api/dex-aggregator/reference/supported-dexes">
    The full list of venues in the routing graph.
  </Card>
</CardGroup>

<Tip>
  Already integrating? Skim [Quote freshness](/api/dex-aggregator/guides/quote-freshness) and [Error handling](/api/dex-aggregator/guides/error-handling) before you ship. They cover the two failure modes that catch most teams.
</Tip>