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

# Quote and prepare trades

> Use the launch pool's Uniswap v4 Quoter, Permit2, and Universal Router safely.

The trading API supports exact-input buys and sells against the token's own Uniswap v4 launch pool.

## Quote

`POST /swaps/quote`

```json theme={null}
{
  "chain_id": 4663,
  "wallet": "0x1111111111111111111111111111111111111111",
  "token_address": "0x2222222222222222222222222222222222222201",
  "side": "sell",
  "amount_in_raw": "1000000000000000000",
  "slippage_bps": 300,
  "referrer": "0x3333333333333333333333333333333333333333",
  "comment": "API trade"
}
```

`amount_in_raw` is an unsigned base-10 integer in input-token base units. `slippage_bps` must be below 5000.

The API resolves the token's historical suite, pool key, hook, quote, tick spacing, router, Permit2, and Quoter. It does not guess from `tx.to` or use only the latest factory.

The optional referrer is preserved through quote and preparation and encoded in the same hook data used by the Launchpad app. It must be a separate eligible wallet, not zero, the trader, creator, platform treasury, or router. Invalid choices return `422 invalid_referrer`; valid referrals accrue their fee share in FeeEscrow and claim it through `POST /claims/prepare`.

The response contains:

* signed `quote_id` and expiry
* `prepared_at` and the chain block used for all quote, balance, and allowance reads
* input and output currencies
* expected and minimum output
* estimated quote gas
* a normalized `review` of the exact route, amounts, slippage, referrer, and comment
* balance and allowance issues
* an ERC-20 approval transaction when the input token has not approved Permit2
* Permit2 typed data when the router allowance is missing or expired

## Actionable issues

A valid request can return HTTP 200 with:

```json theme={null}
{
  "code": "erc20_allowance_required",
  "severity": "action_required",
  "asset": "0x...",
  "spender": "0x...",
  "actual_raw": "0",
  "required_raw": "1000000",
  "remediation_step_id": "approve-input-token"
}
```

`blocking` means funds or state must change. `action_required` points to a provided step. `warning` is reviewable but does not stop preparation.

## Prepare

`POST /swaps/prepare` accepts the reviewed `quote_id`, wallet, and optional Permit2 signature.

The API:

1. verifies the quote signature, wallet binding, and expiry
2. rereads wallet balance, ERC-20 approval, and Permit2 allowance at one block
3. requotes the exact route
4. rejects a price move beyond the reviewed minimum
5. uses the stricter valid minimum
6. validates the Permit2 nonce, deadline, and signature requirement
7. builds official Universal Router v4 commands
8. appends ERC-8021 builder attribution on Base
9. simulates the exact transaction from the expected wallet

The prepare response shows reviewed, refreshed, and execution-minimum amounts together. An expired or moved quote returns `409 stale_quote`, an unconfirmed ERC-20 approval returns `409 approval_not_confirmed`, and changed Permit2 state returns `409 invalid_permit`. A missing or unexpected signature is a `400 invalid_request`; an unavailable route or failed simulation returns a specific `422` problem.

The wallet must submit the returned `to`, `data`, and `value` unchanged before expiry. `value` is the exact swap value, not a gas budget; the wallet must retain additional native currency for gas.

<Warning>
  Exact-output swaps are not exposed. During the anti-snipe window the launch hook intentionally rejects exact-output execution.
</Warning>