Swap

​

Workflow

1. Build the swap limits
2. Optionally call quote() to preview pricing and routing
3. Pass the same limits to execute()
4. Check data.status in the response

​

Get Quote

def quote(request: SwapQuoteRequest | SwapQuoteRequestInput) -> SwapQuoteResponse

async quote(request: SwapQuoteRequest): Promise<SwapQuoteResponse>

• from (object): Source wallet { network, address }
• to (object): Destination wallet { network, address }
• amount (string): Amount in smallest unit (wei, lamports, etc.)
• fromToken (string | null, optional): Source token address (omit for native tokens)
• toToken (string | null, optional): Destination token address (omit for native tokens)
• slippage (string, optional): Slippage tolerance % as string (default: “0.5”)
• priceImpact (string, optional): Maximum acceptable price impact % as a string (default: “2”)
• engines (string[], optional): Restrict routing to specific engines - route providers ("relay", "lifi", "across", "kyberswap", "paraswap", "jupiter") and/or action adapters ("weth", "pusd", "erc4626", "hypercore-deposit")

• success (boolean): Whether the quote was retrieved
• data (object): Quote data (on success)
  • engine (string): Routing engine used (e.g., "relay", "lifi", "across", "kyberswap", "paraswap", "jupiter", "weth", "pusd", "erc4626")
  • engines (string[], optional): Original routing engine filter when one was requested
  • assetSend (object): Source asset details
    • network (string): Network identifier
    • address (string): Onchain token contract address (or the chain’s native-asset sentinel)
    • token (string): Token identifier
    • name (string): Token name
    • symbol (string): Token symbol
    • decimals (number): Token decimals
    • amount (string): Amount in smallest units
    • amountFormatted (string): Human-readable amount
    • amountUsd (string, optional): Approximate value in USD
  • assetReceive (object): Destination asset details (same shape as assetSend, plus an optional minimumAmount - the slippage floor in smallest units)
  • estimatedCost (object): Estimated route and asset-flow value loss
    • usd (string): Signed estimated cost in USD; positive means the operation costs the user value, while negative means favorable execution
    • percentage (string): The same signed estimated cost as a percentage
    • The estimate is starting USD minus ending USD. It includes costs already reflected in the received asset value and excludes separately paid network fees.
  • The former priceImpact response object is removed; read estimatedCost instead
  • fees (array): Separately paid network fee line items; these are not included in estimatedCost
    • name (string): Fee label
    • amount (string, optional): Fee amount in the token’s smallest units
    • amountFormatted (string, optional): Human-readable fee amount
    • amountUsd (string, optional): Approximate USD value of the fee
  • steps (array): Transaction steps to execute
  • quoteFreshness (object, optional): Quote expiry metadata
    • issuedAtMs (number): Quote issue time in milliseconds
    • ttlMs (number): Quote time-to-live in milliseconds
    • resolvedSlippage (string): Slippage value applied to this quote
    • minimumOutputAtIssue (string): Minimum output amount captured at quote time
  • slippage (string, optional): Slippage applied to the quote and preserved for execution re-quoting
  • maxPriceImpact (string, optional): Caller-supplied price-impact approval limit preserved for execution re-quoting
• error (string | null): Error message if quote failed

request = {
    "from": {
        "network": "ethereum:137",
        "address": agent.session_wallet_address,
    },
    "to": {
        "network": "ethereum:137",
        "address": agent.session_wallet_address,
    },
    "amount": "1000000",  # 1 USDC.e (6 decimals)
    "fromToken": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",  # USDC.e
    "toToken": "0xd93f7e271cb87c23aaa73edc008a79646d1f9912",  # wSOL
    "slippage": "10.0",
    "priceImpact": "10.0",
}
quote = agent.swap.quote(request)

if quote.success and quote.data:
    if quote.data.asset_receive.amount_formatted:
        agent.log(f"You'll receive: {quote.data.asset_receive.amount_formatted}")
    agent.log(
        f"Estimated cost: ${quote.data.estimated_cost.usd} "
        f"({quote.data.estimated_cost.percentage}%)"
    )
    for fee in quote.data.fees:
        agent.log(
            f"{fee.name}: {fee.amount_formatted or fee.amount or 'amount unavailable'}"
        )

const request = {
  from: { network: "ethereum:137", address: agent.sessionWalletAddress },
  to: { network: "ethereum:137", address: agent.sessionWalletAddress },
  amount: "1000000", // 1 USDC.e (6 decimals)
  fromToken: "0x2791bca1f2de4661ed88a30c99a7a9449aa84174", // USDC.e
  toToken: "0xd93f7e271cb87c23aaa73edc008a79646d1f9912", // wSOL
  slippage: "10.0",
  priceImpact: "10.0"
};
const quote = await agent.swap.quote(request);

