# Alliance DAO
Source: https://docs.o1.exchange/AllianceDAO

Strategic Partnerships Powering o1.exchange

<Frame>
  <img alt="Alliance DAO Partnership" />
</Frame>

## Elite Backing

<CardGroup>
  <Card title="Alliance DAO" icon="handshake">
    First investor in <a href="https://pump.fun">pump.fun</a>, <a href="https://moonshot.money/">Moonshot</a>, <a href="https://believe.app//">Believe App</a>
  </Card>
</CardGroup>

We're proud to announce that o1.exchange is backed by these elite investors in the blockchain space and many more, bringing institutional credibility and strategic resources to our platform.

These strategic partnerships empower o1.exchange to push the boundaries of DeFi trading technology. We're rapidly developing cutting-edge solutions to deliver a divine trading experience that sets new standards in the industry.


# Authentication
Source: https://docs.o1.exchange/api/dex-aggregator/authentication

Request an API key, send it on every request, and stay within the rate limit.

Every endpoint except [`GET /health`](/api/dex-aggregator/endpoints/health) requires an API key.

## How to get an API key

API keys are currently issued directly by the o1 team. Self-serve key creation is on the roadmap; for now, the flow is:

<Steps>
  <Step title="Reach out">
    Contact the o1 team through your usual partnership or support channel and request a DEX Aggregator API key. Include a short description of your integration (app name, expected volume, environment) so we can size your rate limit correctly.
  </Step>

  <Step title="Receive your key">
    The team provisions a key scoped to your integration and shares it securely. Each key is independent, so you can request additional keys for staging, dev, or per-environment isolation.
  </Step>

  <Step title="Store it securely">
    Treat your API key like a password. Keep it server-side, never commit it to source control, and never expose it in browser-side code.
  </Step>
</Steps>

<Tip>
  Need to rotate or revoke a key? Reach out to the same channel. The team can create a replacement and revoke the old one with a short overlap window so you can deploy without downtime.
</Tip>

## Sending the key

Pass your key on every request via the `x-api-key` HTTP header.

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X POST https://quiet-bloodhound-531.convex.site/quote \
    -H "x-api-key: o1_your_key_here" \
    -H "content-type: application/json" \
    -d '{
      "chainId": 8453,
      "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "1000000000",
      "slippageBps": 100
    }'
  ```

  ```ts TypeScript theme={null} theme={null}
  await fetch(`${API_URL}/quote`, {
    method: "POST",
    headers: {
      "x-api-key": process.env.O1_API_KEY!,
      "content-type": "application/json",
    },
    body: JSON.stringify({ /* ... */ }),
  });
  ```

  ```python Python theme={null} theme={null}
  import os, requests

  requests.post(
      f"{API_URL}/quote",
      headers={
          "x-api-key": os.environ["O1_API_KEY"],
          "content-type": "application/json",
      },
      json={ ... },
  )
  ```
</CodeGroup>

<Warning>
  Never expose your API key in client-side JavaScript. Proxy through your own server. If your key has leaked, revoke it immediately and rotate.
</Warning>

## Rate limits

The default rate limit is **120 requests per minute per API key**. Higher tiers are available on request — contact the o1 team if you expect sustained traffic above that.

The window is sliding (60 seconds), enforced server-side. When you exceed it you get a `429`:

```json theme={null} theme={null}
{
  "error": "rate limit exceeded",
  "limit": 120,
  "windowSec": 60
}
```

See [Rate limits](/api/dex-aggregator/reference/rate-limits) for the recommended retry strategy.

## Error responses

<Tabs>
  <Tab title="401 Unauthorized">
    Missing or invalid `x-api-key`.

    ```json theme={null} theme={null}
    { "error": "unauthorized" }
    ```
  </Tab>

  <Tab title="429 Rate limited">
    You've exceeded the per-minute quota. Back off for at least one second before retrying.

    ```json theme={null} theme={null}
    {
      "error": "rate limit exceeded",
      "limit": 120,
      "windowSec": 60
    }
    ```
  </Tab>
</Tabs>

## Best practices

<CardGroup>
  <Card title="One key per integration" icon="layer-group">
    Use a distinct key per app, environment, or backend service. Makes revocation painless when something rotates.
  </Card>

  <Card title="Rotate proactively" icon="rotate">
    Rotate keys quarterly or whenever an engineer with access leaves the team. Old keys can stay live for a short overlap window during the migration.
  </Card>

  <Card title="Log key usage server-side" icon="chart-bar">
    Tag your outbound requests with a request ID so you can correlate API errors with your server logs.
  </Card>

  <Card title="Honor 429s gracefully" icon="hand">
    On `429`, back off and retry with jitter. Don't hammer.
  </Card>
</CardGroup>


# POST /execute
Source: https://docs.o1.exchange/api/dex-aggregator/endpoints/execute

openapi.yaml POST /execute
One-shot quote + submit. Returns a fresh quote and broadcast-ready calldata in a single call.

`POST /execute` is the one-step convenience endpoint. It runs `/quote` and `/submit` server-side and returns both the route plan (so you can display it) and the calldata (so you can broadcast).

Use this when:

* You don't need a separate price preview step (one-click swap, server-side bot).
* You want to avoid the `quoteId` round trip.
* You always submit immediately after quoting.

For UIs that show a quote, let the user think, then submit, prefer the [`/quote` + `/submit`](/api/dex-aggregator/guides/integration-patterns) two-step flow so the user sees the final price before signing.

<Info>
  * **Authentication:** `x-api-key` header required.
  * **`user` is required** here (unlike `/quote`) because the response includes signed-ready calldata.
</Info>

## Request

<Tabs>
  <Tab title="Endpoint">
    ```http theme={null} theme={null}
    POST {API_URL}/execute
    Content-Type: application/json
    x-api-key: <YOUR_API_KEY>
    ```
  </Tab>

  <Tab title="Body">
    ```json theme={null} theme={null}
    {
      "chainId": 8453,
      "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "1000000000",
      "slippageBps": 100,
      "user": "0xYourWalletAddress",
      "useNativeIn": false,
      "unwrapNativeOut": true,
      "feeBps": 30
    }
    ```
  </Tab>
</Tabs>

### Body parameters

`/execute` accepts the union of `/quote` and `/submit` parameters.

| Field                 | Type             | Required | Description                                        |
| --------------------- | ---------------- | -------- | -------------------------------------------------- |
| `chainId`             | integer          | yes      | `8453` for Base.                                   |
| `tokenIn`             | address          | yes      | Token to sell. Native sentinel allowed.            |
| `tokenOut`            | address          | yes      | Token to buy. Native sentinel allowed.             |
| `amountIn`            | string           | yes      | Amount in wei as a decimal string.                 |
| `slippageBps`         | integer          | yes      | Slippage tolerance in bps (`0..10000`).            |
| `user`                | address          | yes      | Wallet that will sign the tx.                      |
| `useNativeIn`         | boolean          | no       | Override native-in detection.                      |
| `unwrapNativeOut`     | boolean          | no       | Receive native ETH instead of WETH.                |
| `feeBps`              | integer          | no       | Integrator fee in bps.                             |
| `maxHops`             | integer          | no       | Default `3`.                                       |
| `splitEnabled`        | boolean          | no       | Default `true`.                                    |
| `enforcePoolDisjoint` | boolean          | no       | Default `false`.                                   |
| `allowedDexes`        | array of `DexId` | no       | Restrict routing to specific venues.               |
| `permit`              | object           | no       | EIP-2612 permit payload (same shape as `/submit`). |

See [`POST /quote`](/api/dex-aggregator/endpoints/quote) and [`POST /submit`](/api/dex-aggregator/endpoints/submit) for full descriptions of each field.

## Response

<Tabs>
  <Tab title="200 OK">
    ```json theme={null} theme={null}
    {
      "quoteId": "a1b2c3d4e5f6...",
      "chainId": 8453,
      "to": "0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3",
      "data": "0x...",
      "value": "0",
      "expiresAt": 1712180000000,
      "routePlan": {
        "chainId": 8453,
        "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "tokenOut": "0x4200000000000000000000000000000000000006",
        "amountIn": "1000000000",
        "expectedAmountOut": "484446072048780734",
        "minAmountOut": "479601611328292926",
        "slippageBps": 100,
        "blockNumber": 44266656,
        "routes": [ /* ... */ ]
      }
    }
    ```
  </Tab>

  <Tab title="400 Bad Request">
    ```json theme={null} theme={null}
    { "error": "no routes for pair" }
    ```
  </Tab>

  <Tab title="401 Unauthorized">
    ```json theme={null} theme={null}
    { "error": "unauthorized" }
    ```
  </Tab>

  <Tab title="429 Rate Limited">
    ```json theme={null} theme={null}
    {
      "error": "rate limit exceeded",
      "limit": 120,
      "windowSec": 60
    }
    ```
  </Tab>
</Tabs>

### Response fields

A union of the `/quote` response (so you can display the price) and `/submit` response (so you can broadcast).

| Field       | Type    | Description                                                                           |
| ----------- | ------- | ------------------------------------------------------------------------------------- |
| `quoteId`   | string  | The freshly issued quote ID. Useful for log correlation.                              |
| `chainId`   | integer | `8453`.                                                                               |
| `to`        | address | Always the `O1Router`.                                                                |
| `data`      | hex     | `swapExactIn(...)` calldata.                                                          |
| `value`     | string  | `msg.value` in wei.                                                                   |
| `expiresAt` | integer | Unix milliseconds at which the cached quote drops.                                    |
| `routePlan` | object  | Full route plan. See [RoutePlan reference](/api/dex-aggregator/reference/route-plan). |

## Examples

<CodeGroup>
  ```ts TypeScript theme={null} theme={null}
  const exec = await fetch(`${API_URL}/execute`, {
    method: "POST",
    headers: {
      "x-api-key": process.env.O1_API_KEY!,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      chainId: 8453,
      tokenIn: USDC,
      tokenOut: WETH,
      amountIn: "1000000000",
      slippageBps: 100,
      user: walletAddress,
    }),
  }).then((r) => r.json());

  const txHash = await walletClient.sendTransaction({
    to: exec.to as `0x${string}`,
    data: exec.data as `0x${string}`,
    value: BigInt(exec.value),
  });
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST https://quiet-bloodhound-531.convex.site/execute \
    -H "x-api-key: $O1_API_KEY" \
    -H "content-type: application/json" \
    -d '{
      "chainId": 8453,
      "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "1000000000",
      "slippageBps": 100,
      "user": "0xYourWalletAddress"
    }'
  ```
</CodeGroup>

<Tip>
  `/execute` always returns a fresh quote. There's no risk of `404 expired` here because the quote is consumed immediately on the server side.
</Tip>


# GET /health
Source: https://docs.o1.exchange/api/dex-aggregator/endpoints/health

openapi.yaml GET /health
Liveness probe for the DEX Aggregator API.

Returns `{ "ok": true }` when the service is reachable. No authentication required.

<Info>
  This endpoint is **public** — it does not require an `x-api-key` header.
</Info>

## Request

```http theme={null} theme={null}
GET {API_URL}/health
```

## Response

```json theme={null} theme={null}
{ "ok": true }
```

## When to use this

<CardGroup>
  <Card title="CI / monitoring" icon="heart-pulse">
    Schedule periodic health checks from your monitoring system. Treat anything other than `200 { "ok": true }` as down.
  </Card>

  <Card title="Connectivity self-test" icon="plug">
    Use as the first call in an integration test to confirm DNS, TLS, and API key plumbing without spending quota on a real quote.
  </Card>
</CardGroup>

```bash theme={null} theme={null}
curl https://quiet-bloodhound-531.convex.site/health
```


# POST /quote
Source: https://docs.o1.exchange/api/dex-aggregator/endpoints/quote

openapi.yaml POST /quote
Price a swap and receive a routePlan you can hand back to /submit. Read-only, no user address required.

Use `POST /quote` to fetch a price. The response includes a stable `quoteId` you echo on `/submit` when the user is ready to swap.

<Info>
  * **Authentication:** `x-api-key` header required.
  * **Rate limit:** 120 req/min per key (default). See [Rate limits](/api/dex-aggregator/reference/rate-limits).
</Info>

## Request

<Tabs>
  <Tab title="Endpoint">
    ```http theme={null} theme={null}
    POST {API_URL}/quote
    Content-Type: application/json
    x-api-key: <YOUR_API_KEY>
    ```
  </Tab>

  <Tab title="Body">
    ```json theme={null} theme={null}
    {
      "chainId": 8453,
      "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "1000000000",
      "slippageBps": 100,
      "feeBps": 30,
      "maxHops": 3,
      "splitEnabled": true
    }
    ```
  </Tab>
</Tabs>

### Body parameters

| Field                 | Type             | Required | Description                                                                                                   |
| --------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `chainId`             | integer          | yes      | EVM chain ID. Currently only `8453` (Base) is supported.                                                      |
| `tokenIn`             | address          | yes      | Token to sell. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` or the zero address for native ETH.           |
| `tokenOut`            | address          | yes      | Token to buy. Same native sentinel rules apply.                                                               |
| `amountIn`            | string           | yes      | Amount in base units (wei) as a decimal string. Must be `> 0`.                                                |
| `slippageBps`         | integer          | yes      | Slippage tolerance in basis points (`100` = 1%). Range `0..10000`.                                            |
| `feeBps`              | integer          | no       | Integrator fee in basis points, taken out of `expectedAmountOut`. Range `0..10000`.                           |
| `maxHops`             | integer          | no       | Maximum hops per route. Default `3`.                                                                          |
| `splitEnabled`        | boolean          | no       | Allow the optimizer to split the trade across multiple routes when it improves output. Default `true`.        |
| `enforcePoolDisjoint` | boolean          | no       | When splitting, require routes to use disjoint pool sets. Off by default.                                     |
| `allowedDexes`        | array of `DexId` | no       | Restrict routing to a subset of venues. See [Supported DEXes](/api/dex-aggregator/reference/supported-dexes). |
| `taker`               | address          | no       | Optional taker hint. Doesn't affect pricing for most callers.                                                 |
| `timeBudgetMs`        | integer          | no       | Per-request override of the optimizer wall-clock budget. Range `50..10000`.                                   |

## Response

