---
name: O1exchange
description: Use when building trading applications, integrating DEX swap functionality, executing programmatic trades, or implementing swap UIs. Agents should reach for this skill when working with the Trading API for direct trade execution, the DEX Aggregator API for optimal swap routing on Base, or when helping users understand trading features, rewards programs, and platform capabilities.
metadata:
    mintlify-proj: o1exchange
    version: "1.0"
---

# o1.exchange Skill

## Product summary

o1.exchange is a next-generation DeFi trading platform combining institutional-grade infrastructure with an intuitive interface. It provides two primary APIs: the **Trading API** for programmatic trade execution with MEV protection and Permit2 support, and the **DEX Aggregator API** for optimal swap routing across 20+ venues on Base mainnet. The platform also offers a web UI with spot, limit, sniper, and TWAP order types, portfolio analytics, wallet management, and a referral rewards system.

**Key files and endpoints:**
- Trading API: `POST https://api.o1.exchange/api/v2/order` (create batch), `POST https://api.o1.exchange/api/v2/order/complete` (submit)
- DEX Aggregator API: `POST /quote`, `POST /submit`, `POST /execute` (Base mainnet only, chainId 8453)
- API key generation: https://o1.exchange/api-trading
- Primary docs: https://docs.o1.exchange

## When to use

Reach for this skill when:
- **Building a swap UI or DEX aggregator integration** — use the DEX Aggregator API to quote and execute swaps on Base with optimal routing
- **Executing trades programmatically** — use the Trading API for direct trade execution with MEV protection and gasless approvals
- **Implementing live price feeds** — poll `/quote` to display real-time swap prices with freshness handling
- **Handling multi-step trading flows** — implement quote preview, user confirmation, and transaction submission
- **Managing wallet integrations** — understand Permit2 signatures, ERC-20 approvals, and native ETH handling
- **Advising on trading features** — explain order types (spot, limit, sniper, TWAP), rewards tiers, and referral mechanics
- **Troubleshooting API errors** — diagnose rate limits, quote expiry, slippage reverts, and authentication issues

## Quick reference

### DEX Aggregator API (Base only)

| Endpoint | Purpose | Key params | Returns |
|---|---|---|---|
| `POST /quote` | Price a swap, no execution | `chainId`, `tokenIn`, `tokenOut`, `amountIn`, `slippageBps` | `quoteId`, `routePlan`, `expiresAt` (~10s TTL) |
| `POST /submit` | Build tx from quote | `quoteId`, `user` | `{ to, data, value }` ready to sign |
| `POST /execute` | Quote + build in one call | Same as `/quote` + `user` | `routePlan` + `{ to, data, value }` |
| `GET /health` | Health check | None | `{ status: "ok" }` |

### Trading API (multi-chain)

| Endpoint | Purpose | Key params | Returns |
|---|---|---|---|
| `POST /api/v2/order` | Create transaction batch | `networkId`, `signerAddress`, `tokenAddress`, `uiAmount`, `direction`, `slippageBps`, `mevProtection` | `id` (batch ID), `transactions[]` with unsigned tx + Permit2 EIP-712 |
| `POST /api/v2/order/complete` | Submit signed transactions | `id` (batch ID), `transactions[]` with signed tx + permit2 signature | `{ success, transactions[] }` with tx hash and status |

### Authentication

All endpoints except `GET /health` require `x-api-key` header:
```
-H "x-api-key: <YOUR_API_KEY>"
```

API keys are issued by the o1 team (contact via partnership channel). Default rate limit: **120 req/min per key** (sliding 60-second window).

### Network IDs

| Network | ID | API Support |
|---|---|---|
| Base | 8453 | DEX Aggregator + Trading |
| BSC | 56 | Trading only |
| Solana | 1399811149 | Trading only |

### Slippage and fees

- **Slippage:** specified in basis points (bps). 100 bps = 1%. Typical: 300 bps (3%) for normal conditions, 500–1000 bps for volatile tokens.
- **Integrator fee:** optional `feeBps` on `/quote` request; taken from output, enforced on-chain.
- **Permit2:** EIP-712 signature for gasless approvals; one-time approval for unlimited trading.

## Decision guidance

### When to use DEX Aggregator vs Trading API

| Scenario | Use | Why |
|---|---|---|
| Building a swap UI with price preview | DEX Aggregator (`/quote` + `/submit`) | Optimized routing, user sees price before signing, two-step flow |
| One-click instant swap (no preview) | DEX Aggregator (`/execute`) | Single round trip, no quote expiry handling |
| Programmatic bot trading | Trading API | Direct execution, MEV protection, multi-chain support |
| Server-side trade execution | Trading API | Full control over signing, batch operations |
| Base mainnet only, need best routing | DEX Aggregator | Searches 20+ venues, splits trades for optimization |

### When to use two-step vs one-step DEX flow

| Pattern | Use when | Trade-off |
|---|---|---|
| `/quote` → `/submit` (two-step) | User reviews price before signing | Quote expires in ~10s; must handle 404 and re-quote |
| `/execute` (one-step) | No preview needed; instant execution | Single call; user doesn't see price before signing |

### When to use Permit2 vs standard approval

