Skip to main content
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": [
    "UNIV2"
  ],
  "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": [
          {
            "dex": "UNIV2",
            "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": [
            "UNIV2"
          ],
          "projectedOut": "<string>",
          "allocatedIn": "<string>",
          "score": 123
        }
      ]
    },
    "nativeIn": true,
    "nativeOut": true
  },
  "expiresAt": 123
}

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.

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

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

​
Body parameters

/execute accepts the union of /quote and /submit parameters.
FieldTypeRequiredDescription
chainIdintegeryes8453 for Base.
tokenInaddressyesToken to sell. Native sentinel allowed.
tokenOutaddressyesToken to buy. Native sentinel allowed.
amountInstringyesAmount in wei as a decimal string.
slippageBpsintegeryesSlippage tolerance in bps (0..10000).
useraddressyesWallet that will sign the tx.
useNativeInbooleannoOverride native-in detection.
unwrapNativeOutbooleannoReceive native ETH instead of WETH.
feeBpsintegernoIntegrator fee in bps.
maxHopsintegernoDefault 3.
splitEnabledbooleannoDefault true.
enforcePoolDisjointbooleannoDefault false.
allowedDexesarray of DexIdnoRestrict routing to specific venues.
permitobjectnoEIP-2612 permit payload (same shape as /submit).
See POST /quote and POST /submit for full descriptions of each field.

​
Response

{
  "quoteId": "a1b2c3d4e5f6...",
  "chainId": 8453,
  "to": "0xe56e22354DDdc07cF2dfbCFb53a90fB0a56E50D5",
  "data": "0x...",
  "value": "0",
  "expiresAt": 1712180000000,
  "routePlan": {
    "chainId": 8453,
    "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "tokenOut": "0x4200000000000000000000000000000000000006",
    "amountIn": "1000000000",
    "expectedAmountOut": "484446072048780734",
    "minAmountOut": "479601611328292926",
    "slippageBps": 100,
    "blockNumber": 44266656,
    "routes": [ /* ... */ ]
  }
}

​
Response fields

A union of the /quote response (so you can display the price) and /submit response (so you can broadcast).
FieldTypeDescription
quoteIdstringThe freshly issued quote ID. Useful for log correlation.
chainIdinteger8453.
toaddressAlways the O1Router.
datahexswapExactIn(...) calldata.
valuestringmsg.value in wei.
expiresAtintegerUnix milliseconds at which the cached quote drops.
routePlanobjectFull 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

Response

Quote + transaction payload

​
quoteId
string
required
​
chainId
integer
required
​
to
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
​
expiresAt
integer<int64>
required