<Tabs>
  <Tab title="200 OK">
    ```json theme={null} theme={null}
    {
      "quoteId": "a1b2c3d4e5f6...",
      "expiresAt": 1712180000000,
      "routePlan": {
        "chainId": 8453,
        "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "tokenOut": "0x4200000000000000000000000000000000000006",
        "amountIn": "1000000000",
        "expectedAmountOut": "484446072048780734",
        "minAmountOut": "479601611328292926",
        "slippageBps": 100,
        "feeBps": 30,
        "blockNumber": 44266656,
        "gasEstimate": { "gasUnits": 300000 },
        "feeBreakdown": {
          "protocolFeeAmount": "1457804507741243911",
          "integratorFeeAmount": "0"
        },
        "routes": [
          {
            "amountIn": "1000000000",
            "legs": [
              {
                "dex": "UNIV3",
                "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
                "tokenOut": "0x4200000000000000000000000000000000000006",
                "amountIn": "1000000000",
                "minOut": "0",
                "poolId": "0xd0b5...f224",
                "data": { "kind": "v3_direct", "pool": "0xd0b5...f224" }
              }
            ]
          }
        ],
        "metadata": {
          "candidatePaths": 16,
          "selectedPaths": 1,
          "connectorsConsidered": [
            "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
            "0x9401e5e6564db35c0f86573a9828df69fc778631"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="400 Bad Request">
    ```json theme={null} theme={null}
    { "error": "amountIn must be > 0" }
    ```

    Other common 400 messages: `chainId required`, `slippageBps out of range`, `no routes for pair`.
  </Tab>

  <Tab title="401 Unauthorized">
    ```json theme={null} theme={null}
    { "error": "unauthorized" }
    ```
  </Tab>

  <Tab title="429 Rate Limited">
    ```json theme={null} theme={null}
    {
      "error": "rate limit exceeded",
      "limit": 120,
      "windowSec": 60
    }
    ```
  </Tab>
</Tabs>

### Response fields

| Field       | Type    | Description                                                                                                                                             |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `quoteId`   | string  | Stable identifier for this quote. Hand to `/submit`.                                                                                                    |
| `expiresAt` | integer | Unix milliseconds at which the cached quote drops.                                                                                                      |
| `routePlan` | object  | Full plan including pricing, gas estimate, and per-leg detail. See the [RoutePlan reference](/api/dex-aggregator/reference/route-plan) for every field. |

The fields you'll most commonly surface to users:

* `routePlan.expectedAmountOut` — the price you display
* `routePlan.minAmountOut` — the worst case after slippage
* `routePlan.routes[].legs[].dex` — list of venues used (e.g. `UNIV3 → AERODROME_CL`)
* `routePlan.feeBps` — protocol + integrator fee in bps
* `routePlan.gasEstimate.gasUnits` — estimated gas for the swap

## Caching and freshness

Quotes are cached server-side under their `quoteId` for roughly 10 seconds. After `expiresAt`, calling `/submit` returns `404 quote not found or expired`.

For UIs that show a live price, the recommended pattern is to re-fetch the quote every 5 to 8 seconds while the swap modal is open. See [Quote freshness](/api/dex-aggregator/guides/quote-freshness).

## Examples

<CodeGroup>
  ```ts TypeScript theme={null} theme={null}
  const quote = await fetch(`${API_URL}/quote`, {
    method: "POST",
    headers: {
      "x-api-key": process.env.O1_API_KEY!,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      chainId: 8453,
      tokenIn: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      tokenOut: "0x4200000000000000000000000000000000000006",
      amountIn: "1000000000",
      slippageBps: 100,
    }),
  }).then((r) => r.json());
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST https://quiet-bloodhound-531.convex.site/quote \
    -H "x-api-key: $O1_API_KEY" \
    -H "content-type: application/json" \
    -d '{
      "chainId": 8453,
      "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "1000000000",
      "slippageBps": 100
    }'
  ```
</CodeGroup>

<Tip>
  Pair this with [`POST /submit`](/api/dex-aggregator/endpoints/submit) for the standard two-step flow, or use [`POST /execute`](/api/dex-aggregator/endpoints/execute) when you don't need a price preview step.
</Tip>


# POST /submit
Source: https://docs.o1.exchange/api/dex-aggregator/endpoints/submit

openapi.yaml POST /submit
Build a broadcast-ready transaction from a previously fetched quoteId.

Use `POST /submit` to convert a `quoteId` from [`POST /quote`](/api/dex-aggregator/endpoints/quote) into the calldata your wallet broadcasts.

<Info>
  * **Authentication:** `x-api-key` header required.
  * **Quote TTL:** quotes expire roughly 10 seconds after `/quote`. Submitting an expired `quoteId` returns `404`.
</Info>

## Request

<Tabs>
  <Tab title="Endpoint">
    ```http theme={null} theme={null}
    POST {API_URL}/submit
    Content-Type: application/json
    x-api-key: <YOUR_API_KEY>
    ```
  </Tab>

  <Tab title="Body">
    ```json theme={null} theme={null}
    {
      "quoteId": "a1b2c3d4e5f6...",
      "user": "0xYourWalletAddress",
      "useNativeIn": false,
      "unwrapNativeOut": true
    }
    ```
  </Tab>
</Tabs>

### Body parameters

| Field                     | Type    | Required | Description                                                                                                                 |
| ------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `quoteId`                 | string  | yes      | The `quoteId` from a recent `/quote` response.                                                                              |
| `user`                    | address | yes      | The wallet that will sign and broadcast the transaction.                                                                    |
| `useNativeIn`             | boolean | no       | Override `routePlan.nativeIn`. Set `true` to send native ETH; the router wraps `msg.value` to WETH before dispatching legs. |
| `unwrapNativeOut`         | boolean | no       | Override `routePlan.nativeOut`. Set `true` to receive native ETH instead of WETH.                                           |
| `permit`                  | object  | no       | Optional EIP-2612 permit payload for one-tx approve+swap. See [`permit` payload](#permit-payload) below.                    |
| `gasPriceWei`             | string  | no       | Hint for legacy gas pricing (`gasPrice`).                                                                                   |
| `maxFeePerGasWei`         | string  | no       | Hint for EIP-1559 `maxFeePerGas`.                                                                                           |
| `maxPriorityFeePerGasWei` | string  | no       | Hint for EIP-1559 `maxPriorityFeePerGas`.                                                                                   |

<Note>
  The gas price fields are hints only. They are not currently echoed back into the calldata; your wallet client should set its own gas pricing when broadcasting.
</Note>

#### `permit` payload

When you have a fresh EIP-2612 permit signature for `tokenIn`, include it to skip the standard `approve` transaction.

```json theme={null} theme={null}
{
  "permit": {
    "value": "1000000000",
    "deadline": 1712180600,
    "v": 27,
    "r": "0x...",
    "s": "0x..."
  }
}
```

| Field           | Type       | Notes                                                        |
| --------------- | ---------- | ------------------------------------------------------------ |
| `value`         | string     | Amount permitted in token base units. Must be `>= amountIn`. |
| `deadline`      | integer    | Unix seconds at which the permit expires.                    |
| `v` / `r` / `s` | components | EIP-2612 signature pieces.                                   |

The router consumes the permit inside the same transaction; if it fails, the whole swap reverts. See [ERC-20 approvals](/api/dex-aggregator/guides/erc20-approvals) for the full pattern.

## Response

<Tabs>
  <Tab title="200 OK">
    ```json theme={null} theme={null}
    {
      "quoteId": "a1b2c3d4e5f6...",
      "chainId": 8453,
      "to": "0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3",
      "data": "0x...",
      "value": "0"
    }
    ```
  </Tab>

  <Tab title="404 Not Found">
    ```json theme={null} theme={null}
    { "error": "quote not found or expired" }
    ```

    The `quoteId` either never existed or has aged out of the cache. Re-fetch via `/quote` and retry.
  </Tab>

  <Tab title="400 Bad Request">
    ```json theme={null} theme={null}
    { "error": "user is required" }
    ```

    Other common 400 messages: `invalid user address`, `permit signature invalid`.
  </Tab>

  <Tab title="401 Unauthorized">
    ```json theme={null} theme={null}
    { "error": "unauthorized" }
    ```
  </Tab>

  <Tab title="429 Rate Limited">
    ```json theme={null} theme={null}
    {
      "error": "rate limit exceeded",
      "limit": 120,
      "windowSec": 60
    }
    ```
  </Tab>
</Tabs>

### Response fields

| Field     | Type    | Description                                                                                               |
| --------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `quoteId` | string  | Echo of the `quoteId` you submitted.                                                                      |
| `chainId` | integer | Always `8453` while only Base is supported.                                                               |
| `to`      | address | Always the `O1Router` address. See [Router contract](/api/dex-aggregator/reference/router-contract).      |
| `data`    | hex     | Encoded `swapExactIn(...)` calldata.                                                                      |
| `value`   | string  | `msg.value` to send with the transaction in wei. Non-zero only for native-in swaps (`useNativeIn: true`). |

## Sending the transaction

The response is intentionally minimal so any signer works. Example with `viem`:

```ts theme={null} theme={null}
const txHash = await walletClient.sendTransaction({
  to: submit.to as `0x${string}`,
  data: submit.data as `0x${string}`,
  value: BigInt(submit.value),
});
```

ethers v6:

```ts theme={null} theme={null}
const txResponse = await wallet.sendTransaction({
  to: submit.to,
  data: submit.data,
  value: submit.value,
});
```

<Warning>
  Do not modify `data` before sending. The router validates the route plan against the submitted `quoteId`; any tamper attempt will revert.
</Warning>

## Native ETH and unwrap behavior

| Want to            | Set on `/quote`                                        | Set on `/submit`        |
| ------------------ | ------------------------------------------------------ | ----------------------- |
| Sell native ETH    | `tokenIn` = native sentinel (`0xEeee...EEeE` or `0x0`) | `useNativeIn: true`     |
| Receive native ETH | `tokenOut` = native sentinel                           | `unwrapNativeOut: true` |

When you sell native ETH, the response `value` carries `amountIn` and the router wraps to WETH internally. See the [Native ETH guide](/api/dex-aggregator/guides/native-eth) for the full matrix.

## Common pitfalls

<CardGroup>
  <Card title="404 on /submit" icon="clock">
    Quote expired. Re-fetch via `/quote` with the same parameters and resubmit. Don't cache `quoteId` longer than `expiresAt` minus a small safety window.
  </Card>

  <Card title="`value` is 0 for ETH swaps" icon="circle-exclamation">
    You forgot `useNativeIn: true`. The router can't infer it from `tokenIn` alone in `/submit` because the API does not assume the user has changed their mind since `/quote`.
  </Card>

  <Card title="Tx reverts with slippage error" icon="triangle-exclamation">
    Pool state moved between `/quote` and broadcast. Increase `slippageBps` slightly or re-quote and resend.
  </Card>

  <Card title="Allowance error" icon="lock">
    The user hasn't approved the router for `tokenIn`. Approve `O1Router` for at least `amountIn`, or use a `permit` payload. See [ERC-20 approvals](/api/dex-aggregator/guides/erc20-approvals).
  </Card>
</CardGroup>


# ERC-20 approvals
Source: https://docs.o1.exchange/api/dex-aggregator/guides/erc20-approvals

How to grant the O1Router permission to spend your tokens — including the gasless EIP-2612 permit flow.

Before the router can pull `tokenIn` from a user, the user must approve the router as a spender. This is standard ERC-20 behavior. The aggregator supports two patterns:

1. **Standard `approve` + swap** — two transactions, but works for any ERC-20.
2. **EIP-2612 permit + swap** — one transaction, but only works for tokens that implement the permit extension.

<Note>
  No approval is needed when `tokenIn` is native ETH (using the sentinel `0xEeee...EEeE` or `0x0`). In that case, the router pulls value via `msg.value`. See [Native ETH](/api/dex-aggregator/guides/native-eth).
</Note>

## Pattern 1: standard `approve`

This is the universal fallback. Two transactions per first swap, then no approvals on subsequent swaps if the previous allowance is large enough.

```ts theme={null} theme={null}
import { erc20Abi } from "viem";

const ROUTER = "0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3";

// 1. Read current allowance
const allowance = await publicClient.readContract({
  address: tokenIn,
  abi: erc20Abi,
  functionName: "allowance",
  args: [walletAddress, ROUTER],
});

// 2. Approve if insufficient
if (allowance < BigInt(amountIn)) {
  const approveHash = await walletClient.writeContract({
    address: tokenIn,
    abi: erc20Abi,
    functionName: "approve",
    args: [ROUTER, BigInt(amountIn)],
  });
  await publicClient.waitForTransactionReceipt({ hash: approveHash });
}

// 3. Now safe to call /submit and broadcast the swap
```

### Approve amount strategies

<Tabs>
  <Tab title="Approve exact amount (recommended)">
    Approve exactly `amountIn`. Re-approves on every swap. Safest from a security standpoint — the router only ever has rights to the exact amount being swapped.

    ```ts theme={null} theme={null}
    args: [ROUTER, BigInt(amountIn)],
    ```
  </Tab>

  <Tab title="Approve max (least friction)">
    Approve `2^256 - 1`. User signs an approve once and never sees an approve dialog again for that token.

    ```ts theme={null} theme={null}
    const MAX_UINT256 = (1n << 256n) - 1n;
    args: [ROUTER, MAX_UINT256],
    ```

    <Warning>
      Max allowance means the router has perpetual rights to spend that token. Any future bug or compromise affects every wallet that approved max. Most consumer swap UIs do this; high-value flows usually don't.
    </Warning>
  </Tab>

  <Tab title="Approve a buffered amount">
    Approve `amountIn × 1.1` or some user-configured tier (e.g. "approve enough for 10 swaps"). Compromise between friction and risk.
  </Tab>
</Tabs>

## Pattern 2: EIP-2612 permit (one transaction)

For tokens that implement EIP-2612 (USDC and a growing number of others on Base), the user can sign an off-chain permit that the router consumes inside the same transaction as the swap. Net effect: **one signature, one transaction, no `approve` step**.

### How it works

<Steps>
  <Step title="Build the permit typed data">
    Read the token's `name`, `EIP712_VERSION`, and the user's `nonces(user)`. Construct the EIP-712 domain and message.
  </Step>

  <Step title="User signs the permit off-chain">
    Use `signTypedData` (eth\_signTypedData\_v4). No gas, no on-chain state change.
  </Step>

  <Step title="Send the permit on /submit">
    Pass `{ value, deadline, v, r, s }` in the `permit` field on `POST /submit`.
  </Step>

  <Step title="Router consumes it atomically">
    `O1Router.swapExactIn(...)` calls `IERC20Permit(token).permit(...)` then pulls funds, all in one tx.
  </Step>
</Steps>

### Example

```ts theme={null} theme={null}
import { signTypedData } from "viem/actions";

const PERMIT_TYPES = {
  Permit: [
    { name: "owner", type: "address" },
    { name: "spender", type: "address" },
    { name: "value", type: "uint256" },
    { name: "nonce", type: "uint256" },
    { name: "deadline", type: "uint256" },
  ],
};

async function buildPermit(token: `0x${string}`, owner: `0x${string}`, value: bigint) {
  const [name, nonce, chainId] = await Promise.all([
    publicClient.readContract({ address: token, abi: erc20PermitAbi, functionName: "name" }),
    publicClient.readContract({ address: token, abi: erc20PermitAbi, functionName: "nonces", args: [owner] }),
    publicClient.getChainId(),
  ]);

  const deadline = Math.floor(Date.now() / 1000) + 600; // 10 minutes

  const signature = await walletClient.signTypedData({
    account: owner,
    domain: { name, version: "1", chainId, verifyingContract: token },
    types: PERMIT_TYPES,
    primaryType: "Permit",
    message: {
      owner,
      spender: ROUTER,
      value,
      nonce,
      deadline: BigInt(deadline),
    },
  });

  // Split into v / r / s
  const r = `0x${signature.slice(2, 66)}` as const;
  const s = `0x${signature.slice(66, 130)}` as const;
  const v = parseInt(signature.slice(130, 132), 16);

  return { value: value.toString(), deadline, v, r, s };
}
```

Then on `/submit`:

```ts theme={null} theme={null}
const permit = await buildPermit(tokenIn, walletAddress, BigInt(amountIn));

const submit = await fetch(`${API_URL}/submit`, {
  method: "POST",
  headers: { "x-api-key": API_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    quoteId: quote.quoteId,
    user: walletAddress,
    permit,
  }),
}).then((r) => r.json());

const txHash = await walletClient.sendTransaction({
  to: submit.to as `0x${string}`,
  data: submit.data as `0x${string}`,
  value: BigInt(submit.value),
});
```

<Tip>
  Cache `name` and the EIP-712 domain per token to avoid an RPC call on every swap. Don't cache `nonce` though; it changes after every permit consumption.
</Tip>

## Detecting permit support

Not every token implements EIP-2612. The cheapest way to detect support is to read `nonces(user)` on the token and treat a successful read as a positive signal. Tokens without permit will revert.

```ts theme={null} theme={null}
async function supportsPermit(token: `0x${string}`, user: `0x${string}`): Promise<boolean> {
  try {
    await publicClient.readContract({
      address: token,
      abi: [{ name: "nonces", type: "function", stateMutability: "view", inputs: [{ name: "owner", type: "address" }], outputs: [{ type: "uint256" }] }],
      functionName: "nonces",
      args: [user],
    });
    return true;
  } catch {
    return false;
  }
}
```

For better UX, fall back to standard `approve` automatically when permit support is missing.

## Security checklist

<CardGroup>
  <Card title="Always approve the router only" icon="shield">
    The approval target is **always** the canonical `O1Router` address: `0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3`. Reject any UI that asks you to approve a different address while using this API.
  </Card>

  <Card title="Verify the spender on the response" icon="circle-check">
    `submit.to` should equal the router address. If it doesn't, abort and report.
  </Card>

  <Card title="Respect deadlines on permits" icon="clock">
    Use a short deadline (5 to 15 minutes). Don't sign permits with deadlines hours in the future — they're a long-lived approval risk if the signature leaks.
  </Card>

  <Card title="Don't reuse permits" icon="ban">
    Each permit signature consumes a `nonce`. Don't try to bundle multiple swaps under a single permit.
  </Card>
</CardGroup>


# Error handling
Source: https://docs.o1.exchange/api/dex-aggregator/guides/error-handling

How to interpret every error the API can return and the recommended retry strategy for each.

The API uses HTTP status codes plus a JSON body of the form `{ "error": "<message>" }` for every error. This guide covers what each status code means and the right response.

## Status code reference

| Status | Meaning                                 | Retry?                    |
| ------ | --------------------------------------- | ------------------------- |
| `200`  | Success                                 | n/a                       |
| `400`  | Validation error or no routes available | No (fix the request)      |
| `401`  | Missing or invalid `x-api-key`          | No (fix the key)          |
| `404`  | Quote expired (only on `/submit`)       | Yes (re-quote)            |
| `429`  | Rate limit exceeded                     | Yes (backoff)             |
| `5xx`  | Internal error                          | Yes (backoff with jitter) |

## Common error messages

<Tabs>
  <Tab title="400 examples">
    ```json theme={null} theme={null}
    { "error": "amountIn must be > 0" }
    ```

    ```json theme={null} theme={null}
    { "error": "no routes for pair" }
    ```

    ```json theme={null} theme={null}
    { "error": "slippageBps out of range" }
    ```

    ```json theme={null} theme={null}
    { "error": "invalid token address" }
    ```

    **Treatment:** show the user a clear message ("This pair has no liquidity right now"), do not retry. If `no routes for pair` happens often for a specific token, the token may not have routable on-chain liquidity on Base.
  </Tab>

  <Tab title="401 example">
    ```json theme={null} theme={null}
    { "error": "unauthorized" }
    ```

    **Treatment:** verify the `x-api-key` header is set, the key is current, and your code isn't accidentally trimming whitespace. If you've recently rotated, redeploy with the new key.
  </Tab>

  <Tab title="404 example (only on /submit)">
    ```json theme={null} theme={null}
    { "error": "quote not found or expired" }
    ```

    **Treatment:** call `/quote` with the same parameters and submit again. Don't show a user-facing error unless this happens twice in a row.

    See [Quote freshness](/api/dex-aggregator/guides/quote-freshness) for the full recovery pattern.
  </Tab>

  <Tab title="429 example">
    ```json theme={null} theme={null}
    {
      "error": "rate limit exceeded",
      "limit": 120,
      "windowSec": 60
    }
    ```

    **Treatment:** back off for at least 1 second, ideally with jitter (`1s + random(0..500ms)`). If you sustain this, contact the o1 team to request a higher rate limit.
  </Tab>

  <Tab title="5xx (internal)">
    ```json theme={null} theme={null}
    { "error": "internal error" }
    ```

    **Treatment:** retry once after 1-2 seconds with jitter. If the second retry fails, surface a generic error to the user and emit an internal alert.
  </Tab>
</Tabs>

## On-chain transaction failures

Errors above are HTTP errors. Once you have a `submit` response and broadcast the transaction, a separate class of failures can happen on-chain:

| Revert reason                                      | Likely cause                                                      | Fix                                                                      |
| -------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `Slippage`                                         | Pool state moved between `/quote` and inclusion.                  | Increase `slippageBps`, or re-quote and resend.                          |
| `TRANSFER_FROM_FAILED` / `INSUFFICIENT_ALLOWANCE`  | Allowance for `tokenIn` is below `amountIn`.                      | Approve the router for `amountIn`, or use a `permit` payload.            |
| `TRANSFER_FROM_FAILED` (with sufficient allowance) | The user's balance is below `amountIn`.                           | Validate balance before submitting.                                      |
| `Permit failed`                                    | Permit signature invalid or already consumed.                     | Re-sign with a fresh nonce; verify the EIP-712 domain matches the token. |
| `Out of gas`                                       | Gas estimate was too low (rare; happens during chain congestion). | Re-broadcast with a higher gas limit, e.g. `gasEstimate.gasUnits × 1.5`. |

<Tip>
  The on-chain `Slippage` revert is intentional. It means the safety net worked. If a user complains, the most common fix is "use slightly higher slippage" or "re-quote and retry quickly."
</Tip>

## Recommended retry policy

```ts theme={null} theme={null}
async function callWithRetry<T>(fn: () => Promise<Response>, maxRetries = 2): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fn();

    if (res.ok) return res.json();

    const body = await res.json().catch(() => ({}));

    // Non-retryable: fix the request and return
    if (res.status === 400 || res.status === 401) {
      throw new Error(body.error ?? `${res.status}`);
    }

    // 404 on /submit: caller must re-quote. Bubble up a typed error.
    if (res.status === 404) {
      throw new Error("QUOTE_EXPIRED");
    }

    // 429 / 5xx: back off and retry
    if (attempt === maxRetries) {
      throw new Error(body.error ?? `${res.status}`);
    }

    const baseDelay = res.status === 429 ? 1000 : 1500;
    const jitter = Math.random() * 500;
    await new Promise((r) => setTimeout(r, baseDelay + jitter));
  }
  throw new Error("unreachable");
}
```

Then in the submit handler:

```ts theme={null} theme={null}
try {
  const submit = await callWithRetry(() =>
    fetch(`${API_URL}/submit`, { /* ... */ }),
  );
  // broadcast as usual
} catch (e) {
  if (e.message === "QUOTE_EXPIRED") {
    const fresh = await refreshQuote(params);
    // retry submit with fresh.quoteId
  } else {
    showError(e.message);
  }
}
```

## What NOT to do

<CardGroup>
  <Card title="Don't retry 400 errors" icon="ban">
    `400` means the request itself is malformed or unroutable. Retrying doesn't help; fix the request.
  </Card>

  <Card title="Don't hammer on 429" icon="hand">
    The rate limit window is per API key. Retrying immediately after a `429` makes the situation worse and burns the rest of your minute. Always back off.
  </Card>

  <Card title="Don't surface raw errors to users" icon="user-shield">
    Translate `error` strings into UI-friendly copy. "no routes for pair" → "Couldn't find liquidity for this pair, try a different amount or token."
  </Card>

  <Card title="Don't ignore on-chain reverts" icon="link-slash">
    Always check `receipt.status === "success"` after `waitForTransactionReceipt`. A `0x` tx hash is not the same as a successful swap.
  </Card>
</CardGroup>


# Integration patterns
Source: https://docs.o1.exchange/api/dex-aggregator/guides/integration-patterns

When to use the two-step /quote + /submit flow versus the one-step /execute call.

The DEX Aggregator API supports two integration shapes. They produce equivalent on-chain transactions; the difference is when the routing engine runs.

<CardGroup>
  <Card title="Two-step" icon="layer-group">
    `/quote` → human reviews price → `/submit` → broadcast.

    Best for swap UIs.
  </Card>

  <Card title="One-step" icon="bolt">
    `/execute` → broadcast.

    Best for one-click flows and bots.
  </Card>
</CardGroup>

## Two-step (recommended for swap UIs)

Use this flow when a user reviews the quoted price before they commit.

```mermaid theme={null} theme={null}
sequenceDiagram
  participant U as User
  participant C as Client
  participant A as O1 API
  participant W as Wallet
  participant R as Router

  U->>C: Pick tokens, enter amount
  C->>A: POST /quote
  A-->>C: quoteId + routePlan
  C->>U: Display price + route
  U->>C: Click "Swap"
  C->>A: POST /submit (quoteId, user)
  A-->>C: { to, data, value }
  C->>W: sendTransaction
  W->>R: swapExactIn(...)
  R-->>W: tx hash
