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

{
  "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:

{
  "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.

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.

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.