Get Quote

POST /quote | Auth: Required

Get a swap quote with estimated output amount and exchange rate. The returned quote_id can be passed to POST /swap to execute the trade without re-specifying parameters.

Request

Body

Field	Type	Required	Description
from_token	string	Yes	Source token symbol (e.g., "ETH", "USDC").
to_token	string	Yes	Destination token symbol (e.g., "USDC", "DAI").
amount	string	Yes	Human-readable amount to swap (e.g., "0.5", "1000"). Not in smallest units.
chain	string	No	Chain key for same-chain swaps. Defaults to "ethereum".
from_chain	string	No	Source chain for cross-chain swaps. Overrides chain for the source side.
to_chain	string	No	Destination chain for cross-chain swaps. Overrides chain for the destination side.
wallet_address	string	No	Wallet address to tailor the quote (e.g., for gas estimation).
slippage	number	No	Maximum acceptable slippage as a decimal between 0 and 1. Default: 0.03 (3%).

For same-chain swaps, use chain. For cross-chain swaps, use from_chain and to_chain instead.

Example (Same-Chain)

{
  "hl-key">"from_token": "ETH",
  "hl-key">"to_token": "USDC",
  "hl-key">"amount": "0.5",
  "hl-key">"chain": "base",
  "hl-key">"slippage": 0.01
}

Example (Cross-Chain)

{
  "hl-key">"from_token": "ETH",
  "hl-key">"to_token": "USDC",
  "hl-key">"amount": "1.0",
  "hl-key">"from_chain": "ethereum",
  "hl-key">"to_chain": "base",
  "hl-key">"wallet_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

Response

Status: 200 OK

Fields

Field	Type	Description
success	boolean	Always true.
quote_id	string	Unique quote identifier. Valid for 60 seconds. Pass to POST /swap to execute.
from_token.symbol	string	Source token symbol.
from_token.chain	string	Source chain key.
from_token.address	string	Source token contract address.
to_token.symbol	string	Destination token symbol.
to_token.chain	string	Destination chain key.
to_token.address	string	Destination token contract address.
amount_in	string	Amount of source token to be swapped (human-readable).
amount_out	string	Estimated amount of destination token to be received (human-readable).
exchange_rate	string	Rate of to_token per from_token.
expires_in_seconds	number	Seconds until this quote expires. Always 60.

Example

{
  "hl-key">"success": true,
  "hl-key">"quote_id": "qt_8f3a9b2c1d4e5f6a7b8c9d0e",
  "hl-key">"from_token": {
    "hl-key">"symbol": "ETH",
    "hl-key">"chain": "base",
    "hl-key">"address": "0x0000000000000000000000000000000000000000"
  },
  "hl-key">"to_token": {
    "hl-key">"symbol": "USDC",
    "hl-key">"chain": "base",
    "hl-key">"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "hl-key">"amount_in": "0.5",
  "hl-key">"amount_out": "1748.21",
  "hl-key">"exchange_rate": "3496.42",
  "hl-key">"expires_in_seconds": 60
}

Note: The quote_id is valid for 60 seconds. After expiry, you must request a new quote.

Errors

Status	Error	Description
400	"from_token is required"	Missing required field.
400	"Unknown token 'XYZ' on chain 'base'"	The specified token is not available on the given chain.
400	"Unknown chain 'xyz'"	The specified chain is not supported.
400	"Amount must be a positive number"	The amount value is not a valid positive number.
400	"Slippage must be between 0 and 1"	The slippage value is out of range.
400	"Cross-chain route not available"	No route exists between the specified chains for these tokens.
401	"Invalid or missing API key"	The API key is missing, malformed, or revoked.

Code Examples

curl

-kw">curl -X POST https://api.suwappu.bot/v1/agent/quote \
  -H -str">"Authorization: Bearer suwappu_sk_your_api_key" \
  -H -str">"Content-Type: application/json" \
  -d -str">'{
    -str">"from_token": -str">"ETH",
    -str">"to_token": -str">"USDC",
    -str">"amount": -str">"0.5",
    -str">"chain": -str">"base",
    -str">"slippage": 0.01
  }'

Python

import requests

response = requests.post(
    class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/quote",
    headers={class="hl-str">"Authorization": class="hl-str">"Bearer suwappu_sk_your_api_key"},
    json={
        class="hl-str">"from_token": class="hl-str">"ETH",
        class="hl-str">"to_token": class="hl-str">"USDC",
        class="hl-str">"amount": class="hl-str">"0.5",
        class="hl-str">"chain": class="hl-str">"base",
        class="hl-str">"slippage": 0.01,
    },
)

data = response.json()
print(fclass="hl-str">"Quote ID: {data[class="hl-str">'quote_id']}")
print(fclass="hl-str">"Rate: 1 {data[class="hl-str">'from_token'][class="hl-str">'symbol']} = {data[class="hl-str">'exchange_rate']} {data[class="hl-str">'to_token'][class="hl-str">'symbol']}")
print(fclass="hl-str">"You receive: {data[class="hl-str">'amount_out']} {data[class="hl-str">'to_token'][class="hl-str">'symbol']}")
print(fclass="hl-str">"Expires in: {data[class="hl-str">'expires_in_seconds']}s")

TypeScript

const response = await fetch(class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/quote", {
  method: class="hl-str">"POST",
  headers: {
    Authorization: class="hl-str">"Bearer suwappu_sk_your_api_key",
    class="hl-str">"Content-Type": class="hl-str">"application/json",
  },
  body: JSON.stringify({
    from_token: class="hl-str">"ETH",
    to_token: class="hl-str">"USDC",
    amount: class="hl-str">"0.5",
    chain: class="hl-str">"base",
    slippage: 0.01,
  }),
});

const data = await response.json();
console.log(Quote ID: ${data.quote_id});
console.log(You receive: ${data.amount_out} ${data.to_token.symbol});
console.log(Expires in: ${data.expires_in_seconds}s);