```

```ts theme={null} theme={null}
// 1. Quote
const quote = await fetch(`${API_URL}/quote`, {
  method: "POST",
  headers: { "x-api-key": API_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    chainId: 8453,
    tokenIn: USDC,
    tokenOut: WETH,
    amountIn: "1000000000",
    slippageBps: 100,
  }),
}).then((r) => r.json());

// 2. Display to user
showQuote({
  output: formatUnits(BigInt(quote.routePlan.expectedAmountOut), 18),
  minOutput: formatUnits(BigInt(quote.routePlan.minAmountOut), 18),
  route: quote.routePlan.routes
    .map((r) => r.legs.map((l) => l.dex).join(" → "))
    .join(" | "),
  fee: `${(quote.routePlan.feeBps ?? 0) / 100}%`,
});

// 3. User clicks "Swap" → build tx
const submit = await fetch(`${API_URL}/submit`, {
  method: "POST",
  headers: { "x-api-key": API_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    quoteId: quote.quoteId,
    user: walletAddress,
  }),
}).then((r) => r.json());

// 4. Send to wallet
const txHash = await walletClient.sendTransaction({
  to: submit.to as `0x${string}`,
  data: submit.data as `0x${string}`,
  value: BigInt(submit.value),
});
```

### Pros

* User confirms the price they see; no last-second surprise.
* You can run validation between quote and submit (e.g. "is this trade > \$X? require a confirm dialog").
* Clean separation between read (quote) and write (submit) for caching, analytics, and rate limiting.

### Cons

* Quotes have a TTL (\~10 seconds). If the user takes too long, `/submit` returns `404` and you must re-quote. See [Quote freshness](/api/dex-aggregator/guides/quote-freshness).
* Two API calls per swap.

***

## One-step (instant swap)

Use this flow when there's no preview step.

```mermaid theme={null} theme={null}
sequenceDiagram
  participant C as Client
  participant A as O1 API
  participant W as Wallet
  participant R as Router

  C->>A: POST /execute
  A-->>C: routePlan + { to, data, value }
  C->>W: sendTransaction
  W->>R: swapExactIn(...)
  R-->>W: tx hash
```

```ts theme={null} theme={null}
const exec = await fetch(`${API_URL}/execute`, {
  method: "POST",
  headers: { "x-api-key": API_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    chainId: 8453,
    tokenIn: USDC,
    tokenOut: WETH,
    amountIn: "1000000000",
    slippageBps: 100,
    user: walletAddress,
  }),
}).then((r) => r.json());

const txHash = await walletClient.sendTransaction({
  to: exec.to as `0x${string}`,
  data: exec.data as `0x${string}`,
  value: BigInt(exec.value),
});
```

### Pros

* Single round trip.
* No `quoteId` to track, no expiry to handle.

### Cons

* The user (or bot) doesn't see the price before signing. If you still want to show it, log `exec.routePlan.expectedAmountOut` after the fact.
* Less flexibility for caching and analytics, since each call rebuilds the full route plan server-side.

***

## Choosing the right pattern

| Use case                                      | Pattern                          |
| --------------------------------------------- | -------------------------------- |
| Standard swap UI with confirm dialog          | Two-step                         |
| One-click "swap now" button                   | One-step                         |
| Server-side market-maker / bot                | One-step                         |
| Limit-order style flow with delayed execution | Two-step (re-quote on each tick) |
| Mobile UI with poor connectivity              | One-step (fewer round trips)     |

<Tip>
  Even when you use `/execute` for the user-facing call, you can still hit `/quote` separately for live price display in the modal. Just be aware they consume separate rate-limit budget.
</Tip>

## Always: handle expired quotes

Whichever pattern you pick, treat `404 quote not found or expired` from `/submit` as recoverable: re-fetch `/quote` with the same parameters and retry. Don't surface this as a user-facing error unless it happens repeatedly.

See [Quote freshness](/api/dex-aggregator/guides/quote-freshness) for the full pattern.


# Native ETH
Source: https://docs.o1.exchange/api/dex-aggregator/guides/native-eth

Sell native ETH or receive native ETH directly, without manually wrapping or unwrapping WETH.

The `O1Router` handles all wrapping and unwrapping internally. From the API caller's perspective there are two flags:

| Flag              | Where                      | What it does                                                                                   |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------------- |
| `useNativeIn`     | `/submit` (and `/execute`) | When `true`, send `msg.value = amountIn` and the router wraps to WETH before dispatching legs. |
| `unwrapNativeOut` | `/submit` (and `/execute`) | When `true`, the router unwraps WETH to ETH for the recipient before completing the swap.      |

## Sentinel addresses for native ETH

When you want to swap **native ETH** in `tokenIn` or `tokenOut`, use one of these sentinels:

| Sentinel                                     | Notes                                           |
| -------------------------------------------- | ----------------------------------------------- |
| `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | Standard EIP-7528 native sentinel. Recommended. |
| `0x0000000000000000000000000000000000000000` | Zero-address fallback, also accepted.           |

The aggregator detects either form and sets `routePlan.nativeIn` or `routePlan.nativeOut` to `true` automatically. You still need to set the corresponding flag on `/submit` or `/execute`, since the user might have changed their mind about wrapping between quote and submit.

## The four common cases

<Tabs>
  <Tab title="ETH → ERC-20">
    Sell native ETH, receive an ERC-20 like USDC.

    **Quote:**

    ```json theme={null} theme={null}
    {
      "tokenIn": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "amountIn": "1000000000000000000",
      "slippageBps": 100,
      "chainId": 8453
    }
    ```

    **Submit:**

    ```json theme={null} theme={null}
    {
      "quoteId": "...",
      "user": "0x...",
      "useNativeIn": true
    }
    ```

    **Send transaction:** the response `value` will equal `amountIn` (`1000000000000000000`).

    ```ts theme={null} theme={null}
    await walletClient.sendTransaction({
      to: submit.to,
      data: submit.data,
      value: BigInt(submit.value), // = 1 ETH
    });
    ```

    **Approval:** none needed.
  </Tab>

  <Tab title="ERC-20 → ETH">
    Sell an ERC-20 like USDC, receive native ETH.

    **Quote:**

    ```json theme={null} theme={null}
    {
      "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "tokenOut": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "amountIn": "1000000000",
      "slippageBps": 100,
      "chainId": 8453
    }
    ```

    **Submit:**

    ```json theme={null} theme={null}
    {
      "quoteId": "...",
      "user": "0x...",
      "unwrapNativeOut": true
    }
    ```

    **Approval:** standard ERC-20 approve of the router for `amountIn`, or use `permit`.

    The router pulls USDC, swaps to WETH internally, then unwraps and sends ETH to `user` in the same transaction.
  </Tab>

  <Tab title="ETH → WETH (or WETH → ETH)">
    A pure wrap or unwrap also goes through the aggregator. The router uses a no-op routing path — there's no swap math involved, just a `deposit()` or `withdraw()` call against WETH.

    **Wrap:**

    ```json theme={null} theme={null}
    {
      "tokenIn":  "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      ...
    }
    ```

    Then on `/submit` set `useNativeIn: true`.

    **Unwrap:**

    ```json theme={null} theme={null}
    {
      "tokenIn":  "0x4200000000000000000000000000000000000006",
      "tokenOut": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      ...
    }
    ```

    Then on `/submit` set `unwrapNativeOut: true`.
  </Tab>

  <Tab title="ERC-20 → ERC-20">
    No native handling. Don't set either flag. The router pulls `tokenIn`, swaps to `tokenOut`, sends to the user.

    **Approval:** required (or use `permit`).
  </Tab>
</Tabs>

## Common mistakes

<CardGroup>
  <Card title="Forgot useNativeIn" icon="circle-exclamation">
    `/submit` response has `value: "0"` even though `tokenIn` was the native sentinel. Cause: you didn't set `useNativeIn: true` on `/submit`. The API errs on the side of safety and assumes you might have changed your mind.
  </Card>

  <Card title="Sending msg.value with an ERC-20 swap" icon="triangle-exclamation">
    The router rejects any non-zero `msg.value` when `useNativeIn` is `false`. If your wallet is sending ETH along, double-check you didn't carry over `value` from a previous swap.
  </Card>

  <Card title="Approving WETH unnecessarily" icon="lock">
    For an `ETH → ERC-20` swap with `useNativeIn: true`, the user does not need to approve WETH. The router handles the wrap from `msg.value` and the resulting WETH never leaves the router contract.
  </Card>

  <Card title="Missing unwrapNativeOut" icon="ethereum">
    User receives WETH instead of ETH because `unwrapNativeOut` was omitted on `/submit`. Always set it explicitly when you want native ETH back.
  </Card>
</CardGroup>

## Why both quote and submit need the flag

The aggregator detects native intent on `/quote` from the sentinel and sets `routePlan.nativeIn` / `routePlan.nativeOut`. But `/submit` requires you to re-confirm with the explicit flag because:

1. The `quoteId` is independent of the user. The same quote can be submitted by different users with different preferences.
2. Some integrators want to auto-wrap on the user's behalf, e.g. always pull ERC-20 WETH from the user even when the quote was for native ETH.

Always pass `useNativeIn` / `unwrapNativeOut` explicitly on `/submit` to remove ambiguity.


# Quote freshness
Source: https://docs.o1.exchange/api/dex-aggregator/guides/quote-freshness

How to keep the displayed price live in your UI and gracefully handle expired quotes.

Quotes are price snapshots at a specific block. Pool reserves, tick state, and competing trades can move the market between the moment you quote and the moment your transaction lands. The aggregator handles this with a short server-side cache TTL and explicit expiry semantics.

## The contract

<CardGroup>
  <Card title="TTL is ~10 seconds" icon="clock">
    Each `/quote` response includes `expiresAt` (Unix milliseconds). The default TTL is 10 seconds. After that, the cache entry is gone.
  </Card>

  <Card title="/submit returns 404 on expired quotes" icon="circle-xmark">
    Once `expiresAt` has passed, `POST /submit` with that `quoteId` returns `{ "error": "quote not found or expired" }`. Re-quote and retry.
  </Card>
</CardGroup>

## Recommended UI pattern

<Steps>
  <Step title="Fetch a fresh quote when the swap modal opens">
    On modal open, call `/quote` and store the result. Display the price.
  </Step>

  <Step title="Re-quote on a 5 to 8 second interval">
    While the modal is open, re-fetch the quote periodically. Compare `expectedAmountOut` against the previous value to decide whether to flash an "updated" indicator.
  </Step>

  <Step title="Stop polling on user action">
    When the user clicks "Swap" (or your equivalent), pause polling so the price doesn't change between their decision and the wallet prompt.
  </Step>

  <Step title="Submit using the latest quoteId">
    Always submit using the `quoteId` from the most recent successful `/quote`. Don't reuse an older one.
  </Step>

  <Step title="Handle 404 gracefully">
    If `/submit` returns `404`, automatically re-fetch `/quote` and retry once. Only surface a user-facing error if the second attempt also fails.
  </Step>
</Steps>

## Reference implementation

```ts theme={null} theme={null}
import { useEffect, useRef, useState } from "react";

interface QuoteState {
  quoteId: string;
  expectedOut: bigint;
  minOut: bigint;
  expiresAt: number;
}

function useLiveQuote(params: QuoteParams, isOpen: boolean) {
  const [quote, setQuote] = useState<QuoteState | null>(null);
  const isFreezingRef = useRef(false);

  useEffect(() => {
    if (!isOpen) return;

    let cancelled = false;
    const tick = async () => {
      if (cancelled || isFreezingRef.current) return;
      try {
        const q = await fetch(`${API_URL}/quote`, {
          method: "POST",
          headers: { "x-api-key": API_KEY, "content-type": "application/json" },
          body: JSON.stringify(params),
        }).then((r) => r.json());
        if (!cancelled && q.quoteId) {
          setQuote({
            quoteId: q.quoteId,
            expectedOut: BigInt(q.routePlan.expectedAmountOut),
            minOut: BigInt(q.routePlan.minAmountOut),
            expiresAt: q.expiresAt,
          });
        }
      } catch (e) {
        // ignore transient failures; next tick will retry
      }
    };

    tick();
    const id = setInterval(tick, 6000);
    return () => {
      cancelled = true;
      clearInterval(id);
    };
  }, [isOpen, JSON.stringify(params)]);

  const freeze = () => { isFreezingRef.current = true; };
  const unfreeze = () => { isFreezingRef.current = false; };

  return { quote, freeze, unfreeze };
}
```

Then in the swap submit handler:

```ts theme={null} theme={null}
async function onSwap() {
  if (!quote) return;
  freeze(); // stop background re-quoting

  try {
    const submit = await fetch(`${API_URL}/submit`, {
      method: "POST",
      headers: { "x-api-key": API_KEY, "content-type": "application/json" },
      body: JSON.stringify({ quoteId: quote.quoteId, user: walletAddress }),
    }).then(async (r) => {
      if (r.status === 404) {
        // Quote expired between the freeze and the submit. Re-quote and retry.
        const fresh = await refreshQuote(params);
        return fetch(`${API_URL}/submit`, {
          method: "POST",
          headers: { "x-api-key": API_KEY, "content-type": "application/json" },
          body: JSON.stringify({ quoteId: fresh.quoteId, user: walletAddress }),
        }).then((r2) => r2.json());
      }
      return r.json();
    });

    const txHash = await walletClient.sendTransaction({
      to: submit.to,
      data: submit.data,
      value: BigInt(submit.value),
    });
    onSuccess(txHash);
  } finally {
    unfreeze();
  }
}
```

## Why not use `/execute` for this?

`/execute` always returns a fresh quote, so it sidesteps the 404 problem. But:

* You lose the ability to display the quoted price *before* the user signs.
* Every `/execute` call burns rate-limit budget *and* re-runs the routing engine, so it's more expensive than alternating `/quote` and `/submit`.

Use `/execute` for one-click flows where preview doesn't matter. Use the two-step pattern with the freshness loop above for any UI that shows a price.

## Slippage as a freshness backstop

Even with aggressive re-quoting, your submitted transaction may land 1-2 blocks after `/quote` ran. Use `slippageBps` as the safety margin:

| Pair type                              | Recommended `slippageBps`   |
| -------------------------------------- | --------------------------- |
| Stablecoin to stablecoin (USDC → USDT) | `10` to `30` (0.1% to 0.3%) |
| Blue-chip to blue-chip (WETH → cbBTC)  | `30` to `100` (0.3% to 1%)  |
| Blue-chip to mid-cap                   | `100` to `300` (1% to 3%)   |
| Long tail / memecoins                  | `300` to `1000` (3% to 10%) |

The user's `minAmountOut` is set on the router, so the swap reverts cleanly if real output falls below the slippage threshold — your transaction never lands in a worse-than-expected state.

<Tip>
  Cache the user's preferred slippage per pair-type. Forcing the user to set slippage manually on every swap is a common UX pitfall.
</Tip>


# Introduction
Source: https://docs.o1.exchange/api/dex-aggregator/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>
  <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>
  <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>
  <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>


# Quickstart
Source: https://docs.o1.exchange/api/dex-aggregator/quickstart

Get a quote, build a transaction, and execute your first swap on Base in under five minutes.

This guide walks you through a complete swap from a TypeScript client. We'll trade **1,000 USDC for WETH** on Base, then receive native ETH back instead of WETH.

<Note>
  Production base URL is currently `https://quiet-bloodhound-531.convex.site`. If you're integrating against a vanity domain (e.g. `https://api.o1.exchange/dex`), substitute that throughout.
</Note>

## Prerequisites

<CardGroup>
  <Card title="API key" icon="key">
    See [Authentication](/api/dex-aggregator/authentication) to request one.
  </Card>

  <Card title="Base RPC URL" icon="server">
    Any Base mainnet RPC works. We use `viem` defaults below.
  </Card>

  <Card title="Wallet with USDC" icon="wallet">
    Plus a small ETH balance to pay gas (and approve the router if this is your first swap).
  </Card>
</CardGroup>

## 1. Set up your client

```ts theme={null} theme={null}
import { createPublicClient, createWalletClient, http, erc20Abi } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const API_URL = "https://quiet-bloodhound-531.convex.site";
const API_KEY = process.env.O1_API_KEY!;

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const publicClient = createPublicClient({ chain: base, transport: http() });
const walletClient = createWalletClient({ chain: base, account, transport: http() });

const USDC = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
const WETH = "0x4200000000000000000000000000000000000006";
```

