POST /execute - o1 Exchange

One-shot quote + submit

curl --request POST \
  --url https://quiet-bloodhound-531.convex.site/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "chainId": 2,
  "tokenIn": "<string>",
  "tokenOut": "<string>",
  "amountIn": "<string>",
  "slippageBps": 5000,
  "user": "<string>",
  "maxHops": 2,
  "splitEnabled": true,
  "enforcePoolDisjoint": true,
  "allowedDexes": [],
  "feeBps": 5000,
  "useNativeIn": true,
  "unwrapNativeOut": true
}
'

{
  "quoteId": "<string>",
  "chainId": 123,
  "to": "<string>",
  "data": "<string>",
  "value": "<string>",
  "routePlan": {
    "chainId": 123,
    "tokenIn": "<string>",
    "tokenOut": "<string>",
    "amountIn": "<string>",
    "expectedAmountOut": "<string>",
    "minAmountOut": "<string>",
    "slippageBps": 5000,
    "routes": [
      {
        "amountIn": "<string>",
        "legs": [
          {
            "tokenIn": "<string>",
            "tokenOut": "<string>",
            "amountIn": "<string>",
            "minOut": "<string>",
            "data": {
              "kind": "<string>",
              "pool": "<string>",
              "feeBps": 5000
            },
            "poolId": "<string>"
          }
        ]
      }
    ],
    "blockNumber": 1,
    "feeBps": 5000,
    "gasEstimate": {
      "gasUnits": 1,
      "gasCostWei": "<string>"
    },
    "feeBreakdown": {
      "protocolFeeAmount": "<string>",
      "integratorFeeAmount": "<string>"
    },
    "metadata": {
      "connectorsConsidered": [
        "<string>"
      ],
      "candidatePaths": 1,
      "selectedPaths": 1,
      "candidates": [
        {
          "path": [
            "<string>"
          ],
          "dexes": [],
          "projectedOut": "<string>",
          "allocatedIn": "<string>",
          "score": 123
        }
      ]
    },
    "nativeIn": true,
    "nativeOut": true
  },
  "expiresAt": 123
}

POST

execute

One-shot quote + submit

curl --request POST \
  --url https://quiet-bloodhound-531.convex.site/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "chainId": 2,
  "tokenIn": "<string>",
  "tokenOut": "<string>",
  "amountIn": "<string>",
  "slippageBps": 5000,
  "user": "<string>",
  "maxHops": 2,
  "splitEnabled": true,
  "enforcePoolDisjoint": true,
  "allowedDexes": [],
  "feeBps": 5000,
  "useNativeIn": true,
  "unwrapNativeOut": true
}
'

{
  "quoteId": "<string>",
  "chainId": 123,
  "to": "<string>",
  "data": "<string>",
  "value": "<string>",
  "routePlan": {
    "chainId": 123,
    "tokenIn": "<string>",
    "tokenOut": "<string>",
    "amountIn": "<string>",
    "expectedAmountOut": "<string>",
    "minAmountOut": "<string>",
    "slippageBps": 5000,
    "routes": [
      {
        "amountIn": "<string>",
        "legs": [
          {
            "tokenIn": "<string>",
            "tokenOut": "<string>",
            "amountIn": "<string>",
            "minOut": "<string>",
            "data": {
              "kind": "<string>",
              "pool": "<string>",
              "feeBps": 5000
            },
            "poolId": "<string>"
          }
        ]
      }
    ],
    "blockNumber": 1,
    "feeBps": 5000,
    "gasEstimate": {
      "gasUnits": 1,
      "gasCostWei": "<string>"
    },
    "feeBreakdown": {
      "protocolFeeAmount": "<string>",
      "integratorFeeAmount": "<string>"
    },
    "metadata": {
      "connectorsConsidered": [
        "<string>"
      ],
      "candidatePaths": 1,
      "selectedPaths": 1,
      "candidates": [
        {
          "path": [
            "<string>"
          ],
          "dexes": [],
          "projectedOut": "<string>",
          "allocatedIn": "<string>",
          "score": 123
        }
      ]
    },
    "nativeIn": true,
    "nativeOut": true
  },
  "expiresAt": 123
}

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 two-step flow so the user sees the final price before signing.

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

Request

Endpoint
Body

POST {API_URL}/execute
Content-Type: application/json
x-api-key: <YOUR_API_KEY>

{
  "chainId": 8453,
  "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "tokenOut": "0x4200000000000000000000000000000000000006",
  "amountIn": "1000000000",
  "slippageBps": 100,
  "user": "0xYourWalletAddress",
  "useNativeIn": false,
  "unwrapNativeOut": true,
  "feeBps": 30
}

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 and POST /submit for full descriptions of each field.

Response

200 OK
400 Bad Request
401 Unauthorized
429 Rate Limited

{
  "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": [ /* ... */ ]
  }
}

{ "error": "no routes for pair" }

{ "error": "unauthorized" }

{
  "error": "rate limit exceeded",
  "limit": 120,
  "windowSec": 60
}

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.

Examples

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),
});

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

Authorizations

x-api-key

string

header

required

Body

application/json

chainId

integer

required

Required range: x >= 1

tokenIn

string

required

20-byte hex address. The sentinel 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE (or the zero address) signals the chain's native asset (ETH on Base) and is recognized in tokenIn/tokenOut.

Pattern: ^0x[a-fA-F0-9]{40}$

tokenOut

string

required

20-byte hex address. The sentinel 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE (or the zero address) signals the chain's native asset (ETH on Base) and is recognized in tokenIn/tokenOut.

Pattern: ^0x[a-fA-F0-9]{40}$

amountIn

string

required

Non-negative integer encoded as a decimal string (wei).

Pattern: ^[0-9]+$

slippageBps

integer

required

Required range: 0 <= x <= 10000

user

string

required

20-byte hex address. The sentinel 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE (or the zero address) signals the chain's native asset (ETH on Base) and is recognized in tokenIn/tokenOut.

Pattern: ^0x[a-fA-F0-9]{40}$

maxHops

integer

Required range: x >= 1

splitEnabled

boolean

enforcePoolDisjoint

boolean

allowedDexes

enum<string>[]

Minimum array length: 1

Available options:

UNIV2,

UNIV3,

UNIV4,

AERODROME_V2LIKE,

AERODROME_CL,

PANCAKE_V2,

PANCAKE_V3,

PANCAKE_INFINITY_CL,

HYDREX,

QUICKSWAP_V4,

ALIEN_BASE_V3,

CURVE,

PROPSWAP,

TESSERA,

ELFOMOFI,

LUNARBASE,

FELTIR,

DODO_V2,

WOOFI,

GYROSCOPE_ECLP,

MAVERICK_V2

feeBps

integer

Required range: 0 <= x <= 10000

useNativeIn

boolean

unwrapNativeOut

boolean

permit

object

Show child attributes

Response

Quote + transaction payload

quoteId

string

required

chainId

integer

required

string

required

20-byte hex address. The sentinel 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE (or the zero address) signals the chain's native asset (ETH on Base) and is recognized in tokenIn/tokenOut.

Pattern: ^0x[a-fA-F0-9]{40}$

data

string

required

Hex-encoded bytes.

Pattern: ^0x[a-fA-F0-9]*$

value

string

required

Non-negative integer encoded as a decimal string (wei).

Pattern: ^[0-9]+$

routePlan

object

required

Show child attributes

expiresAt

integer<int64>

required

POST /submit GET /health

​Request

​Body parameters

​Response

​Response fields

​Examples

Authorizations

Body

Response

Request

Body parameters

Response

Response fields

Examples