Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

Use swap to move tokens between chains or swap between assets on the same chain. This is the primary way most agents rebalance portfolios, enter/exit positions, or convert between tokens.

​
Workflow

  1. Get a quote with quote()
  2. Execute the swap with execute()
  3. Check data.status in the response

​
Get Quote

Get pricing and routing information for a swap. 
def quote(request: SwapQuoteRequest | dict) -> SwapQuoteResponse
Request Parameters:
  • 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”)
  • engines (string[], optional): Restrict routing to specific engines ("uniswap", "lifi", "relay")
Response:
  • success (boolean): Whether the quote was retrieved
  • data (object): Quote data (on success)
    • engine (string): Routing engine used (e.g., "uniswap", "lifi", "relay")
    • engines (string[], optional): Original routing engine filter when one was requested
    • assetSend (object): Source asset details
      • network (string): Network identifier
      • token (string | null): Token address (null for native)
      • 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): Total value in USD
    • assetReceive (object): Destination asset details (same shape as assetSend)
    • priceImpact (object): Price impact info
      • percentage (string): Price impact as a percentage
      • usd (string, optional): Price impact in USD
    • fees (array): Fee breakdown
      • name (string): Fee label
      • amount (string, optional): Fee amount in smallest units
      • amountFormatted (string, optional): Human-readable fee
      • amountUsd (string, optional): Fee value in USD
    • 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
      • signature (string, optional): Server signature used to reject tampered freshness metadata
  • error (string | null): Error message if quote failed
Example: 
quote = agent.swap.quote({
    "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",
})

if quote.success and quote.data:
    if quote.data.assetReceive.amountFormatted:
        agent.log(f"You'll receive: {quote.data.assetReceive.amountFormatted}")
    if quote.data.priceImpact.percentage:
        agent.log(f"Price impact: {quote.data.priceImpact.percentage}%")

        # Validate price impact
        if abs(float(quote.data.priceImpact.percentage)) > 10:
            agent.log("Price impact too high", error=True)
            return

​
Execute Quote

Execute a swap using a quote. 
def execute(quote_data: SwapData | list[SwapData]) -> SwapExecuteResponse | list[SwapExecuteResponse]
Parameters:
  • quoteData: Complete quote object from quote(), or array of quotes for bulk execution
  • expiresAt (string | null, optional): ISO 8601 timestamp. In manual mode, the suggestion is discarded if not approved by this time. If omitted, no time-based expiry is set (all suggestions are auto-cleared at the start of each run cycle regardless).
Response:
  • 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)
Example: 
if quote.success and quote.data:
    result = agent.swap.execute(quote.data)

    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)

​
Bulk Execution

Execute multiple swaps in parallel by passing an array of quotes: 
results = agent.swap.execute([quote1.data, quote2.data])
for index, result in enumerate(results):
    if result.success and result.data:
        agent.log(f"Swap {index + 1} status: {result.data.status}")

​
Routing Engines

Circuit queries multiple routing engines and selects the best route automatically. Same-chain EVM swaps prefer Uniswap when it can return an executable route, then fall back to LiFi.
EngineSupported Networks
uniswapSame-chain swaps on supported EVM chains
relayEVM chains, Solana, Hyperliquid
lifiEVM chains, Solana

​
Notes

  • Always validate quotes before executing. Check price impact and slippage.
  • Execute quotes promptly. Expired quotes are rejected with QUOTE_STALE; request a fresh quote and retry.
  • Circuit filters quotes with price impact exceeding 100%. Agents should validate returned quotes based on their own parameters.
  • 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

In manual mode, execute() returns a suggestion instead of executing. The response will have data.suggested = true and data.suggestionId.

​
See Also

​
Python: from Parameter

from is a reserved keyword in Python. Use the string key "from" in dicts (recommended), or from_ if using the Pydantic model directly.
from is a reserved keyword in Python. When passing a dict to quote(), use the string key "from" — it works because dict keys are strings. If using the Pydantic model directly, the field is from_: 
# Using a dict (recommended) — "from" works as a string key
quote = agent.swap.quote({
    "from": {"network": "ethereum:137", "address": agent.sessionWalletAddress},
    "to": {"network": "ethereum:137", "address": agent.sessionWalletAddress},
    "amount": "1000000",
})

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