> ## 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

> Quote exact-input trades and prepare wallet transactions with the configured router.

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": 50,
  "referrer": "0x3333333333333333333333333333333333333333",
  "comment": "API trade"
}
```

`amount_in_raw` uses the input currency's base units: quote units for a buy and launch-token units for a sell. Slippage uses basis points, where 1 bps is 0.01%; `50` means 0.5%, `100` means 1%, and the maximum is `4999`.

The API resolves the contracts recorded for the token, including its pool key, hook, paired asset, tick spacing, router and its quoting and approval requirements. 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/fees/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
* ERC-20 approval transactions for the spender required by the selected router
* Permit2 typed data when the selected route requires it

## 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. verifies current input balance and the selected router's approval requirements
3. requotes the exact route
4. rejects a price move beyond the reviewed minimum
5. uses the stricter valid minimum
6. validates the deadline and any required Permit2 nonce and signature
7. builds calldata for the configured router: SwapX on Arc, Universal Router on Base, Robinhood and Monad
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 required Permit2 signature returns `400 invalid_request`. Arc does not use Permit2; supplying a Permit2 signature to Arc preparation returns `409 stale_quote`. 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. The launch hook rejects exact-output execution while a pool's surcharge window is active. New Arc pools have no active surcharge window, but this API still exposes exact-input swaps only.
</Warning>

## Monad settlement scope

Use `chain_id: 143`. API buys spend the launch pool's paired MON, USDC or WETH; sells return that asset. The API does not expose the browser's MON-to-USDC/WETH multihop settlement or atomic developer-buy flow. Native MON needs transaction value; ERC-20 USDC/WETH use the returned approval/Permit2 requirements. WMON is routing infrastructure, not a registered quote.

## Arc settlement and approvals

Use `chain_id: 5042`. Buys spend six-decimal ERC-20 USDC and receive the launched token; sells spend launched-token units and receive ERC-20 USDC. For a buy, `amount_in_raw: "1000000"` means 1 USDC. The API trades through the exact launch pool using SwapX, with `value: "0"` and no Permit2 signature, wrapper or USDC-to-itself swap.

Quotes simulate execution against the funded wallet and measure the recipient's output balance change. Insufficient input funds or a failed route simulation returns `422 quote_unavailable`. A quote cannot substitute for funding the wallet first.

If approval is needed, the response approves the exact input amount to the configured SwapX router. A nonzero insufficient allowance includes a zero-reset step first; follow `depends_on` and wait for confirmations before preparation. Preparation refreshes the quote, verifies the confirmed allowance and preserves at least the reviewed minimum output. Approval can remain if the wallet approves but does not execute the swap.

Native USDC pays gas with 18-decimal units and ERC-20 USDC uses six decimals, but both access the same balance. Leave enough USDC for gas rather than treating the two balances as separate funds. API swaps cover the direct paired-asset route; browser multihop settlement and atomic Dev Buy are separate flows.