if (quote.success && quote.data) {
  if (quote.data.assetReceive.amountFormatted) {
    await agent.log(`You'll receive: ${quote.data.assetReceive.amountFormatted}`);
  }
  await agent.log(
    `Estimated cost: $${quote.data.estimatedCost.usd} (${quote.data.estimatedCost.percentage}%)`
  );
  for (const fee of quote.data.fees) {
    await agent.log(
      `${fee.name}: ${fee.amountFormatted ?? fee.amount ?? "amount unavailable"}`
    );
  }
}

​

Execute

def execute(request: SwapExecuteRequest | list[SwapExecuteRequest]) -> SwapExecuteResponse | list[SwapExecuteResponse]

async execute(request: SwapExecuteRequest | SwapExecuteRequest[]): Promise<SwapExecuteResponse | SwapExecuteResponse[]>

• request: The quote request fields listed above, or an array of independent requests
• expiresAt (string | null): ISO 8601 timestamp. Use null for no time-based expiry.

• success (boolean): Whether execution started
• data.status (string): Execution status (“success”, “failure”, “refund”, “delayed”)
• data.in.txs (string[]): Input transaction hashes (on success)
• data.out.txs (string[]): Output transaction hashes (on success)
• error (string | null): Error message (on failure)

result = agent.swap.execute({**request, "expiresAt": None})

if result.success and result.data:
    agent.log(f"Swap status: {result.data.status}")
    if result.data.status == "success":
        agent.log("Swap completed")
        if result.data.in_ and result.data.in_.txs:
            agent.log(f"In tx: {result.data.in_.txs[0]}")
        if result.data.out and result.data.out.txs:
            agent.log(f"Out tx: {result.data.out.txs[0]}")
    elif result.data.status == "failure":
        agent.log("Swap failed", error=True)
else:
    agent.log(result.error or "Execute failed", error=True)

const result = await agent.swap.execute({ ...request, expiresAt: null });

if (result.success && result.data) {
  await agent.log(`Swap status: ${result.data.status}`);
  if (result.data.status === "success") {
    await agent.log("Swap completed");
    if (result.data.in?.txs?.[0]) {
      await agent.log(`In tx: ${result.data.in.txs[0]}`);
    }
    if (result.data.out?.txs?.[0]) {
      await agent.log(`Out tx: ${result.data.out.txs[0]}`);
    }
  } else if (result.data.status === "failure") {
    await agent.log("Swap failed", { error: true });
  }
} else {
  await agent.log(result.error || "Execute failed", { error: true });
}

​

Bulk Execution

results = agent.swap.execute([request1, request2])
for index, result in enumerate(results):
    if result.success and result.data:
        agent.log(f"Swap {index + 1} status: {result.data.status}")

const results = await agent.swap.execute([request1, request2]);
for (let i = 0; i < results.length; i++) {
  if (results[i].success && results[i].data) {
    await agent.log(`Swap ${i + 1} status: ${results[i].data.status}`);
  }
}

​

Routing Engines

​

Notes

• Validate the preview’s estimated cost and expected output before execution.
• Execution uses the source amount, endpoints, token addresses, slippage, engine filter, and request-side priceImpact cap as approval limits. It does not pin the preview’s receive amount.
• The engine rejects its own stale executable quotes before broadcast.
• Amounts are in smallest units (wei for ETH, lamports for SOL, etc.).
• Omit fromToken/toToken for native tokens (ETH, SOL).
• Execution status is final for same-chain swaps. For cross-chain bridges, the data.status field in the execute response indicates the final status: "success", "failure", "refund", or "delayed".

​

Manual Mode

​

See Also

• Positions - Check balances before and after swaps
• SDK Quick Reference - Network identifiers and native token addresses
• Error Handling - Swap-specific error codes
• Yield Agent Example - Full working agent using swap

​

Python: from Parameter

# Using a dict (recommended) - "from" works as a string key
quote = agent.swap.quote({
    "from": {"network": "ethereum:137", "address": agent.session_wallet_address},
    "to": {"network": "ethereum:137", "address": agent.session_wallet_address},
    "amount": "1000000",
})

# Using the Pydantic model - use from_ (with underscore)
from circuit_sdk.types.swap import SwapQuoteRequest, SwapWallet
quote = agent.swap.quote(SwapQuoteRequest(
    from_=SwapWallet(network="ethereum:137", address=agent.session_wallet_address),
    to=SwapWallet(network="ethereum:137", address=agent.session_wallet_address),
    amount="1000000",
))