Build Swap Transaction

POST /swap | Auth: Required

Build an unsigned swap transaction. The response contains raw transaction data that the caller must sign and submit to the blockchain. This endpoint does not execute the swap -- it only prepares the transaction.

For server-side signing with managed wallets, use POST /swap/execute instead (not covered in this reference).

Request

Body

There are two usage modes:

Mode 1: Using a quote (recommended)

Field	Type	Required	Description
quote_id	string	Yes	Quote ID from POST /quote. Must not be expired (60s TTL).
wallet_address	string	Yes	Address that will sign and submit the transaction.

Mode 2: Direct swap (no quote)

Field	Type	Required	Description
wallet_address	string	Yes	Address that will sign and submit the transaction.
from_token	string	Yes	Source token symbol.
to_token	string	Yes	Destination token symbol.
amount	string	Yes	Human-readable amount to swap.
chain	string	No	Chain key. Defaults to "ethereum".
slippage	number	No	Max slippage as a decimal (0-1). Default: 0.03.

Example (With Quote)

{
  "hl-key">"quote_id": "qt_8f3a9b2c1d4e5f6a7b8c9d0e",
  "hl-key">"wallet_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

Example (Direct)

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

Response

Status: 200 OK

Fields

Field	Type	Description
success	boolean	Always true.
transaction.to	string	Contract address to send the transaction to.
transaction.data	string	Hex-encoded calldata.
transaction.value	string	Native token value in wei (hex-encoded). "0x0" for ERC-20 to ERC-20 swaps.
transaction.gas_estimate	string	Estimated gas limit (hex-encoded).
transaction.chain_id	number	Chain ID for the transaction.
meta.from_token	string	Source token symbol.
meta.to_token	string	Destination token symbol.
meta.amount_in	string	Human-readable input amount.
meta.expected_out	string	Human-readable expected output amount.
meta.min_out	string	Minimum output after slippage.

Example

{
  "hl-key">"success": true,
  "hl-key">"transaction": {
    "hl-key">"to": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
    "hl-key">"data": "0x3593564c000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a0...",
    "hl-key">"value": "0x6f05b59d3b20000",
    "hl-key">"gas_estimate": "0x3d090",
    "hl-key">"chain_id": 8453
  },
  "hl-key">"meta": {
    "hl-key">"from_token": "ETH",
    "hl-key">"to_token": "USDC",
    "hl-key">"amount_in": "0.5",
    "hl-key">"expected_out": "1748.21",
    "hl-key">"min_out": "1730.73"
  }
}

Important: The response contains an unsigned transaction. You must sign it with the private key of wallet_address and broadcast it to the chain yourself.

Errors

Status	Error	Description
400	"wallet_address is required"	Missing required field.
400	"Provide quote_id or (from_token, to_token, amount)"	Neither a quote ID nor direct swap parameters were provided.
400	"Quote has expired"	The quote_id is older than 60 seconds. Request a new quote.
400	"Invalid quote_id"	The quote_id does not exist.
400	"Insufficient liquidity for this trade"	The swap cannot be completed at the requested size.
400	"Unknown token 'XYZ' on chain 'base'"	Token not supported on the specified chain.
401	"Invalid or missing API key"	The API key is missing, malformed, or revoked.

Code Examples

curl

-str">"hl-comment"># Using a quote
-kw">curl -X POST https://api.suwappu.bot/v1/agent/swap \
  -H -str">"Authorization: Bearer suwappu_sk_your_api_key" \
  -H -str">"Content-Type: application/json" \
  -d -str">'{
    -str">"quote_id": -str">"qt_8f3a9b2c1d4e5f6a7b8c9d0e",
    -str">"wallet_address": -str">"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  }'

Python

import requests

class=class="hl-str">"hl-comment"># Step 1: Get a quote
quote_resp = 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",
    },
)
quote = quote_resp.json()

class=class="hl-str">"hl-comment"># Step 2: Build the swap transaction
swap_resp = requests.post(
    class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/swap",
    headers={class="hl-str">"Authorization": class="hl-str">"Bearer suwappu_sk_your_api_key"},
    json={
        class="hl-str">"quote_id": quote[class="hl-str">"quote_id"],
        class="hl-str">"wallet_address": class="hl-str">"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    },
)
swap = swap_resp.json()

tx = swap[class="hl-str">"transaction"]
print(fclass="hl-str">"Send tx to: {tx[class="hl-str">'to']}")
print(fclass="hl-str">"Value: {tx[class="hl-str">'value']}")
print(fclass="hl-str">"Expected out: {swap[class="hl-str">'meta'][class="hl-str">'expected_out']} USDC")

class=class="hl-str">"hl-comment"># Step 3: Sign and submit the transaction using your web3 library
class=class="hl-str">"hl-comment"># e.g., web3.eth.account.sign_transaction(tx, private_key)

TypeScript

class=class="hl-str">"hl-comment">// Step 1: Get a quote
const quoteResp = 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",
  }),
});
const quote = await quoteResp.json();

class=class="hl-str">"hl-comment">// Step 2: Build the swap transaction
const swapResp = await fetch(class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/swap", {
  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({
    quote_id: quote.quote_id,
    wallet_address: class="hl-str">"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  }),
});
const swap = await swapResp.json();

console.log(Send tx to: ${swap.transaction.to});
console.log(Expected out: ${swap.meta.expected_out} USDC);

class=class="hl-str">"hl-comment">// Step 3: Sign and submit using your wallet/signer
class=class="hl-str">"hl-comment">// e.g., await signer.sendTransaction(swap.transaction);