## 2. Get a quote

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST {API_URL}/quote`

    ```ts theme={null} theme={null}
    const quote = await fetch(`${API_URL}/quote`, {
      method: "POST",
      headers: {
        "x-api-key": API_KEY,
        "content-type": "application/json",
      },
      body: JSON.stringify({
        chainId: 8453,
        tokenIn: USDC,
        tokenOut: WETH,
        amountIn: "1000000000",   // 1,000 USDC (6 decimals)
        slippageBps: 100,         // 1% slippage tolerance
      }),
    }).then((r) => r.json());
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null} theme={null}
    {
      "quoteId": "a1b2c3d4...",
      "expiresAt": 1712180000000,
      "routePlan": {
        "chainId": 8453,
        "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "tokenOut": "0x4200000000000000000000000000000000000006",
        "amountIn": "1000000000",
        "expectedAmountOut": "484446072048780734",
        "minAmountOut": "479601611328292926",
        "slippageBps": 100,
        "blockNumber": 44266656,
        "gasEstimate": { "gasUnits": 300000 },
        "routes": [
          {
            "amountIn": "1000000000",
            "legs": [
              {
                "dex": "UNIV3",
                "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
                "tokenOut": "0x4200000000000000000000000000000000000006",
                "amountIn": "1000000000",
                "minOut": "0",
                "poolId": "0xd0b5...f224",
                "data": { "kind": "v3_direct", "pool": "0xd0b5...f224" }
              }
            ]
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

The fields you'll display to the user:

* `routePlan.expectedAmountOut` — the price you quote
* `routePlan.minAmountOut` — the worst-case fill after slippage
* `routePlan.routes[].legs[].dex` — which venues are involved
* `expiresAt` — quote validity window (about 10 seconds; see [Quote freshness](/api/dex-aggregator/guides/quote-freshness))

## 3. Approve the router (first swap only)

<Note>
  Skip this step entirely if `tokenIn` is native ETH, or if you're using an EIP-2612 permit (see [`POST /submit`](/api/dex-aggregator/endpoints/submit) → `permit`).
</Note>

```ts theme={null} theme={null}
const ROUTER = "0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3";

const allowance = await publicClient.readContract({
  address: USDC,
  abi: erc20Abi,
  functionName: "allowance",
  args: [account.address, ROUTER],
});

if (allowance < BigInt(quote.routePlan.amountIn)) {
  await walletClient.writeContract({
    address: USDC,
    abi: erc20Abi,
    functionName: "approve",
    args: [ROUTER, BigInt(quote.routePlan.amountIn)],
  });
}
```

## 4. Build the transaction

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST {API_URL}/submit`

    ```ts theme={null} theme={null}
    const submit = await fetch(`${API_URL}/submit`, {
      method: "POST",
      headers: {
        "x-api-key": API_KEY,
        "content-type": "application/json",
      },
      body: JSON.stringify({
        quoteId: quote.quoteId,
        user: account.address,
        unwrapNativeOut: true,   // receive native ETH instead of WETH
      }),
    }).then((r) => r.json());
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null} theme={null}
    {
      "quoteId": "a1b2c3d4...",
      "chainId": 8453,
      "to": "0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3",
      "data": "0x...",
      "value": "0"
    }
    ```
  </Tab>
</Tabs>

## 5. Sign and send

```ts theme={null} theme={null}
const txHash = await walletClient.sendTransaction({
  to: submit.to as `0x${string}`,
  data: submit.data as `0x${string}`,
  value: BigInt(submit.value),
});

console.log(`Submitted: https://basescan.org/tx/${txHash}`);
```

That's it. Wait for the receipt with `publicClient.waitForTransactionReceipt({ hash: txHash })` and the swap is complete.

## Full example, end to end

<Accordion title="Complete TypeScript script">
  ```ts theme={null} theme={null}
  import { createPublicClient, createWalletClient, http, erc20Abi } from "viem";
  import { privateKeyToAccount } from "viem/accounts";
  import { base } from "viem/chains";

  const API_URL = "https://quiet-bloodhound-531.convex.site";
  const API_KEY = process.env.O1_API_KEY!;
  const ROUTER = "0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3";

  const USDC = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
  const WETH = "0x4200000000000000000000000000000000000006";

  async function main() {
    const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
    const publicClient = createPublicClient({ chain: base, transport: http() });
    const walletClient = createWalletClient({ chain: base, account, transport: http() });

    // 1. Quote
    const quote = await fetch(`${API_URL}/quote`, {
      method: "POST",
      headers: { "x-api-key": API_KEY, "content-type": "application/json" },
      body: JSON.stringify({
        chainId: 8453,
        tokenIn: USDC,
        tokenOut: WETH,
        amountIn: "1000000000",
        slippageBps: 100,
      }),
    }).then((r) => r.json());

    console.log(`Expected out: ${quote.routePlan.expectedAmountOut} WETH (wei)`);

    // 2. Approve if needed
    const allowance = await publicClient.readContract({
      address: USDC,
      abi: erc20Abi,
      functionName: "allowance",
      args: [account.address, ROUTER],
    });
    if (allowance < BigInt(quote.routePlan.amountIn)) {
      const approveHash = await walletClient.writeContract({
        address: USDC,
        abi: erc20Abi,
        functionName: "approve",
        args: [ROUTER, BigInt(quote.routePlan.amountIn)],
      });
      await publicClient.waitForTransactionReceipt({ hash: approveHash });
    }

    // 3. Submit
    const submit = await fetch(`${API_URL}/submit`, {
      method: "POST",
      headers: { "x-api-key": API_KEY, "content-type": "application/json" },
      body: JSON.stringify({
        quoteId: quote.quoteId,
        user: account.address,
        unwrapNativeOut: true,
      }),
    }).then((r) => r.json());

    // 4. Send
    const txHash = await walletClient.sendTransaction({
      to: submit.to as `0x${string}`,
      data: submit.data as `0x${string}`,
      value: BigInt(submit.value),
    });

    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
    console.log(`Confirmed in block ${receipt.blockNumber}`);
  }

  main().catch(console.error);
  ```
</Accordion>

## What's next

<CardGroup>
  <Card title="Two-step vs one-step" icon="code-branch" href="/api/dex-aggregator/guides/integration-patterns">
    When to use `/quote` + `/submit` vs `/execute`.
  </Card>

  <Card title="ERC-20 approvals" icon="lock-open" href="/api/dex-aggregator/guides/erc20-approvals">
    Approve patterns, including one-tx permit-enabled swaps.
  </Card>

  <Card title="Native ETH" icon="ethereum" href="/api/dex-aggregator/guides/native-eth">
    Sell ETH directly without wrapping, or receive ETH instead of WETH.
  </Card>

  <Card title="Quote freshness" icon="clock" href="/api/dex-aggregator/guides/quote-freshness">
    How to keep the displayed price live in your UI.
  </Card>
</CardGroup>


# Changelog
Source: https://docs.o1.exchange/api/dex-aggregator/reference/changelog

Notable API changes for the DEX Aggregator API.

This page tracks user-visible changes to the DEX Aggregator API. Breaking changes are flagged explicitly.

## 2026-04-30 — Public docs published

* Initial public documentation for the DEX Aggregator API at `docs.o1.exchange/api/dex-aggregator`.
* Endpoints: `/quote`, `/submit`, `/execute`, `/health`.
* Live on Base mainnet (chain ID `8453`).
* Default rate limit: 120 requests / minute / API key.
* Router contract: [`0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3`](https://basescan.org/address/0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3).

## Versioning policy

The API does not use a versioned URL prefix today. We treat published behavior as stable and add fields additively whenever possible. Breaking changes will be:

1. Pre-announced here at least two weeks before deployment.
2. Mirrored at a versioned path (`/v1/quote`, `/v2/quote`) for the duration of the migration window.
3. Documented with a migration note describing the old and new shapes.

## What "breaking" means

* Removing or renaming a field on a response.
* Changing the type or units of an existing field.
* Tightening a validation rule that previously accepted a value.
* Removing or renaming an endpoint.

Adding new optional request fields, new optional response fields, or new endpoints is **not** breaking.

## Subscribing to updates

If you'd like change notifications, contact the o1 team to be added to an integrator mailing list. The changelog page here is the canonical record either way.


# Rate limits
Source: https://docs.o1.exchange/api/dex-aggregator/reference/rate-limits

How the per-key rate limit works, what to do when you hit it, and how to request a higher quota.

The DEX Aggregator API enforces a per-key sliding-window rate limit. The default is **120 requests per minute per API key**.

## How it works

<CardGroup>
  <Card title="Per-key" icon="key">
    The window is keyed off the `x-api-key` header, not your IP. Each key gets its own bucket.
  </Card>

  <Card title="Sliding 60-second window" icon="clock-rotate-left">
    Hits are tracked with timestamps. The window is `now − 60s..now`. There's no hard reset on the minute boundary; the oldest hits drop off as time passes.
  </Card>
</CardGroup>

## What counts as a request

Every authenticated call counts:

* `POST /quote`
* `POST /submit`
* `POST /execute`

`GET /health` is public and free.

## What you get on overflow

```http theme={null} theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
```

```json theme={null} theme={null}
{
  "error": "rate limit exceeded",
  "limit": 120,
  "windowSec": 60
}
```

## Recommended retry

```ts theme={null} theme={null}
async function fetchWithBackoff(req: () => Promise<Response>, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await req();
    if (res.status !== 429) return res;

    if (attempt === maxAttempts) return res;

    // Linear backoff with jitter is fine here. Don't go below 1 second.
    const delay = 1000 + Math.random() * 500;
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error("unreachable");
}
```

<Warning>
  Don't retry immediately on `429`. The window is sliding, so a fast retry just lands at the same spot in the bucket. Wait at least 1 second.
</Warning>

## Capacity planning

A few guidelines for sizing your usage:

| Workload                                                           | Approximate rate   | Headroom                                |
| ------------------------------------------------------------------ | ------------------ | --------------------------------------- |
| Single-user swap UI with live quote polling (one user, 8s polling) | \~7 req/min        | Plenty                                  |
| 10 concurrent users polling                                        | \~75 req/min       | Comfortable                             |
| 50 concurrent users polling                                        | \~375 req/min      | Exceeds default — request a higher tier |
| Server-side bot quoting once per second per pair                   | 60 req/min × pairs | Scales linearly                         |

If you expect sustained load above the default 120 req/min, contact the o1 team to discuss a higher tier.

## Per-pair caching tips

You can dramatically reduce request count on the client by:

1. **Debouncing user input.** Don't quote on every keystroke; quote 300ms after the last input.
2. **Coalescing identical quotes.** If two components need the same `(tokenIn, tokenOut, amountIn)` quote, share one fetch.
3. **Pausing polling when the tab is hidden.** Use `document.visibilityState === "hidden"` to skip ticks.

## What does NOT scale your quota

* Adding more API keys for the same product. The o1 team can detect related keys and apply combined limits if abuse is suspected.
* Spreading requests across IPs while reusing one key. The limit is keyed on the key, not the IP.

If you legitimately need more headroom, ask. The defaults exist to protect upstream RPC and pool-data providers, and higher tiers are available.


# RoutePlan schema
Source: https://docs.o1.exchange/api/dex-aggregator/reference/route-plan

Every field in the routePlan object returned by /quote and /execute.

The `routePlan` object is returned on every successful `/quote` and `/execute` call. It's the canonical description of what the swap will do, broken down by route and leg.

You don't need to construct a `RoutePlan` yourself. The API generates it; this page is for callers who want to display its contents in detail or audit a swap before signing.

## Top-level shape

```json theme={null} theme={null}
{
  "chainId": 8453,
  "tokenIn": "0x...",
  "tokenOut": "0x...",
  "amountIn": "1000000000",
  "expectedAmountOut": "484446072048780734",
  "minAmountOut": "479601611328292926",
  "slippageBps": 100,
  "feeBps": 30,
  "blockNumber": 44266656,
  "gasEstimate": { "gasUnits": 300000, "gasCostWei": "..." },
  "feeBreakdown": {
    "protocolFeeAmount": "...",
    "integratorFeeAmount": "..."
  },
  "routes": [ /* SplitRoute[] */ ],
  "metadata": { /* RouteMetadata */ },
  "nativeIn": false,
  "nativeOut": false
}
```

| Field               | Type    | Description                                                                                                                  |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `chainId`           | integer | EVM chain ID. `8453` for Base.                                                                                               |
| `tokenIn`           | address | Echo of the request `tokenIn`.                                                                                               |
| `tokenOut`          | address | Echo of the request `tokenOut`.                                                                                              |
| `amountIn`          | string  | Echo of the request `amountIn`, in wei.                                                                                      |
| `expectedAmountOut` | string  | The output amount the optimizer believes you'll receive, in wei.                                                             |
| `minAmountOut`      | string  | The on-chain enforced minimum after slippage.                                                                                |
| `slippageBps`       | integer | Slippage tolerance in bps. Same value as the request.                                                                        |
| `feeBps`            | integer | Total fee in bps (protocol + optional integrator).                                                                           |
| `blockNumber`       | integer | Block at which the routing engine snapshotted pool state.                                                                    |
| `gasEstimate`       | object  | Estimated gas usage. See [gasEstimate](#gasestimate).                                                                        |
| `feeBreakdown`      | object  | Fee split between protocol and integrator. See [feeBreakdown](#feebreakdown).                                                |
| `routes`            | array   | One or more `SplitRoute` objects. See [Routes](#routes).                                                                     |
| `metadata`          | object  | Optimizer telemetry. See [metadata](#metadata).                                                                              |
| `nativeIn`          | boolean | `true` when the request used the native sentinel for `tokenIn`. The submit handler must set `useNativeIn: true` accordingly. |
| `nativeOut`         | boolean | `true` when the request used the native sentinel for `tokenOut`. Mirrors of `nativeIn`.                                      |

## `gasEstimate`

```json theme={null} theme={null}
{ "gasUnits": 300000, "gasCostWei": "12000000000000000" }
```

| Field        | Type    | Description                                                                                                                                      |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `gasUnits`   | integer | Estimated gas units the swap will consume.                                                                                                       |
| `gasCostWei` | string  | (Optional) Estimated gas cost in wei at the snapshotted base fee. Display only; the transaction is priced by the user's wallet, not this number. |

## `feeBreakdown`

```json theme={null} theme={null}
{
  "protocolFeeAmount": "1457804507741243911",
  "integratorFeeAmount": "0"
}
```

| Field                 | Type   | Description                                                                      |
| --------------------- | ------ | -------------------------------------------------------------------------------- |
| `protocolFeeAmount`   | string | Protocol fee taken out of `expectedAmountOut`, in `tokenOut` base units.         |
| `integratorFeeAmount` | string | Integrator fee (when you set `feeBps` on the request), in `tokenOut` base units. |

## Routes

`routes[]` is an array of `SplitRoute`. Each route is one path through the venue graph. When the optimizer splits a trade, you'll see multiple entries with the input divided across them.

```json theme={null} theme={null}
{
  "amountIn": "600000000",
  "legs": [ /* RouteLeg[] */ ]
}
```

| Field      | Type   | Description                                                 |
| ---------- | ------ | ----------------------------------------------------------- |
| `amountIn` | string | Portion of the total `amountIn` allocated to this route.    |
| `legs`     | array  | 1 to 3 hops. Each `leg` swaps one pair on a specific venue. |

### `RouteLeg`

```json theme={null} theme={null}
{
  "dex": "UNIV3",
  "tokenIn": "0x...",
  "tokenOut": "0x...",
  "amountIn": "600000000",
  "minOut": "0",
  "poolId": "0xd0b5...f224",
  "data": { "kind": "v3_direct", "pool": "0xd0b5...f224" }
}
```

| Field      | Type    | Description                                                                                                  |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `dex`      | `DexId` | Which venue the adapter dispatches to. See [Supported DEXes](/api/dex-aggregator/reference/supported-dexes). |
| `tokenIn`  | address | Input token for this leg.                                                                                    |
| `tokenOut` | address | Output token for this leg.                                                                                   |
| `amountIn` | string  | Input amount to this leg, in wei.                                                                            |
| `minOut`   | string  | Minimum output for this leg in isolation. May be `0` because the global `minAmountOut` is the binding check. |
| `poolId`   | string  | A human-friendly identifier for the pool, when applicable.                                                   |
| `data`     | object  | Tagged union with `kind` discriminator. Shape varies per venue. See below.                                   |

### `data` shapes (by `kind`)

The `data` object is a tagged union keyed by `kind`. The router's adapter for each venue knows how to consume the corresponding shape.

| `kind`              | Carries                          | Used for                                                          |
| ------------------- | -------------------------------- | ----------------------------------------------------------------- |
| `v2_direct`         | `pool`, `feeBps`                 | Single Uni V2 / Aerodrome V2-like / PancakeSwap V2 pool           |
| `v3_direct`         | `pool`                           | Single Uni V3 pool                                                |
| `pancake_v3_direct` | `pool`                           | Single PancakeSwap V3 pool                                        |
| `algebra_direct`    | `pool`                           | Algebra family pool (Hydrex, QuickSwap V4)                        |
| `hydrex`            | `deadline`                       | Hydrex multi-hop                                                  |
| `univ4`             | `commands`, `inputs`, `deadline` | Uniswap V4 universal-router payload                               |
| `curve`             | `pool`, `i`, `j`                 | Curve TwoCrypto-NG (or compatible)                                |
| `prop_amm`          | `router`, `protocol`             | Proprietary AMMs (PropSwap, Tessera, Elfomofi, LunarBase, Feltir) |
| `dodo_v2`           | `pool`, `baseToken`              | DODO V2                                                           |
| `woofi`             | `router`                         | WooFi                                                             |
| `univ2`             | `path`, `deadline`               | Multi-hop V2 fallback                                             |
| `univ3`             | `path`, `deadline`               | Multi-hop V3 path-encoded fallback                                |
| `aerodrome_v2`      | `routes`, `deadline`             | Aerodrome multi-hop with stable/volatile flags                    |

These details exist mainly for debugging and auditing. Application code rarely needs to inspect them.

## `metadata`

Optimizer telemetry. Useful for displaying a "tried N paths, picked M" indicator in dev tools or analytics.

```json theme={null} theme={null}
{
  "candidatePaths": 16,
  "selectedPaths": 1,
  "connectorsConsidered": [
    "0xcbb7...3bf",
    "0x9401...631"
  ],
  "candidates": [ /* RouteCandidateMetadata[] */ ]
}
```

| Field                  | Type             | Description                                                                                 |
| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
| `candidatePaths`       | integer          | Number of token paths the optimizer considered.                                             |
| `selectedPaths`        | integer          | How many of those are in the final plan.                                                    |
| `connectorsConsidered` | array of address | Intermediate tokens the optimizer hopped through.                                           |
| `candidates`           | array            | (Optional) Per-candidate scoring detail. Useful for debugging "why did it pick that route?" |

<Tip>
  In production UIs, the only fields most apps need from `routePlan` are `expectedAmountOut`, `minAmountOut`, `feeBps`, `gasEstimate.gasUnits`, and the list of `dex` names from `routes[].legs[]`. Treat the rest as advanced.
</Tip>


# Router contract
Source: https://docs.o1.exchange/api/dex-aggregator/reference/router-contract

The on-chain entrypoint that executes every aggregator swap.

Every transaction the API produces calls the same canonical router contract on Base.

<Card title="O1Router on Base" icon="cube">
  * **Address:** [`0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3`](https://basescan.org/address/0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3)
  * **Chain ID:** `8453`
  * **Source:** [`contracts/src/O1Router.sol`](https://github.com/o1exchange/o1-dex-agg/blob/main/contracts/src/O1Router.sol)
</Card>

<Note>
  This is the only address you should ever approve as a spender for swaps via this API. If a `/submit` response returns a different `to` address, **abort and report it**.
</Note>

## What it does

The `O1Router` is a thin orchestrator that:

1. Pulls `tokenIn` from the user (via `transferFrom` or, if a `permit` is supplied, via `permit + transferFrom` in the same tx).
2. Optionally wraps `msg.value` to WETH when `useNativeIn` is set.
3. Dispatches each route leg to the corresponding venue adapter (Uniswap V2/V3/V4, Aerodrome, Pancake, Curve, DODO, WooFi, Hydrex, etc.).
4. Aggregates outputs from all routes.
5. Optionally unwraps WETH to native ETH when `unwrapNativeOut` is set.
6. Sends final `tokenOut` to the user.
7. Reverts if `actualOutput < minAmountOut` (slippage check), per-leg or globally.

## Public function signature

```solidity theme={null} theme={null}
function swapExactIn(
    SwapParams calldata params
) external payable returns (uint256 amountOut);
```

Where `SwapParams` is constructed by the API; you don't need to encode it yourself. Just send `submit.data` as the `data` field of your transaction.

## Slippage and safety

The router enforces three layers of protection:

<CardGroup>
  <Card title="Per-leg minOut" icon="circle-check">
    Each leg has its own `minOut` checked by the corresponding adapter.
  </Card>

  <Card title="Global minAmountOut" icon="shield-check">
    The aggregate output is checked against `routePlan.minAmountOut`. The whole tx reverts if it's lower.
  </Card>

  <Card title="Permit deadline" icon="clock">
    If a `permit` payload is supplied, the EIP-712 deadline is enforced before the swap proceeds.
  </Card>
</CardGroup>

## Native wrapping

The router uses a configured wrapped-native token address. On Base that's WETH at `0x4200000000000000000000000000000000000006`.

* `useNativeIn: true` → router calls `WETH.deposit{value: msg.value}()` before dispatching legs.
* `unwrapNativeOut: true` → router calls `WETH.withdraw(amount)` after legs settle, then forwards ETH to the user.

You don't need to interact with WETH directly.

## Verifying on-chain

Before integrating, verify the deployment:

```bash theme={null} theme={null}
# Check that the bytecode at the address is non-empty
cast code 0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3 --rpc-url https://mainnet.base.org
```

Or just open it on [Basescan](https://basescan.org/address/0x8Dc736C6BA12e1Df1c73DB6BED8d7573F0aD90B3) and confirm:

* Contract is verified.
* Source matches `contracts/src/O1Router.sol` in the public repo.
* Constructor args set `WETH`, the fee recipient, and the venue adapter allowlist.

<Warning>
  Do not derive the router address from the API response without sanity checking it against this hardcoded value. Production integrations should hardcode the address and treat any mismatch in `submit.to` as fatal.
</Warning>


# Supported DEXes
Source: https://docs.o1.exchange/api/dex-aggregator/reference/supported-dexes

Every venue the routing engine can quote and dispatch to on Base.

The router can dispatch legs to the venues below. The `DexId` value appears in `routePlan.routes[].legs[].dex` on every quote response, and you can pass any subset of these in the optional `allowedDexes` field on `/quote` and `/execute` to restrict routing.

## Constant-product (V2-style)

Single-hop direct-pool swaps via the V2 product formula `x × y = k`.

| `DexId`            | Protocol                 | Notes                                        |
| ------------------ | ------------------------ | -------------------------------------------- |
| `UNIV2`            | Uniswap V2               | Multi-hop fallback also uses this kind.      |
| `AERODROME_V2LIKE` | Aerodrome volatile pools | The V2-style side of Aerodrome (non-stable). |
| `PANCAKE_V2`       | PancakeSwap V2           |                                              |

## Concentrated liquidity (V3-style)

Tick-aware pool math.

| `DexId`               | Protocol                                    | Notes                                                            |
| --------------------- | ------------------------------------------- | ---------------------------------------------------------------- |
| `UNIV3`               | Uniswap V3                                  | Direct-pool dispatch for single hop, path-encoded for multi-hop. |
| `PANCAKE_V3`          | PancakeSwap V3                              |                                                                  |
| `PANCAKE_INFINITY_CL` | PancakeSwap Infinity Concentrated Liquidity |                                                                  |
| `ALIEN_BASE_V3`       | AlienBase V3                                |                                                                  |
| `HYDREX`              | Hydrex                                      | Algebra Integral family.                                         |
| `QUICKSWAP_V4`        | QuickSwap V4                                | Algebra Integral family.                                         |

## Universal router (V4-style)

Uniswap V4 is dispatched through the universal-router commands ABI.

| `DexId` | Protocol   | Notes                                                          |
| ------- | ---------- | -------------------------------------------------------------- |
| `UNIV4` | Uniswap V4 | Carries an opaque `commands` byte string and `inputs[]` array. |

## Stable and curve-style

| `DexId`        | Protocol                             | Notes                      |
| -------------- | ------------------------------------ | -------------------------- |
| `AERODROME_CL` | Aerodrome Concentrated Liquidity     | Stable side of Aerodrome.  |
| `CURVE`        | Curve TwoCrypto-NG (and compatibles) | Pool-indexed by `i` / `j`. |

## Proprietary on-chain AMMs

These are direct integrations with project-specific AMMs on Base. All dispatch through a router contract per protocol.

| `DexId`     | Protocol  |
| ----------- | --------- |
| `PROPSWAP`  | PropSwap  |
| `TESSERA`   | Tessera   |
| `ELFOMOFI`  | Elfomofi  |
| `LUNARBASE` | LunarBase |
| `FELTIR`    | Feltir    |

## Other on-chain venues

| `DexId`          | Protocol       | Notes                                         |
| ---------------- | -------------- | --------------------------------------------- |
| `DODO_V2`        | DODO V2        | Carries `pool` and `baseToken` for direction. |
| `WOOFI`          | WooFi          | Routed through the WooFi router contract.     |
| `GYROSCOPE_ECLP` | Gyroscope ECLP | Elliptic concentrated liquidity.              |
| `MAVERICK_V2`    | Maverick V2    |                                               |

## Restricting routing

If you want to limit which venues the optimizer considers (e.g. for a benchmarking experiment, or to avoid a specific protocol), pass `allowedDexes` on `/quote` or `/execute`:

```json theme={null} theme={null}
{
  "chainId": 8453,
  "tokenIn": "0x...",
  "tokenOut": "0x...",
  "amountIn": "1000000000",
  "slippageBps": 100,
  "allowedDexes": ["UNIV3", "AERODROME_CL", "PANCAKE_V3"]
}
```

<Warning>
  Restricting `allowedDexes` reduces routing flexibility. Expect worse `expectedAmountOut` than an unrestricted quote. Use only when you have a clear reason.
</Warning>

## What's NOT supported

Off-chain professional market makers (PMMs) used by some upstream aggregators are **not** in this list.

Bridges, cross-chain venues, and limit-order books are also out of scope; this aggregator is same-chain spot routing on Base.


# Trading API
Source: https://docs.o1.exchange/api/trading

Execute trades programmatically with MEV protection, Permit2 support, and automatic slippage handling

## Overview

The o1.exchange Trading API enables programmatic trading with enterprise-grade features including built-in MEV protection, Permit2 support for gasless approvals, and automatic slippage handling.

<Card title="Key Benefits" icon="star">
  * **MEV Protection**: Private mempool routing to prevent sandwich attacks
  * **Gasless Approvals**: One-time Permit2 signatures for unlimited trading
  * **Automatic Slippage**: Built-in slippage protection with customizable limits
</Card>

## Prerequisites

<CardGroup>
  <Card title="Wallet" icon="wallet">
    Ethereum wallet with private key
  </Card>

  <Card title="Gas Fees" icon="coins">
    ETH for transaction costs
  </Card>

  <Card title="Runtime" icon="code">
    Node.js environment
  </Card>
</CardGroup>

## Quick Start

### 1. Generate API Key

<Steps>
  <Step title="Navigate to API Trading">
    Visit [https://o1.exchange/api-trading](https://o1.exchange/api-trading)
  </Step>

  <Step title="Create API Key">
    Generate your secure API token for authentication
  </Step>
</Steps>

### 2. Create Transaction Batch

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST https://api.o1.exchange/api/v2/order`

    **Headers:**

    ```json theme={null}
    {
      "Authorization": "Bearer <YOUR_API_TOKEN>",
      "Content-Type": "application/json"
    }
    ```

    **Body:**

    ```json theme={null}
    {
      "networkId": 8453, // Network ID (8453 = Base, 56 = BSC, 1399811149 = Solana)
      "signerAddress": "0x...",  // Your wallet address
      "tokenAddress": "0x...",   // Token contract address
      "uiAmount": "1.0",         // Amount in human-readable format
      "direction": "buy",        // "buy" or "sell"
      "slippageBps": 300,        // Slippage in basis points (300 = 3%)
      "mevProtection": true,      // Enable MEV protection
      "quoteTokenAddress": "0x...", // (Optional) Quote token for stablecoin trades (Base only)
      "poolAddress": "0x..." // (Optional) Specific liquidity pool (Base, BSC)
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "success": true,
      "id": "batch_123...",
      "transactions": [
        {
          "id": "tx_456...",
          "unsigned": {
            "to": "0x...",
            "data": "0x...",
            "value": "0x...",
            "gasLimit": "0x...",
            "chainId": 1
          },
          "permit2": {
            "eip712": {
              "domain": {...},
              "types": {...},
              "values": {...}
            }
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

### 3. Sign Transaction and Permit2

<Accordion title="Implementation Details">
  For each transaction in the response:

  1. **Sign Permit2 (if present):**
     * Extract the EIP-712 typed data from `permit2.eip712`
     * Sign using wallet's `signTypedData` method
     * Replace the signature placeholder in transaction data

  2. **Sign the transaction:**
     * Create transaction object from the unsigned data
     * Sign using wallet's `signTransaction` method

  ```javascript theme={null}
  // Fixed signature placeholder - don't change
  const SIGNATURE_PLACEHOLDER =
    "42f68902113a2a579bcc207c91254c8516d921250e748c18a082d91d74908f8e9a05f27b72a030c6a42d77d0e0aab6fb09219b01a01e7b5b24e4f322ee1762ff1b";

  for (const ctx of data.transactions) {
    const unsignedTx = Transaction.from(ctx.unsigned);

    // Handle Permit2 signature if present
    if (ctx?.permit2?.eip712) {
      const { domain, types, values } = ctx.permit2.eip712;
      const signature = await wallet.signTypedData(domain, types, values);

      // Replace placeholder with actual signature
      let txData = unsignedTx.data;
      txData = txData.replace(SIGNATURE_PLACEHOLDER, signature.slice(2));
      unsignedTx.data = txData;
    }

    // Sign the transaction
    const signedTx = await wallet.signTransaction(unsignedTx);
  }
  ```
</Accordion>

### 4. Submit Transaction

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST https://api.o1.exchange/api/v2/order/complete`

    **Headers:**

    ```json theme={null}
    {
      "Authorization": "Bearer <YOUR_API_TOKEN>",
      "Content-Type": "application/json"
    }
    ```

    **Body:**

    ```json theme={null}
    {
      "id": "batch_123...",     // Batch ID from create response
      "transactions": [
        {
          "id": "tx_456...",     // Transaction ID
          "signed": "0x...",     // Signed transaction hex
          "permit2": {
            "eip712": {
              "signature": "0x..." // Permit2 signature
            }
          }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "success": true,
      "transactions": [
        {
          "hash": "0x...",        // Transaction hash
          "status": "pending",    // Transaction status
          "tokenDelta": "1000000" // Token balance change
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Sample Scripts & Examples

<Card title="Complete Sample Repository" icon="github">
  **GitHub Repository:** [https://github.com/CohumanSpace/o1-api](https://github.com/CohumanSpace/o1-api)

  This repository contains complete sample scripts for using the o1.exchange API, including:

  * Interactive CLI trading application
  * Complete integration examples
  * Proper error handling patterns
  * Environment setup guides
</Card>

## Interactive Example

<Card title="Complete CLI Trading App" icon="terminal">
  See `execute-trade-interactive.js` in the [sample repository](https://github.com/CohumanSpace/o1-api) for a fully functional CLI trading application that demonstrates all integration steps with proper error handling and user interaction.
</Card>

### Setup Environment

Create a `.env.local` file:

```env theme={null}
EXECUTE_TRADE_PRIVATE_KEY=<YOUR_PRIVATE_KEY>
EXECUTE_TRADE_API_TOKEN=<YOUR_API_TOKEN>
EXECUTE_TRADE_BASE_URL=<API_BASE_URL>
EXECUTE_TRADE_RPC_URL=<ETHEREUM_RPC_URL>
```

### Run Interactive CLI

```bash theme={null}
node execute-trade-interactive.js
```

<Steps>
  <Step title="Token Address">
    Enter token contract address (e.g., `0x06ca615ac72a18e76b63bd4b5c320b6c8e291f8b`)
  </Step>

  <Step title="Trade Direction">
    Choose `buy` or `sell`
  </Step>

  <Step title="Amount">
    Enter amount in ETH (for buy) or tokens (for sell)
  </Step>

  <Step title="Confirm">
    Review trade details and execute
  </Step>

  <Step title="Results">
    View balance changes after execution
  </Step>
</Steps>

## Advanced Features

<CardGroup>
  <Card title="Permit2 Integration" icon="signature">
    <p>**Gasless token approvals** using EIP-712 signatures</p>

    <ul>
      <li>Automatic signature placeholder replacement</li>
      <li>One-time approval for unlimited trading</li>
      <li>Reduced gas costs for frequent traders</li>
    </ul>
  </Card>

  <Card title="MEV Protection" icon="shield">
    <p>**Protection against sandwich attacks**</p>

    <ul>
      <li>Private mempool routing</li>
      <li>Reduced slippage from MEV bots</li>
      <li>Enable with `mevProtection: true`</li>
    </ul>
  </Card>
</CardGroup>

### Slippage Control

<Info>
  Specify `slippageBps` in basis points where **100 bps = 1%**

  **Recommendations:**

  * **Normal conditions:** 300 bps (3%)
  * **Volatile tokens:** 500-1000 bps (5-10%)
  * **Large trades:** Increase as needed
</Info>

## Error Handling

<Warning>
  Always implement proper error handling for:

  * Network connectivity issues
  * Insufficient balance or gas
  * Transaction reverts
  * API rate limiting
</Warning>

<Tip>
  The interactive example includes comprehensive error handling patterns you can reference for your own implementation.
</Tip>


# Bug Bounty Program
Source: https://docs.o1.exchange/community/bug-bounty

Help secure o1.exchange and earn rewards for finding vulnerabilities

## Protecting Our Community

At o1.exchange, security is our top priority. We've established a comprehensive bug bounty program to incentivize security researchers and developers to help identify vulnerabilities in our platform. Your contributions help us maintain the highest security standards for our users.

<CardGroup>
  <Card title="Report Vulnerabilities" icon="bug">
    Discover and report security issues to earn rewards
  </Card>

  <Card title="Earn Rewards" icon="coins">
    Get paid for valid security findings based on severity
  </Card>
</CardGroup>

## Reward Structure

<Tabs>
  <Tab title="Severity Levels">
    Rewards are determined based on the severity and impact of the vulnerability:

    | Severity   | Description                                  | Reward Range    |
    | ---------- | -------------------------------------------- | --------------- |
    | **High**   | loss of funds, significant impact            | $1,000 - $5,000 |
    | **Medium** | Limited impact, requires specific conditions | $500 - $1,000   |
    | **Low**    | Minimal impact, informational issues         | $100 - $500     |
  </Tab>

  <Tab title="Scope">
    ### In Scope

    * Smart contract vulnerabilities
    * Trading engine exploits
    * Authentication bypass
    * Fund manipulation
    * Oracle manipulation
    * Cross-site scripting (XSS)
    * SQL injection
    * Remote code execution

    ### Out of Scope

    * Known issues or already reported vulnerabilities
    * Social engineering attacks
    * Physical attacks
    * Denial of service attacks
    * Issues in third-party services
    * Generic product bugs, including but not limited to UI/UX, application clients, product stability, etc.
  </Tab>
</Tabs>

<Warning>
  * Attempting to exploit vulnerabilities on the mainnet or causing actual harm to users is strictly prohibited and may result in legal action.
  * No one should break nor exploit the mainnet (production o1.exchange site) without the admin/team's approval; otherwise it would lead to a smaller final payout.
</Warning>

## How to Participate

<Steps>
  <Step title="Discover">
    Review our smart contracts, trading platform, and infrastructure for potential vulnerabilities
  </Step>

  <Step title="Document">
    Create a detailed report including:

    * Clear description of the vulnerability
    * Steps to reproduce
    * Impact assessment
    * Suggested fix (if applicable)
    * Payments would be sent when attack and solution documentations are shared, given no follow-up attack within the next 1 month
  </Step>

  <Step title="Submit">
    Send your report to our X account @o1\_exchange via DM
  </Step>

  <Step title="Review">
    Our security team will review your submission within 48 hours
  </Step>

  <Step title="Reward">
    Upon validation, receive your bounty payment in USDC or ETH
  </Step>
</Steps>

## Recognition

<Note>
  Top contributors to our bug bounty program will be featured in our Security Hall of Fame and receive exclusive NFT badges recognizing their contributions to platform security.
</Note>

## Legal Safe Harbor

We commit to not pursuing legal action against security researchers who:

* Comply with this bug bounty policy
* Act in good faith
* Make a reasonable effort to avoid privacy violations
* Do not exploit vulnerabilities beyond what's necessary for verification

<Tip>
  Join our security-focused Discord channel to discuss potential findings with our team and other security researchers. Remember: collaboration makes our platform stronger!
</Tip>

## Contact

For questions about the bug bounty program or to submit a vulnerability report:

<Card title="Security Team" icon="envelope">
  **Twitter**: Send your report to our X account @o1\_exchange via DM.\
  **Response Time**: Within 48 hours.
</Card>


# Platform Metrics
Source: https://docs.o1.exchange/community/metrics



<Card title="Dune Analytics Dashboard" icon="chart-line" href="https://dune.com/o1_exchange/o1exchange-data/">
  View comprehensive platform metrics including trading volumes, active users, fee generation, and network distribution
</Card>

<Tip>
  Bookmark the Dune dashboard to stay updated on platform performance and trading trends. The data is particularly useful for understanding market dynamics and making informed trading decisions.
</Tip>


# Community & Socials
Source: https://docs.o1.exchange/community/socials



Connect with thousands of traders, developers, and DeFi enthusiasts in the o1.exchange community. Get real-time updates, trading insights, and direct support from our team.

<CardGroup>
  <Card title="Discord Server" icon="discord" href="https://discord.gg/o1exchange" />

  <Card title="Twitter/X" icon="x-twitter" href="https://x.com/o1_exchange" />

  <Card title="o1.exchange founder Twitter/X" icon="x-twitter" href="https://x.com/stambouli_o1" />

  <Card title="o1.exchange founder Zora" icon="x-twitter" href="https://zora.co/@yomanwhatsup" />
</CardGroup>

<Note>
  Our community is global and active 24/7. Whether you're a beginner or experienced trader, you'll find valuable insights and supportive community members ready to help you succeed.
</Note>


# Explore Tokens
Source: https://docs.o1.exchange/features/explore-tokens



o1.exchange provides comprehensive token exploration tools to help you discover new opportunities, research projects, and make informed trading decisions across multiple blockchain networks.

### Token Discovery Features

<CardGroup>
  <Card title="Trending Tokens" icon="chart-line-up">
    Discover the most popular and trending tokens based on trading volume and community interest
  </Card>

  <Card title="New Listings" icon="sparkles">
    Stay updated with newly listed tokens and early-stage opportunities
  </Card>

  <Card title="Top Gainers/Losers" icon="arrows-up-down">
    Track the best and worst performing tokens over various time periods
  </Card>

  <Card title="High Volume" icon="chart-bar">
    Find tokens with exceptional trading volume and liquidity
  </Card>
</CardGroup>

<div>
  <div>
    <h4>Explore Tokens in Pulse</h4>

    <img alt="Pulse page showing new token pairs" />

    <p>
      Use the <b>Pulse</b> page to discover new trading pairs that have been recently launched. This section highlights tokens that are gaining traction, allowing you to spot emerging opportunities early.
    </p>
  </div>

  <div>
    <h4>Filter Tokens by Your Criteria</h4>

    <img alt="Pulse page filter options" />

    <p>
      Apply advanced filters to narrow down tokens based on your selection criteria—such as trading volume, price change, liquidity, or launch time. This helps you focus on tokens that best match your investment or trading strategy.
    </p>
  </div>
</div>


# Onramp Fiat to Crypto
Source: https://docs.o1.exchange/features/onramp



o1.exchange provides integrated fiat onramp solutions powered by Coinbase, allowing you to convert traditional currencies (USD, EUR, etc.) directly into cryptocurrency without leaving the platform.

### Supported Payment Methods

<CardGroup>
  <Card title="Credit/Debit Cards" icon="credit-card">
    Instant purchases with major credit and debit cards
  </Card>

  <Card title="Bank Transfers" icon="building-columns">
    Lower fees with ACH and wire transfer options
  </Card>

  <Card title="Digital Wallets" icon="wallet">
    Support for Apple Pay, Google Pay, and other digital wallets
  </Card>
</CardGroup>

<div>
  <div>
    <h4>1. Input the amount of chain native token to purchase</h4>

    <img alt="Onramp process illustration" />
  </div>

  <div>
    <h4>2. Complete the purchase</h4>

    <img alt="Coinbase integration illustration" />
  </div>
</div>


# Portfolio
Source: https://docs.o1.exchange/features/portfolio

Comprehensive portfolio tracking and analytics

## Portfolio Overview

Easily track your entire crypto portfolio in one place. The portfolio dashboard provides a comprehensive summary of your assets, including real-time balances, performance stats, and detailed analytics.

<div>
  <img alt="Portfolio summary dashboard" />
</div>

### Multi-Wallet Analytics

You can view your portfolio analytics for:

* **All wallets combined** for a complete overview
* **Main wallet** or any **active wallet**
* **Custom wallet combinations**—select any set of wallets to analyze their aggregated balances, performance, and token distribution

<div>
  <div>
    <h4>1. Select Wallets to Analyze</h4>

    <img alt="Select wallets for analytics" />

    <p>
      Choose your main, active, or any combination of wallets to customize your analytics view.
    </p>
  </div>

  <div>
    <h4>2. View Aggregated Analytics</h4>

    <img alt="Aggregated analytics across wallets" />

    <p>
      Instantly see aggregated stats, token allocations, and performance metrics across your selected wallets.
    </p>
  </div>
</div>

<Note>
  The portfolio dashboard gives you full flexibility to analyze your holdings across any wallet or group of wallets, helping you make informed decisions with complete visibility.
</Note>


# Referrals & Rewards
Source: https://docs.o1.exchange/features/referrals-rewards

Earn rewards through referrals and trading activities

## Rewards & Referral Dashboard

Manage and track all your rewards and referral activities in one place. The dashboard provides a comprehensive overview of your trading and referral performance, including:

* **Trading Tier**: View your current trading tier and the benefits it unlocks.
* **Cashback Rate**: See your current cashback percentage based on your trading activity.
* **Cashback Rewards**: Track the total cashback you've earned.
* **Total Trading Volume (per chain)**: Monitor your trading volume across different supported blockchains.
* **Referral Rewards**: View the total rewards earned from referring others.
* **Total Referred Users**: See how many users have signed up using your referral code.
* **Referred Volume**: Track the trading volume generated by your referred users.
* **Cashback History**: Review a detailed history of your cashback rewards.
* **Reward History**: Access a log of all rewards earned through trading and referrals.
* **Multi-Tier Referrals**: Analyze your referred users across multiple tiers and their corresponding trading volumes.

<div>
  <img alt="Rewards and referral dashboard" />
</div>

***

## Set Your Referral Code

Personalize your referral code to make it easy to share with friends and track your referrals. Setting your code is simple:

<div>
  <img alt="Set referral code" />
</div>

1. Choose a unique referral code.
2. Save your code to activate it.
3. Share your code with friends to start earning rewards.

***

## Share and Earn Together

Invite friends to o1.exchange using your referral code. When they trade, you both benefit—your friends receive a portion of their trading commission back as cashback, and you earn referral rewards based on their activity.

<div>
  <img alt="Share referral code" />
</div>

* Share your code via social media, messaging apps, or directly.
* Track the rewards and cashback earned by you and your referred users in real time.
* Multi-tier referrals let you benefit from the activity of users referred by your direct referrals as well.

<Note>
  Set your referral code, share it, and start earning rewards together! All referral and cashback rewards are transparently tracked in your dashboard.
</Note>


# Trading
Source: https://docs.o1.exchange/features/trading

Advanced trading features and order types

## Trading Features

Unlock powerful trading tools designed for both beginners and advanced users. Our platform supports a variety of order types to help you execute your strategies with precision.

### 1. Spot Order

A spot order allows you to buy or sell tokens instantly at the current market price.

### 2. Limit Order

Set your desired price and let the system execute your trade when the market reaches your target.

### 3. Sniper Order

Sniper orders are designed for high-speed execution, letting you target specific liquidity events or new token launches.

### 4. TWAP (Time-Weighted Average Price)

TWAP orders help you minimize market impact by splitting your trade into smaller orders executed over a set period.

***

## How to Trade

Follow these simple steps to place a trade:

### 1. Review Token Details

<div>
  <img alt="Token Detail" />
</div>

Check the token's information, including price, liquidity, and recent activity, to make informed decisions.

### 2. Configure Your Wallet

<div>
  <img alt="Wallet Configuration" />
</div>

Select your active wallet for multi-wallet trading.

### 3. Place Your Trade

<div>
  <img alt="Place Trade" />
</div>

Choose your order type (Spot, Limit, Sniper, or TWAP), enter the trade details, and confirm your transaction.

***

<Note>
  Advanced trading features are continuously being improved. Stay tuned for updates and new order types!
</Note>


# Wallets
Source: https://docs.o1.exchange/features/wallets

Secure wallet integration and management

## Wallet Management Features

Manage your wallets seamlessly within o1.exchange. Our platform provides a robust set of tools for creating, importing, exporting, and organizing your wallets—all under your single o1.exchange account.

### 1. Create New Wallets

Easily generate new wallets directly from your o1.exchange dashboard. Each wallet is securely managed and linked to your account, allowing you to organize multiple wallets for different purposes or strategies.

### 2. Import Existing Wallets

Bring your existing wallets into o1.exchange by importing them using your secret key. All imported wallets are managed in a non-custodial manner, ensuring you retain full control and ownership.

### 3. Export Wallets with Recovery Phrase

Export all your wallets at once using a single 12-word recovery phrase. This allows you to back up and restore up to 100 wallets simultaneously, making wallet management and migration simple and efficient.

### 4. Individual Wallet Actions

For each wallet, you can:

* **Archive**: Move wallets you no longer use to an archived state.
* **Set as Main Wallet**: Designate any wallet as your primary wallet for transactions.
* **Export Private Key**: Access and export the private key for any wallet when needed.
* **Set Active/Inactive**: Toggle wallets between active and inactive status to keep your dashboard organized.

<CardGroup>
  <Card title="Create & Import Wallets" icon="plus-circle">
    Generate new wallets or import existing ones using your secret key. All wallets are managed securely and non-custodially.
  </Card>

  <Card title="Export & Organize" icon="download">
    Export up to 100 wallets at once with a single 12-word recovery phrase. Archive, set main, or export private keys for any wallet.
  </Card>
</CardGroup>

## Split & Consolidate Tokens

Easily manage your assets by splitting or consolidating tokens directly from the wallets page. This feature allows you to move tokens between your wallets for better organization or strategy execution.

<div>
  <div>
    <h4>1. View and Select Wallets</h4>

    <img alt="Wallets overview" />

    <p>
      Access all your wallets in one place. Select the wallet you want to split tokens from or consolidate tokens into.
    </p>
  </div>

  <div>
    <h4>2. Initiate Token Transfer</h4>

    <img alt="Initiate token transfer" />

    <p>
      Choose the "Transfer" option to move tokens between your wallets. Specify the amount and the destination wallet to split or consolidate your holdings.
    </p>
  </div>

  <div>
    <h4>3. Confirm and Complete</h4>

    <img alt="Confirm token transfer" />

    <p>
      Review the details and confirm the transfer. Your tokens will be moved instantly, allowing you to efficiently manage your portfolio across multiple wallets.
    </p>
  </div>
</div>

<Note>
  Wallets on o1.exchange are managed in a non-custodial way, giving you full control and flexibility. You can organize, back up, and manage multiple wallets with ease.
</Note>


# Trading Fees
Source: https://docs.o1.exchange/getting-started/fees

The more you trade, the more you earn back!

## Fees

### Cashback Program

Our universal cashback program applies across all markets - spot, prediction markets, and future markets. You level up as you trade more, earning greater cashbacks that reduce your effective trading fees.

#### Tier 1

* Cashback: 0.2%
* Net Fee Reduction: 0.20%

#### Tier 2

* Cashback: 0.25%
* Net Fee Reduction: 0.25%

#### Tier 3

* Cashback: 0.30%
* Net Fee Reduction: 0.30%

#### Tier 4

* Cashback: 0.35%
* Net Fee Reduction: 0.35%

#### Tier 5

* Cashback: 0.40%
* Net Fee Reduction: 0.40%

The cashback is applied to your base trading fee, regardless of the market type you're trading in.

### Spot Market

**Base Fee:** 1.00%

With our cashback program, your effective trading fees for spot markets are:

* **Tier 1:** 0.80% (1.00% - 0.20% cashback)
* **Tier 2:** 0.75% (1.00% - 0.25% cashback)
* **Tier 3:** 0.70% (1.00% - 0.30% cashback)
* **Tier 4:** 0.65% (1.00% - 0.35% cashback)
* **Tier 5:** 0.60% (1.00% - 0.40% cashback)

### Prediction Market

For prediction market trades, we use a dynamic fee structure based on market conditions:

**Base Fee Formula:** `Fee = round_up(0.07 × C × P × (1 - P))`

Where:

* **C** is the amount of shares being traded
* **P** is the current probability (price) of the outcome, expressed as a decimal between 0 and 1
* The result is rounded up to the nearest unit

**Note:** Cashback from our tier program applies to the calculated fee, reducing your effective trading costs.

#### How it Works

The fee calculation automatically adjusts based on:

1. **Trade Size (C):** Larger trades incur proportionally higher fees
2. **Market Probability (P):** The fee changes based on how certain the market is about an outcome
3. **Volatility Factor (P × (1 - P)):** This reaches maximum when P = 0.5 (50% probability), meaning the market is most uncertain

#### Base Fee Examples (Before Cashback)

* When **P = 0.5** (50% probability): Maximum fee = `0.07 × C × 0.25 = 0.0175 × C`
* When **P = 0.1** (10% probability): Fee = `0.07 × C × 0.09 = 0.0063 × C`
* When **P = 0.9** (90% probability): Fee = `0.07 × C × 0.09 = 0.0063 × C`
* When **P = 0.01 or 0.99** (extreme probabilities): Minimum fee = `0.07 × C × 0.0099 ≈ 0.000693 × C`

This dynamic fee structure ensures:

* **Fair pricing** based on market uncertainty
* **Lower fees** when outcomes are more certain (very high or very low probabilities)
* **Balanced liquidity provision** across all probability levels
* **Additional savings** through our universal cashback program

### Perpetuals (Perps)

We integrate with Hyperliquid Build Code to provide perpetual futures trading. Our platform charges the industry's lowest builder fee of **0.010%** for perpetual trades.

**Builder Fee:** 0.010%

This ultra-low builder fee provides exceptional value for perpetual futures traders.


# Points System Season 1.1
Source: https://docs.o1.exchange/getting-started/points-system-season1

Points system rewards active traders and contributors to the o1.exchange community

<Note>
  **Points System Season 1.1** - Active since August 19, 2025, until January 19, 2026, 00:00:00 UTC (Monday). See [Points System Season 2](/getting-started/points-system-season2) for the new competitive weekly leaderboard system.
</Note>

## Points Overview

o1.exchange features a comprehensive rewards system that recognizes and incentivizes various trading activities and community contributions. Earn points through trading, referrals, and early adoption across multiple trading seasons.

<CardGroup>
  <Card title="Trading Points" icon="chart-line">
    Earn points based on your trading volume across all supported networks
  </Card>

  <Card title="Referral Points" icon="users">
    Gain points from the trading activity of users in your referral network
  </Card>

  <Card title="Season Rewards" icon="calendar-star">
    Special bonus points and badges available during trading seasons
  </Card>
</CardGroup>

## Trading Seasons

Explore the different trading seasons and their unique reward structures:

<Cards>
  <Card title="Season 1.1.1: OG Trader" icon="medal" href="/features/rewards/season-1">
    Early beta rewards program with exclusive OG Trader badges and bonus points for early participants (May - September 2025)
  </Card>

  <Card title="Season 1.1.2: Base Season" icon="coins" href="/features/rewards/season-2">
    Foundation season with enhanced trading rewards and expanded network support (Details coming soon)
  </Card>
</Cards>

## Trading Volume Points

Earn points for every trade you execute on the platform.

<Tabs>
  <Tab title="How It Works">
    * **Multi-Network Support**: Points aggregate across Solana, Base, and all supported networks
    * **Token-Specific Rates**: Different tokens may have different point multipliers
    * **Default Rate**: 50 points per 1 SOL traded (or equivalent)
    * **Formula**: `trade_volume × points_rate`
  </Tab>

  <Tab title="Example">
    If you trade 10 SOL worth of tokens:

    * Base points: 10 × 50 = **500 points**
    * Additional multipliers may apply based on specific token configurations
  </Tab>
</Tabs>

## Multi-Level Referral Points

Earn points from the trading activity of users in your referral network, up to 4 levels deep. [Learn more about rewards & point structure →](/features/referral-system)

### Referral Points Structure

* Each level has different point rates
* Rates are configurable per network and token
* Points accumulate from all levels simultaneously

## Additional Point Sources

<CardGroup>
  <Card title="Invite Points" icon="user-plus">
    **200 points** for each direct invite who joins the platform
  </Card>

  <Card title="Special Events" icon="calendar-star">
    Bonus points during promotional periods and campaigns
  </Card>
</CardGroup>

<Warning>
  <b>Update (Aug 27, 2025):</b> Transaction Points are <b>no longer awarded</b> for each transaction. Points are now earned <b>only based on trading volume</b> to prevent abuse and ensure fair rewards. Please focus on increasing your trading volume to maximize your points.
</Warning>

## Total Points Calculation

Your total points are calculated by aggregating:

1. **OG Trader Bonus** (if eligible)
2. **Trading Volume Points** across all networks
3. **Referral Points** from all 4 levels
4. **Invite Points** for direct referrals
5. **Transaction Points** for activity

<Note>
  All calculations use high-precision decimal arithmetic to ensure accuracy in point distribution.
</Note>


# Points System Season 1.2
Source: https://docs.o1.exchange/getting-started/points-system-season2

Competitive weekly leaderboard mechanism distributing predetermined point pools based on trading volume

## Overview

The Points System Season 1.2 is a competitive weekly leaderboard mechanism that distributes a predetermined pool of points to users based on their proportional trading volume. Unlike traditional transaction-based point systems, Season 1.2 allocates a fixed amount of points each week that users compete for based on their share of the total weekly trading volume.

## System Architecture

### Phase-Based Point Allocation

Points System Season 1.2 launches with Phase 1, offering the highest weekly point rewards:

| Phase   | Weeks | Points Per Week | Total Points |
| ------- | ----- | --------------- | ------------ |
| Phase 1 | 1-20  | 2,000,000       | 40,000,000   |
| Phase 2 | 21    | 2,000,000       | 2,000,000    |

**Phase 1:** Distributes 40,000,000 points over weeks 1–20.\
**Phase 2:** Distributes 2,000,000 points over the week 21.

### Epoch System

* **Start Date:** January 19, 2026, 00:00:00 UTC (Monday)
* **End Date:** June 15, 2026, 00:00:00 UTC (Monday)
* **Duration:** Exactly 7 days per epoch
* **Reset:** Weekly at the same time
* **Current Implementation:** Week-based epochs with precise timestamp boundaries

## Point Distribution Mechanism

### Volume Share Calculation

Points are distributed to all users each week in proportion to their trading volume. The weekly point pool is shared among all users who have trading volume, with each user receiving points based on their percentage of the total weekly volume.

<Note>
  **All users are rewarded:** Every user with trading volume receives points proportional to their share of the week's total volume. The leaderboard shows the top 30 users for the current week, but all participating users earn points.
</Note>

### Trading Volume Calculation

**Supported Fee Currencies:**

* **Native Tokens:** SOL, ETH (converted from smallest units)
* **USDC:** Direct USD value (handles both atomic units and human-readable format)
* **Quote tokens**: ZORA, etc.

### Price Conversion

For non-USD transactions, the system uses cached major token prices to convert to USD equivalent:

* Real-time price feeds from majorTokenV2 table
* Network-specific price mappings
* Fallback handling for price discovery failures

**Leaderboard Table:**

* Top 30 users by trading volume
* Rank badges for top 3 positions (Gold/Silver/Bronze) - these are visual recognition only and do not provide additional points
* Wallet addresses (truncated for privacy)
* USD trading volume
* Points allocated

### Real-Time Features

* **Live Updates:** Query-based real-time data refresh
* **Countdown Timer:** Precise remaining time until epoch reset
* **Progress Tracking:** Personal performance metrics
* **Competition Status:** Clear ranking and reward information

This system creates a competitive yet fair environment where users compete weekly for their share of predetermined point pools, with rewards directly proportional to their trading activity and contribution to platform volume.


# Referral System
Source: https://docs.o1.exchange/getting-started/referral-system

Earn rewards through our 4-tier referral program

<img alt="Referral System" />

## Multi-Tier Referral Program

o1.exchange offers a powerful 4-tier referral system that rewards you for bringing new traders to the platform. Earn a percentage of trading fees from not only your direct referrals but also from their referrals up to 4 levels deep.

<CardGroup>
  <Card title="Generate Your Link" icon="link">
    Create your unique referral link from your account dashboard
  </Card>

  <Card title="Share Widely" icon="share-nodes">
    Share your link with friends, on social media, or in trading communities
  </Card>
</CardGroup>

## Referral Reward Structure

<Note>
  **April 10, 2026 Update:** o1.exchange revamped its cashback and referral system to discourage self-referral and encourage the use of official o1.exchange KOL/partner referral links.
</Note>

### Cashback Rules (from April 10, 2026)

<CardGroup>
  <Card title="Partner Referral Link" icon="star">
    Users who sign up with an o1.exchange **KOL/partner referral link** receive **45% cashback** ready to go from day one.
  </Card>

  <Card title="Regular Referral Link" icon="link">
    Users who sign up with a **regular referral link** receive **20% cashback**, with the ability to upgrade to higher cashback tiers as their trading volume grows.
  </Card>
</CardGroup>

### Reward Tiers (before April 10, 2026)

<Tabs>
  <Tab title="Reward Tiers">
    Our industry-leading 4-tier referral system offered some of the most competitive rates in DeFi:

    | Tier | Relationship              | Reward (% of Trading Fees) |
    | ---- | ------------------------- | -------------------------- |
    | 1    | Direct referrals          | **35%**                    |
    | 2    | Your referrals' referrals | **3%**                     |
    | 3    | Third-level referrals     | **2%**                     |
    | 4    | Fourth-level referrals    | **1%**                     |
  </Tab>

  <Tab title="Example Earnings">
    If your network generated \$10,000 in trading fees:

    * **Tier 1 (35%)**: \$3,500 from direct referrals
    * **Tier 2 (3%)**: \$300 from second-level referrals
    * **Tier 3-4**: Additional earnings from your extended network
  </Tab>
</Tabs>

<Note>
  All referral rewards are automatically credited to your account in real-time as your network trades on the platform.
</Note>

## Maximizing Your Referral Income

<AccordionGroup>
  <Accordion title="Build a Strategic Network" icon="users">
    Focus on referring active traders who trade frequently and in high volumes to maximize your tier 1 rewards.
  </Accordion>

  <Accordion title="Educate Your Referrals" icon="graduation-cap">
    Help your direct referrals understand the benefits of referring others, which can increase your tier 2-4 rewards.
  </Accordion>

  <Accordion title="Leverage Community Platforms" icon="bullhorn">
    Share your referral link in trading communities, Discord servers, and social media groups where potential traders gather.
  </Accordion>
</AccordionGroup>

<Tip>
  The power of compound networking means that even a small network of active traders can generate significant passive income through our 4-tier system.
</Tip>

## Getting Started

<Steps>
  <Step title="Log in to your account">
    Access your o1.exchange dashboard using your credentials
  </Step>

  <Step title="Navigate to Referrals">
    Find the "Referrals" section in your user dashboard
  </Step>

  <Step title="Generate your link">
    Create your unique referral link with one click
  </Step>

  <Step title="Share and earn">
    Distribute your link and watch your rewards grow in real-time
  </Step>
</Steps>


# Trading Season 1: Early Beta
Source: https://docs.o1.exchange/getting-started/rewards/season-1

OG Trader rewards during early Beta period

## OG Trader Program

Trading Season 1 recognizes early adopters who participated in the o1.exchange beta period. This exclusive program rewards traders who helped shape the platform during its initial launch.

### Eligibility Period

<CardGroup>
  <Card title="Start Date" icon="calendar-plus">
    **May 17, 2025** - First day of eligibility
  </Card>

  <Card title="End Date" icon="calendar-xmark">
    **September 5, 2025** - Last day to qualify
  </Card>
</CardGroup>

### OG Trader Badge Requirements

<Frame>
  <img alt="OG Badge" />
</Frame>

To earn the exclusive OG Trader Badge:

* Trade during the eligibility period (May 17 - September 5, 2025)
* Reach **Level Tier 2 (Silver tier)** through trading activity
* Maintain active participation throughout the season

### Points Calculation

The OG Trader program rewards early participation with higher points for earlier trading dates:

<Tabs>
  <Tab title="Points Schedule">
    | Trading Start Date | Points Earned    | Bonus Type         |
    | ------------------ | ---------------- | ------------------ |
    | Day 1 (May 17)     | **5,000 points** | Maximum Early Bird |
    | Week 1             | \~4,500 points   | High Early Bird    |
    | Month 1            | \~3,500 points   | Early Bird         |
    | Mid-period         | \~2,550 points   | Standard           |
    | Month 3            | \~1,000 points   | Late Entry         |
    | Last day (Sep 5)   | **100 points**   | Minimum            |
    | After Sep 5        | 0 points         | Ineligible         |
  </Tab>

  <Tab title="How It Works">
    * Points decrease linearly from the maximum to minimum over the eligibility period
    * Earlier traders receive significantly more rewards
    * No points are awarded for trading after the season ends
    * Points are awarded once per trader based on their first trade date
  </Tab>
</Tabs>

## Benefits & Recognition

<CardGroup>
  <Card title="Exclusive Badge" icon="badge-check">
    Permanent OG Trader status displayed on your profile
  </Card>

  <Card title="Bonus Points" icon="trophy">
    Up to 5,000 additional points for early participation
  </Card>

  <Card title="Community Recognition" icon="users">
    Special recognition in the o1.exchange community
  </Card>
</CardGroup>

<Note>
  The OG Trader program was a one-time opportunity for early beta participants. Future seasons will have different reward structures and requirements.
</Note>

## Maximizing Season 1 Rewards

<Steps>
  <Step title="Trade Early">
    Start trading as close to May 17, 2025 as possible for maximum points
  </Step>

  <Step title="Reach Silver Tier">
    Focus on achieving Level Tier 2 through consistent trading activity
  </Step>

  <Step title="Stay Active">
    Maintain regular trading throughout the season to build your profile
  </Step>

  <Step title="Build Network">
    Use the referral system to compound your rewards beyond the OG bonus
  </Step>
</Steps>


# Trading Season 2: Base
Source: https://docs.o1.exchange/getting-started/rewards/season-2

Base Season rewards and point structure

## Base Season Overview

Trading Season 2 represents the foundation of o1.exchange's ongoing rewards program, focusing on Base chain trading with a comprehensive tier system based on ETH trading volume.

### Season Timeline

<Card title="Start Date" icon="calendar-plus">
  **September 5, 2025** - Season 2 begins immediately after Season 1 ends
</Card>

## Base Wizard Badge 🧙‍♂️

<Frame>
  <img alt="Base Wizard Badge" />
</Frame>

Earn the exclusive Base Wizard Badge by completing one of the following requirements:

<CardGroup>
  <Card title="Trading Path" icon="chart-line">
    **Trade 100 ETH** in total volume on Base chain
  </Card>

  <Card title="Referral Path" icon="users">
    **Refer 300 ETH** in total volume through your referral network
  </Card>
</CardGroup>

<Note>
  The Base Wizard Badge is a special achievement that recognizes both active traders and successful community builders. You only need to complete ONE of the two paths to earn this badge.
</Note>

## Tier Benefits

Each Base Chain tier unlocks exclusive benefits and recognition:

<CardGroup>
  <Card title="Exclusive Badges" icon="badge-check">
    Enter trading contest with generous bounty
  </Card>

  <Card title="Point Multipliers" icon="xmark">
    Higher tiers earn increased points per trade
  </Card>

  <Card title="Community Status" icon="crown">
    Special recognition and leaderboard placement
  </Card>
</CardGroup>

<Note>
  Season 2 focuses exclusively on Base chain ETH trading volume. Other networks and tokens may be included in future seasons.
</Note>


# Zora Trading Contest
Source: https://docs.o1.exchange/getting-started/rewards/zora-trading-contest

Eight-week trading contest for Zora Creator and Content Coins

## Contest Overview

The first Zora Trading Contest is an eight-week competitive campaign with a total reward pool of 2,500,000 \$ZORA tokens.

### Campaign Duration

<Card title="Contest Period" icon="calendar">
  **November 3, 2025 - December 27, 2025**

  8 consecutive weekly periods, resetting every Monday at 00:00 SGT
</Card>

## Rewards Pool

<Frame>
  <Card title="Total Prize Pool" icon="dollar-sign">
    **2,500,000 \$ZORA**

    Allocated as 312,500 \$ZORA per weekly window across 8 weeks
  </Card>
</Frame>

## Eligibility Requirements

<Note>
  Only trades executed directly through o1.exchange count toward eligibility. External trades (including after wallet export) are not eligible.
</Note>

## Eligible Trading Activity

The contest tracks bona fide trades of:

* **Zora Creator Coins**
* **Zora Content Coins**

All trades must be executed via the o1.exchange platform to qualify for leaderboard rankings.

## Weekly Leaderboards & Rewards

Each week features a volume-based leaderboard with the following reward structure:

### Volume Leaderboard (312,500 \$ZORA per week)

For users with Base Wizard Badge, we will apply a multiplier of 2X to count your trading volume.

Top 100 accounts by aggregate trading volume across all wallets linked to the same o1 account:

<Accordion title="Reward Distribution Formula">
  | Rank   | Reward per Account (\$ZORA) |
  | ------ | --------------------------- |
  | 1      | 29,738.75                   |
  | 2      | 26,523.75                   |
  | 3      | 24,916.25                   |
  | 4      | 21,701.25                   |
  | 5      | 20,093.75                   |
  | 6      | 19,290.00                   |
  | 7      | 16,878.75                   |
  | 8      | 15,271.25                   |
  | 9      | 12,860.00                   |
  | 10     | 12,056.25                   |
  | 11–15  | 4,822.50                    |
  | 16–20  | 3,536.50                    |
  | 21–25  | 2,411.25                    |
  | 26–50  | 1,607.50                    |
  | 51–100 | 382.625                     |
</Accordion>

## Reward Claims

<Info>
  Rewards will be distributed within 7 days of the weekly volume window.

  Winners must claim rewards within 14 days after each Weekly Campaign Period ends. Unclaimed rewards are forfeited and revert to Zora's control.
</Info>


# Zora Trading Contest Season 2
Source: https://docs.o1.exchange/getting-started/rewards/zora-trading-contest-season2

Season 2 for Zora Creator and Content Coins

## Contest Overview

The second Zora Trading Contest is a competitive campaign with a total reward pool of 1,250,000 \$ZORA tokens for traders.

### Campaign Duration

<Card title="Contest Period" icon="calendar">
  **January 5, 2026 - January 12, 2026**

  Contest ends at 12:00 AM PDT (7:00 AM UTC) on January 12, 2026
</Card>

## Rewards Pool

<Frame>
  <Card title="Total Prize Pool" icon="dollar-sign">
    **1,250,000 \$ZORA**

    Allocated to top 100 winners during the contest week
  </Card>
</Frame>

## Eligibility Requirements

<Note>
  Only trades executed directly through o1.exchange count toward eligibility. External trades (including after wallet export) are not eligible.
</Note>

## Eligible Trading Activity

The contest tracks bona fide trades of:

* **Zora Creator Coins**
* **Zora Content Coins**

All trades must be executed via the o1.exchange platform to qualify for leaderboard rankings.

## Weekly Leaderboards & Rewards

Each week features a volume-based leaderboard with the following reward structure:

### Volume Leaderboard (1,250,000 \$ZORA total)

For users with Base Wizard Badge, we will apply a multiplier of 2X to count your trading volume.

Top 100 accounts by aggregate trading volume across all wallets linked to the same o1 account:

<Accordion title="Reward Distribution Formula">
  | Rank   | Reward per Account (\$ZORA) |
  | ------ | --------------------------- |
  | 1      | 119,047.50                  |
  | 2      | 106,095.00                  |
  | 3      | 99,665.00                   |
  | 4      | 86,805.00                   |
  | 5      | 80,375.00                   |
  | 6      | 77,160.00                   |
  | 7      | 67,515.00                   |
  | 8      | 61,085.00                   |
  | 9      | 51,440.00                   |
  | 10     | 48,225.00                   |
  | 11–15  | 19,290.00                   |
  | 16–20  | 14,146.00                   |
  | 21–25  | 9,645.00                    |
  | 26–50  | 6,430.00                    |
  | 51–100 | 1,530.50                    |
</Accordion>

## Reward Claims

<Info>
  Rewards will be distributed within 7 days of the contest end.

  Winners must claim rewards within 14 days after the Contest Period ends. Unclaimed rewards are forfeited and revert to Zora's control.
</Info>


# Sign Up for o1.exchange
Source: https://docs.o1.exchange/getting-started/signup

Quick onboarding

## Create Your Account

### Account Creation

<Steps>
  <Step title="Visit o1.exchange">
    Go to [o1.exchange](https://o1.exchange) and click the "Enter App" button

    <Frame>
      <img alt="o1.exchange signup page" />
    </Frame>
  </Step>

  <Step title="Connect Your Wallet">
    There are 3 signup options:

    1. Gmail account
    2. One time password for any email you choose
    3. Wallet logins including Phantom, Backpack, MetaMask, Rabby, Coinbase, and over 120 wallet options.

    <Frame>
      <img alt="o1.exchange wallet login options" />
    </Frame>
  </Step>

  <Step title="Complete Profile">
    Set up your trading profile and preferences
  </Step>
</Steps>

## Next Steps

After creating your account:

1. **Fund Your Wallet**: Ensure you have sufficient balance on supported networks
   <Frame>
     <img alt="Fund your wallet on o1.exchange" />
   </Frame>
2. **Explore the Platform**: Familiarize yourself with the trading interface
3. **Join the Community**: Connect with other traders on Discord
4. **Start Trading**: Begin with small positions to get comfortable with the platform

<Card title="Ready to Trade?" icon="chart-line">
  [Start Trading Now](https://o1.exchange) - Create your account and join thousands of traders on o1.exchange
</Card>


# o1.exchange - Democratizing Alpha for Traders
Source: https://docs.o1.exchange/introduction

The Ultimate Trading Terminal for DeFi

<Frame>
  <img alt="o1 Exchange Banner" />
</Frame>

<Note>
  o1.exchange represents the pinnacle of high-frequency trading infrastructure on-chain — architected for unparalleled execution speed, engineered for quantitative edge, and optimized for full-range traders, from beginners to the pro.
</Note>

o1.exchange is the next-generation trading platform built for the DeFi ecosystem, combining institutional-grade infrastructure with an intuitive user experience for traders of all levels.

## Unmatched Trading Performance

<CardGroup>
  <Card title="Lightning-fast Execution" icon="bolt">
    Achieve microsecond-level transaction finality for optimal trade execution
  </Card>

  <Card title="Quantitative Edge" icon="chart-line">
    Leverage proprietary algorithms designed for maximum market advantage
  </Card>

  <Card title="Seamless Experience" icon="user-group">
    Intuitive interface that scales from beginners to professional traders
  </Card>
</CardGroup>

## Powered by Advanced Intelligence

<Accordion title="Alpha-Generating Opportunities">
  Our platform identifies profitable trading opportunities before they appear in market prices, giving you the edge to act first.
</Accordion>

<Accordion title="Real-time Analytics">
  Comprehensive analysis of on-chain metrics, social sentiment, and liquidity patterns delivered in real-time to inform your trading decisions.
</Accordion>

<Accordion title="Institutional-Grade Insights">
  Access exclusive market insights typically reserved for institutional traders, now available on our platform.
</Accordion>

## Full-spectrum Trading Ecosystem

<Tabs>
  <Tab title="Memecoins">
    Trade memecoins with confidence using our advanced predictive analytics that help identify trends before the market.
  </Tab>

  <Tab title="Tokenized Assets">
    Access a wide range of tokenized equities and synthetic assets all from one unified platform.
  </Tab>

  <Tab title="Cross-chain">
    Seamlessly trade across multiple blockchains with our unified liquidity pools and cross-chain infrastructure.
  </Tab>
</Tabs>

<Tip>
  Experience the future of trading with o1.exchange - where speed, intelligence, and accessibility converge.
</Tip>


# Token Contract Audits
Source: https://docs.o1.exchange/token/audits

Security audit reports for the $O token smart contracts

Third-party security audits have been conducted on the \$O token contract and related smart contracts to ensure the integrity and safety of the protocol.

## Audit Reports

<CardGroup>
  <Card title="Audit Report 1" icon="shield-check" href="https://drive.google.com/drive/home?dmr=1&ec=wgc-drive-globalnav-goto">
    View the first token contract audit report.
  </Card>

  <Card title="Audit Report 2" icon="shield-check" href="https://drive.google.com/drive/home?dmr=1&ec=wgc-drive-globalnav-goto">
    View the second token contract audit report.
  </Card>
</CardGroup>


# Community
Source: https://docs.o1.exchange/token/community

How o1.exchange rewards authentic traders through the Season 1 airdrop

## Season 1 Airdrop

The community allocation rewards authentic o1.exchange traders through a carefully designed airdrop mechanism. While the exact algorithm is not open-sourced or publicly disclosed, it was built to ensure that genuine users are well rewarded for their contributions to the platform.

The airdrop allocation for each user is determined by a sophisticated, nonlinear function that factors in:

* **S1.1 and S1.2 Points** — Core trading points earned across both phases of Season 1.
* **Net Fees Paid** — The actual fees paid to o1.exchange after accounting for each user's individual cashback rate, ensuring that users who contribute more to platform revenue are proportionally rewarded.
* **Referrals** — The number of users referred to o1.exchange, rewarding those who helped grow the community.
* **Trading Patterns** — Variety of token mints traded, token holding periods, user retention on the platform, and other behavioral signals used to differentiate real traders from farmers.
* **Social Impact** — Contributions and engagement on X (Twitter) and Discord, including Discord Maxi roles and community participation.

These inputs are combined in a way that disproportionately rewards consistent, organic platform usage over gameable single-dimension metrics. The goal is to distribute \$O to the users who genuinely contributed to o1.exchange's growth during Season 1.


# Disclosure
Source: https://docs.o1.exchange/token/disclosure

o1.exchange / $O Token – Disclosure

Writing as of June 2, 2026

The following disclosure is intended to provide an overview of o1.exchange and the \$O token.
It does not purport to be complete or to contain all information that a recipient may consider relevant in making a decision regarding the token.
Nothing in this disclosure should be viewed as a statement about the future of o1.exchange or the financial performance of the \$O token.

## 1. Project Information

o1.exchange is the Onchain Everything Exchange — a non-custodial, lightning-fast trading platform that delivers institutional-grade execution for spot trading, perpetual futures, and prediction markets across Base, Solana, and BNB Chain.

The platform aggregates liquidity from 100+ sources, offers sub-block latency execution, advanced order types (limit, TWAP, stops, sniping), real-time analytics, TradingView integration, and quantitative/algorithmic trading tools.

o1.exchange has achieved \$180M+ in spot trading volume, 3M+ transactions, and 400,000+ user signups within 7 months of beta, reaching top-3 revenue protocols on Base.

### Executive Officers and Key Personnel

**Company:** MoonX Foundation

PO Box 144, 3119 9 Forum Lane,
Camana Bay, George Town,
Grand Cayman, KY1-9006, Cayman Islands

**Founders and Executive Officers:**

* Claudio Romildo Pezzia, Director
* Jerry Pan, Founder

### Backers and Third-Party Contributors

o1.exchange raised a \$4.8M seed round from the following institutional investors:

* Coinbase Ventures
* a16z (Andreessen Horowitz)
* AllianceDAO
* The House Fund
* Amber Group
* 30+ other select angels and institutional investors

No third-party development shops or external contractors materially contributed to the development of the protocol or the token.

## 2. Token Sale Information

o1.exchange has not conducted and does not plan to conduct a public token sale.
\$O token distribution is driven entirely by usage (trading points program) and ecosystem growth.
There is no public offering, presale, or crowdsale of \$O tokens.

## 3. Token and Token Distribution Information

### Token Overview

\$O is the native utility token of the o1.exchange platform.
It is an ERC-20 token deployed on the Base blockchain (L2 on Ethereum).

\$O provides the following utility to holders:

* **Tiered Trading Fee Discounts:**
  Holding or staking \$O reduces trading fees in real time across all markets on o1.exchange and swap.o1.exchange DEX Aggregator; discounts scale with amount held/staked.

* **Early Access to Alpha Features:**
  Priority access to quantitative trading tools, strategy automation, advanced order types, and upcoming AI/alpha-generation features before public release.

* **Limited Badge Claims & Revenue Sharing Eligibility:**
  Users who stake at least a required amount of \$O for a required period may become eligible to claim limited ecosystem badges. Badge holders qualify to apply for a portion of o1.exchange platform revenue sharing. The minimum staking amount and staking duration are still TBD.

\$O does not represent equity, debt, or profit-sharing in any legal entity.
Token holders are not entitled to dividends, interest, revenue share, or any other financial consideration.

The platform may conduct discretionary ecosystem initiatives (grants, liquidity support) at the sole discretion of the project team; such actions do not confer enforceable rights on token holders.

### Token Supply and Dynamics

* **Token Standard:** ERC-20
* **Blockchain:** Base (Ethereum L2)
* **Total Supply:** 1,000,000,000 \$O (fixed; no inflation or minting after TGE)
* **Circulating Supply at TGE:** 16% (160,000,000 \$O)
  * Community Airdrop / Trading Points: 3% (claimable at TGE)
  * Ecosystem / Trading Competition: 3%
  * Liquidity Fund (CEX/DEX): 6% (unlocked at TGE)
  * Treasury: 4% (unlocked at TGE)
* No inflationary mechanics; token supply is fixed at genesis.
* Future token issuances: None planned.
  Any changes will be publicly disclosed at least one week before taking effect.

### Token Allocation and Vesting

The total supply of 1,000,000,000 \$O is allocated as follows:

| Category  | Allocation |    Tokens   | TGE Unlock |
| :-------- | :--------: | :---------: | :--------: |
| Community |     25%    | 250,000,000 |     3%     |
| Ecosystem |     25%    | 250,000,000 |     3%     |
| Investors |     18%    | 180,000,000 |     0%     |
| Team      |     10%    | 100,000,000 |     0%     |
| Treasury  |     16%    | 160,000,000 |     4%     |
| Liquidity |     6%     |  60,000,000 |     6%     |

**Vesting Details:**

* **Community (25%)** — Trading points airdrop and rewards. Season 1: 3% at TGE; Season 2: 5%; Season 3+: TBD.
* **Ecosystem (25%)** — Liquidity incentives and trading competitions. 1-year cliff followed by 36-month linear vesting. Only used for long-term development of the ecosystem and does not benefit insiders.
* **Investors (18%)** — Private venture round investors. 1-year cliff followed by 36-month linear vesting.
* **Team (10%)** — Project team. 1-year cliff followed by 36-month linear vesting.
* **Treasury (16%)** — Platform development, operations, and ecosystem initiatives. 4% unlocked at TGE; remainder held under multi-sig control. Only used for long-term development of the platform and does not benefit insiders.
* **Liquidity (6%)** — Initial DEX/CEX liquidity provisioning. Fully unlocked at TGE.

### Prior Funding Rounds

o1.exchange has completed one funding round:

* **Round:** Seed
* **Year:** 2025
* **Amount Raised:** \$4.8M
* **Investors:** Coinbase Ventures, a16z, AllianceDAO, The House Fund, Amber Group, and 30+ other select angels and institutional investors.
* **Vesting:** Investor token allocation (18% of total supply) is subject to a 1-year cliff lock starting at TGE, followed by 36-month linear vesting.
* Locked tokens cannot be staked.
  The staking program provides only non-financial utility benefits (fee discounts, feature access) and does not involve unvested token allocations.

## 4. Airdrop Information

o1.exchange plans to distribute \$O tokens to the community via a trading points conversion program at TGE.

* **Total Airdrop Allocation:**
  25% of total supply (250,000,000 \$O). 12% of them, i.e. 3%, will be distributed at TGE (Season 1).
* **Eligible Recipients:**
  Users who accumulated trading points on o1.exchange during the points program period (approximately 400,000 registered users).
* **Eligibility Requirements:**
  Active trading on o1.exchange platform, completion of identity verification, and passing of sanctions screening.
* **Geographic Restrictions:**
  Users in jurisdictions subject to OFAC and other applicable sanctions are excluded from claiming.
* **Claim Process:**
  Eligible users will be able to claim \$O tokens through an on-chain distribution contract beginning at TGE.
  Wallet authentication and applicable compliance checks are required.
  Tokens are not automatically pushed to wallets.
* **Unclaimed Tokens Policy:**
  Undeliverable tokens will be returned to the project treasury wallet and held for 90 days, during which affected users may contact the team.
  After 90 days, any undeliverable tokens will be permanently returned to the community treasury for future distribution programs as decided by the Project Team.

## 5. Conflicts of Interest Information

No related-party transactions involving the token other than the token allocations described in this disclosure have occurred.

## 6. Market Makers & Liquidity Information

o1.exchange will deploy liquidity for \$O via the Liquidity allocation (6% of total supply, 60,000,000 \$O) at TGE.
This allocation is designated for initial DEX and CEX liquidity provisioning.

No exchange listing fees have been paid to date.

Market maker arrangements, if any, will be disclosed prior to TGE.
Any contracted market maker identities, token allocations, and durations will be provided no later than one week before the Day 1 listing event.

Specific market maker details are pending finalization as of the date of this disclosure and will be updated accordingly.

No tokens have been allocated or granted to any market maker as of the date of this document.

## 7. Security Information

* **Token Contract:**
  The \$O token contract (ERC-20) is deployed on Base.
* **Smart Contract Audits:**
  Third-party security audits of the \$O token contract and all vesting contracts have been audited: [https://xors.xyz/audits/o1-exchange-2026-05-02.pdf](https://xors.xyz/audits/o1-exchange-2026-05-02.pdf).
* **Vesting Enforcement:**
  Token vesting for team and investor allocations is enforced through time-bound smart contracts on the Base blockchain.
  These contracts programmatically release tokens according to the vesting schedule.
  Contract code will be publicly verifiable on Basescan.
* **Platform Security:**
  o1.exchange is non-custodial. Users retain full control of assets.
  The platform supports multi-wallet authentication and on-chain verifiable transaction history.

### Public Resources

* Website: [o1.exchange](https://o1.exchange)
* Twitter/X: [x.com/o1\_exchange](https://x.com/o1_exchange)
* Discord: [discord.gg/o1exchange](https://discord.gg/o1exchange)
* Dune Analytics: [dune.com/stambouli\_o1/o1exchange](https://dune.com/stambouli_o1/o1exchange)
* DefiLlama: [defillama.com/protocol/o1.exchange](https://defillama.com/protocol/o1.exchange)

## 8. Risks

The following risks are material to holders and prospective holders of \$O:

1. **Utility Token Only:**
   \$O is a utility token providing platform benefits only.
   It does not represent equity, or debt in any legal entity.
   Token holders are not entitled to receive any payments, dividends, interest, revenue share, or other financial consideration by virtue of holding \$O.

2. **Market and Price Risk:**
   Token value is determined by market dynamics and utility.
   Cryptocurrencies are highly volatile and may lose substantial value.
   Past performance of other digital assets is not indicative of future results.

3. **No Guaranteed Revenue or Buybacks:**
   No guarantees are made regarding future revenue, token buybacks, or fee discounts.
   Any treasury ecosystem initiatives are discretionary and do not confer enforceable rights on token holders.

4. **Staking Cooldown:**
   Staking involves a 30-day cooldown period. Tokens are non-transferable during this period.
   The cooldown resets if additional unstaking occurs during an active cooldown.

5. **Regulatory Risk:**
   Regulatory treatment of digital assets and utility tokens varies by jurisdiction and may change.
   The platform applies geo-restrictions in sanctioned jurisdictions (OFAC-listed countries).
   Certain features, such as prediction market routing, may not be available in specific jurisdictions including the United States.

6. **Platform Development Risk:**
   Future platform features, governance mechanisms, and roadmap milestones are subject to change.
   Governance exploration (\$O-based voting) and synthetic assets are under consideration but not guaranteed.

7. **Concentration Risk:**
   The founding team and seed investors collectively control significant token allocations.
   While vesting schedules reduce short-term concentration risk, these parties may have significant influence after vesting periods.

8. **Liquidity Risk:**
   There is no guarantee of ongoing liquidity for \$O on any exchange.
   Market conditions may make it difficult to buy or sell \$O at desired prices.

9. **This Disclosure:**
   This disclosure is for informational purposes only and does not constitute investment advice, a solicitation to purchase \$O, or a prospectus.
   Recipients should conduct their own due diligence.


# MiCA Whitepaper
Source: https://docs.o1.exchange/token/mica-whitepaper

Markets in Crypto-Assets (MiCA) Whitepaper for $O Token

## MiCA Whitepaper

The Markets in Crypto-Assets (MiCA) whitepaper for the \$O token is available for download below.

<Card title="Download MiCA Whitepaper" icon="file-pdf" href="https://drive.google.com/file/d/1gj-y0p1sUeQHAogPfoJ3wN1vRxQVPmWQ/view?usp=sharing">
  View or download the full MiCA whitepaper (PDF)
</Card>


# Whitepaper
Source: https://docs.o1.exchange/token/whitepaper

$O – The Utility Token of the Onchain Everything Exchange

**\$O – The Utility Token of the Onchain Everything Exchange**

Writing as of June 2, 2026

Version 1.0 | April 2026

TGE: June 2026 17 | Deployed on Base (ERC-20)

## Executive Summary

o1.exchange is the Onchain Everything Exchange — a lightning-fast, non-custodial trading platform that delivers institutional-grade execution for spot, perpetuals, prediction markets, and future synthetic/tokenized assets across Base, Solana, and BNB Chain. Built for retail traders, quant funds, and AI agents alike, o1.exchange aggregates liquidity from 100+ sources, offers sub-block latency execution, advanced order types (limit, TWAP, stops, sniping), real-time analytics, TradingView integration, and quantitative/algorithmic trading tools previously reserved for CeFi.

The utility token \$O powers the ecosystem. Holders and stakers receive tiered trading fee discounts, early access to alpha features (quant automation, advanced order types, strategy builders). A trading points program further rewards active traders with \$O allocations, driving long-term platform loyalty.

Backed by Coinbase Ventures, a16z, AllianceDAO, The House Fund, Amber Group, and 30+ other select angels and institutional investors in a \$4.8M seed round, o1.exchange has already achieved \$220M+ spot volume, 3M+ transactions, and 400k+ user signups in just 7 months of beta, reaching top-3 revenue protocols on Base while expanding to perps (Hyperliquid) and prediction markets (Kalshi).

## 1. The Problem: Fragmented, Expensive, and Underpowered Onchain Trading

DeFi trading today suffers from:

* Fragmented liquidity and poor price discovery across chains and venues.
* High slippage, MEV exposure, and gas costs.
* Lack of advanced execution tools (no native TWAP, limits, or algo strategies on most DEXs).
* Slow, clunky UX compared to centralized exchanges.
* No seamless support for perps, prediction markets, or emerging asset classes (synthetics, tokenized equities) in one unified interface.
* High fees that erode retail and institutional profitability.

Traders are forced to juggle multiple apps, bridges, and wallets, losing edge and paying premium prices.

## 2. The Solution: o1.exchange – Onchain Everything Exchange

o1.exchange is a fully non-custodial trading terminal that brings CeFi-grade performance to DeFi rails. Key features include:

* **Low-latency execution** (≤1 block or microsecond-level on supported chains).
* **Aggregated liquidity** across 100+ DEXs, on-chain venues, and off-chain PMMs for best-in-class fills.
* **Advanced order types** (limit, TWAP, stops/take-profit, sniping) with algorithmic automation.
* **Quantitative & AI-powered tools** — strategy builders, backtesting, real-time analytics, PnL tracking, and multi-chain portfolio views.
* **Multi-asset coverage** — spot, perpetual futures (via Hyperliquid), prediction markets (via Kalshi), and roadmap for tokenized equities/synthetics.
* **Multi-chain & gas abstraction** — trade on Base (primary), Solana, BNB Chain without managing gas or bridges.
* **Self-custodial security** — multi-wallet support, on-chain verifiable history, no custody.
* **Institutional-ready** — sub-accounts, role-based access, post-trade reporting, order-flow masking.

The result: traders get more tokens on every trade, lower costs, and professional-grade tools in one seamless platform.

## 3. \$O Token Utility

\$O is the core utility token that aligns user incentives with platform growth.

Primary benefits for \$O holders and stakers:

### Tiered Trading Fee Discounts

Hold or stake \$O to unlock meaningful reductions in trading fees. Discounts are tiered by amount held/staked and apply in real time across all markets.

### Early Access to Alpha Features

\$O holders gain priority access to quantitative trading tools, strategy automation, advanced order types, and upcoming AI/alpha-generation features before public release.

### Limited Badge Claim & Revenue Sharing Eligibility

Users who stake at least a required amount of \$O for a required period may become eligible to claim limited ecosystem badges. Badge holders qualify to apply for a portion of o1.exchange platform revenue sharing, creating a direct link between long-term staking commitment and platform economic participation.

### Trading Points Program

Active traders earn points convertible to \$O allocations. This incentivizes volume and loyalty from day one.

### Staking Mechanics

* Navigate to the staking page on o1.exchange, connect wallet, and stake \$O.
* 30-day cooldown on unstaking (resets if additional unstaking occurs during cooldown).
* Staked tokens remain in your wallet; no lock-up beyond the cooldown.

## 4. Tokenomics

* **Token Standard:** ERC-20 on Base
* **Total Supply:** 1,000,000,000 \$O (fixed, no inflation)

**Allocation Breakdown** (approximate, subject to final TGE parameters):

| Category  | Allocation | Description                                                                                          |
| :-------- | :--------: | :--------------------------------------------------------------------------------------------------- |
| Community |     25%    | Trading points airdrop (3% at TGE for Season 1), rewards. Season 1: 3%; Season 2: 5%; Season 3+: TBD |
| Ecosystem |     25%    | Liquidity incentives and trading competitions                                                        |
| Investors |     18%    | Seed round backers                                                                                   |
| Team      |     10%    | Vested with 12-month cliff + linear release                                                          |
| Treasury  |     16%    | Platform development, operations, future initiatives                                                 |
| Liquidity |     6%     | Initial DEX/CEX liquidity provisioning                                                               |

* **Circulating Supply at TGE:** 16%
* **Vesting:** Investor and team tokens follow standard 1-year cliff + linear vesting to ensure long-term alignment.
* **No public sale** — distribution driven by usage (points program) and ecosystem growth.

## 5. Platform Growth & Treasury

Higher trading volume drives platform growth and operational sustainability. As the platform matures, the treasury may allocate resources toward ecosystem initiatives — including discretionary market operations such as liquidity support, grants, and ecosystem incentives — at the sole discretion of the project team. These actions, if implemented, are not guaranteed and do not confer any enforceable rights or financial entitlements to token holders.

Staking \$O provides access to tiered fee discounts and early feature access, directly reducing trading costs and improving the user experience. Staking does not entitle holders to any payments, dividends, interest, revenue share, or other financial consideration.

## 6. Roadmap & Future Governance

* **Q2–Q3 2026:** Expanded quant/AI tools, additional chain integrations, and discretionary treasury ecosystem initiatives.
* **2026+:** Onchain governance exploration (potential \$O voting on select parameters), synthetic assets, deeper institutional tooling.

Current governance is team-led with community feedback via Discord/Telegram. Future \$O-based governance is under active consideration.

## 7. Team & Backers

* **Founder:** Jerry Pan
* **Director:** Claudio Romildo Pezzia
* **Company:** MoonX Foundation, incorporated in Cayman Islands
* **Backers:** Coinbase Ventures, a16z, AllianceDAO, The House Fund, Amber Group, and 30+ other select angels and institutional investors.

## 8. Risks & Disclaimers

* \$O is a utility token providing platform benefits only. It does not represent equity, debt, or profit-sharing rights in any legal entity.
* Token value is determined by market dynamics and utility. Cryptocurrencies are volatile and may lose value.
* Staking involves a 30-day cooldown; tokens are non-transferable during this period.
* Token holders are not entitled to receive any payments, dividends, interest, revenue share, or other financial consideration by virtue of holding \$O. No guarantees are made regarding future revenue, buybacks, or fee discounts.
* o1.exchange is non-custodial; users retain full control of assets.
* The platform applies geo-restrictions to users in sanctioned jurisdictions (e.g., OFAC-listed countries). Certain third-party features, such as prediction market routing, may not be available in specific jurisdictions including the United States. Core platform functionality and \$O token utility remain available where legally permitted.
* This whitepaper is for informational purposes only and does not constitute investment advice, a solicitation to purchase \$O, or a prospectus.

For the latest updates, visit [o1.exchange](https://o1.exchange), follow official channels, and review the token contract upon deployment.

*o1.exchange – Onchain Everything Exchange.*