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
}
'

import requests

url = "https://quiet-bloodhound-531.convex.site/execute"

payload = {
    "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
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://quiet-bloodhound-531.convex.site/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://quiet-bloodhound-531.convex.site/execute",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://quiet-bloodhound-531.convex.site/execute"

	payload := strings.NewReader("{\n  \"chainId\": 2,\n  \"tokenIn\": \"<string>\",\n  \"tokenOut\": \"<string>\",\n  \"amountIn\": \"<string>\",\n  \"slippageBps\": 5000,\n  \"user\": \"<string>\",\n  \"maxHops\": 2,\n  \"splitEnabled\": true,\n  \"enforcePoolDisjoint\": true,\n  \"allowedDexes\": [],\n  \"feeBps\": 5000,\n  \"useNativeIn\": true,\n  \"unwrapNativeOut\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://quiet-bloodhound-531.convex.site/execute")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chainId\": 2,\n  \"tokenIn\": \"<string>\",\n  \"tokenOut\": \"<string>\",\n  \"amountIn\": \"<string>\",\n  \"slippageBps\": 5000,\n  \"user\": \"<string>\",\n  \"maxHops\": 2,\n  \"splitEnabled\": true,\n  \"enforcePoolDisjoint\": true,\n  \"allowedDexes\": [],\n  \"feeBps\": 5000,\n  \"useNativeIn\": true,\n  \"unwrapNativeOut\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://quiet-bloodhound-531.convex.site/execute")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"chainId\": 2,\n  \"tokenIn\": \"<string>\",\n  \"tokenOut\": \"<string>\",\n  \"amountIn\": \"<string>\",\n  \"slippageBps\": 5000,\n  \"user\": \"<string>\",\n  \"maxHops\": 2,\n  \"splitEnabled\": true,\n  \"enforcePoolDisjoint\": true,\n  \"allowedDexes\": [],\n  \"feeBps\": 5000,\n  \"useNativeIn\": true,\n  \"unwrapNativeOut\": true\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

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
}
'

import requests

url = "https://quiet-bloodhound-531.convex.site/execute"

payload = {
    "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
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://quiet-bloodhound-531.convex.site/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://quiet-bloodhound-531.convex.site/execute",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://quiet-bloodhound-531.convex.site/execute"

	payload := strings.NewReader("{\n  \"chainId\": 2,\n  \"tokenIn\": \"<string>\",\n  \"tokenOut\": \"<string>\",\n  \"amountIn\": \"<string>\",\n  \"slippageBps\": 5000,\n  \"user\": \"<string>\",\n  \"maxHops\": 2,\n  \"splitEnabled\": true,\n  \"enforcePoolDisjoint\": true,\n  \"allowedDexes\": [],\n  \"feeBps\": 5000,\n  \"useNativeIn\": true,\n  \"unwrapNativeOut\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://quiet-bloodhound-531.convex.site/execute")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chainId\": 2,\n  \"tokenIn\": \"<string>\",\n  \"tokenOut\": \"<string>\",\n  \"amountIn\": \"<string>\",\n  \"slippageBps\": 5000,\n  \"user\": \"<string>\",\n  \"maxHops\": 2,\n  \"splitEnabled\": true,\n  \"enforcePoolDisjoint\": true,\n  \"allowedDexes\": [],\n  \"feeBps\": 5000,\n  \"useNativeIn\": true,\n  \"unwrapNativeOut\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://quiet-bloodhound-531.convex.site/execute")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"chainId\": 2,\n  \"tokenIn\": \"<string>\",\n  \"tokenOut\": \"<string>\",\n  \"amountIn\": \"<string>\",\n  \"slippageBps\": 5000,\n  \"user\": \"<string>\",\n  \"maxHops\": 2,\n  \"splitEnabled\": true,\n  \"enforcePoolDisjoint\": true,\n  \"allowedDexes\": [],\n  \"feeBps\": 5000,\n  \"useNativeIn\": true,\n  \"unwrapNativeOut\": true\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

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

curl -X POST https://quiet-bloodhound-531.convex.site/execute \
  -H "x-api-key: $O1_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "chainId": 8453,
    "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "tokenOut": "0x4200000000000000000000000000000000000006",
    "amountIn": "1000000000",
    "slippageBps": 100,
    "user": "0xYourWalletAddress"
  }'

/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

Overview

Getting Started

Features

API

Native Token: $O

Community

Request

Body parameters

Response

Response fields

Examples

Authorizations

Body

Response

​Request

​Body parameters

​Response

​Response fields

​Examples

Authorizations

Body

Response

Request

Body parameters

Response

Response fields

Examples