| Approach | Use when | Benefit |
|---|---|---|
| Permit2 (EIP-712) | First trade with a token | Gasless approval; one signature covers unlimited future trades |
| Standard ERC-20 approval | Token already approved or Permit2 unavailable | Simpler flow; no EIP-712 signing |
| Native ETH | Swapping raw ETH | Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` or zero address; router handles wrap/unwrap |

## Workflow

### Typical DEX Aggregator swap (two-step)

1. **Get a quote:** `POST /quote` with `chainId: 8453`, `tokenIn`, `tokenOut`, `amountIn`, `slippageBps`. Store the `quoteId` and display `expectedAmountOut` to the user.

2. **Check quote freshness:** Quotes expire in ~10 seconds (`expiresAt`). If the user takes longer, re-quote before submitting.

3. **Approve token (if needed):** Read the router's allowance for `tokenIn`. If below `amountIn`, call `approve()` on the token contract. Skip if using Permit2 or if `tokenIn` is native ETH.

4. **Build the transaction:** `POST /submit` with `quoteId` and `user` (wallet address). Receive `{ to, data, value }` ready to sign.

5. **Sign and broadcast:** Use wallet client to `sendTransaction()` with the returned `to`, `data`, `value`. Wait for receipt.

6. **Verify success:** Check `receipt.status === "success"`. A tx hash alone doesn't confirm the swap executed.

### Typical Trading API flow

1. **Generate API key:** Visit https://o1.exchange/api-trading and create a key.

2. **Set environment:** Create `.env.local` with `EXECUTE_TRADE_PRIVATE_KEY`, `EXECUTE_TRADE_API_TOKEN`, `EXECUTE_TRADE_BASE_URL`, `EXECUTE_TRADE_RPC_URL`.

3. **Create batch:** `POST /api/v2/order` with `networkId`, `signerAddress`, `tokenAddress`, `uiAmount`, `direction` (buy/sell), `slippageBps`, `mevProtection: true`. Receive batch ID and unsigned transactions.

4. **Sign Permit2 (if present):** Extract EIP-712 from `permit2.eip712`, sign with wallet's `signTypedData()`, replace the signature placeholder in transaction data.

5. **Sign transaction:** Sign the unsigned tx with `signTransaction()`.

6. **Submit batch:** `POST /api/v2/order/complete` with batch ID and signed transactions. Receive tx hashes and status.

7. **Monitor:** Poll or wait for transaction confirmation on-chain.

## Common gotchas

- **Quote expiry on `/submit`:** Quotes cached server-side for ~10 seconds. If the user delays, `/submit` returns `404 quote not found or expired`. Always re-quote and retry; don't surface as a user error unless it repeats.

- **Slippage reverts are intentional:** If a swap reverts with "Slippage", the safety net worked. The pool state moved between quote and inclusion. Increase `slippageBps` or re-quote and retry quickly.

- **Permit2 signature placeholder is fixed:** The string `42f68902113a2a579bcc207c91254c8516d921250e748c18a082d91d74908f8e9a05f27b72a030c6a42d77d0e0aab6fb09219b01a01e7b5b24e4f322ee1762ff1b` is the placeholder. Replace it with the actual signature; don't change it.

- **Rate limit window is sliding:** On `429`, back off for at least 1 second with jitter. Immediate retry lands in the same bucket and makes it worse.

- **API key is per-integration:** Use distinct keys for different apps or environments. Spreading requests across multiple keys for the same product doesn't increase quota.

- **DEX Aggregator is Base-only:** `chainId: 8453` only. Multi-chain support is on the roadmap. Trading API supports Base, BSC, and Solana.

- **Don't expose API keys client-side:** Proxy all requests through your own server. If a key leaks, revoke it immediately.

- **Allowance must be >= amountIn:** If approval fails with `INSUFFICIENT_ALLOWANCE`, the router's allowance is below the trade amount. Approve for at least `amountIn`.

- **Native ETH handling:** Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` or zero address for native ETH. The router auto-wraps/unwraps; no manual WETH conversion needed.

- **Fee enforcement is on-chain:** `feeBps` on `/quote` is enforced inside the router contract, not the API. The fee is deducted from output.

## Verification checklist

Before submitting work with o1.exchange:

- [ ] API key is stored securely (server-side, not in source control, not in browser)
- [ ] All requests include `x-api-key` header (except `GET /health`)
- [ ] Quote TTL is handled: re-quote if `/submit` returns `404`
- [ ] Slippage tolerance is reasonable (300–1000 bps depending on volatility)
- [ ] Token approval is checked before swap (or Permit2 is used)
- [ ] Transaction receipt is verified (`status === "success"`) before confirming to user
- [ ] Error responses are handled: `400` (fix request), `401` (fix key), `404` (re-quote), `429` (backoff), `5xx` (retry with jitter)
- [ ] Rate limit headroom is planned (120 req/min default; request higher tier if needed)
- [ ] Native ETH is handled correctly (use sentinel address, no manual wrapping)
- [ ] Permit2 signature placeholder is not modified
- [ ] On-chain reverts are logged and user-facing errors are translated (not raw API messages)

## Resources

- **Comprehensive navigation:** https://docs.o1.exchange/llms.txt
- **DEX Aggregator API introduction:** https://docs.o1.exchange/api/dex-aggregator/introduction
- **Trading API overview:** https://docs.o1.exchange/api/trading
- **Error handling guide:** https://docs.o1.exchange/api/dex-aggregator/guides/error-handling

---

> For additional documentation and navigation, see: https://docs.o1.exchange/llms.txt