Skip to main content
Use swap and bridge 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. 
async quote(request: SwidgeQuoteRequest): Promise<SwidgeQuoteResponse>
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”)
Response:
  • success (boolean): Whether the quote was retrieved
  • data (object): Quote data (on success)
    • engine (string): Routing engine used (e.g., "lifi", "relay", "hypercore")
    • 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
  • error (string | null): Error message if quote failed
Example: 
const quote = await agent.swidge.quote({
  from: { network: "ethereum:137", address: agent.sessionWalletAddress },
  to: { network: "ethereum:137", address: agent.sessionWalletAddress },
  amount: "1000000", // 1 USDC (6 decimals)
  fromToken: "0x2791bca1f2de4661ed88a30c99a7a9449aa84174", // USDC
  toToken: "0xd93f7e271cb87c23aaa73edc008a79646d1f9912", // wSOL
  slippage: "10.0"
});

if (quote.success && quote.data) {
  if (quote.data.assetReceive.amountFormatted) {
    await agent.log(`You'll receive: ${quote.data.assetReceive.amountFormatted}`);
  }
  if (quote.data.priceImpact.percentage) {
    await agent.log(`Price impact: ${quote.data.priceImpact.percentage}%`);

    // Validate price impact
    if (Math.abs(parseFloat(quote.data.priceImpact.percentage)) > 10) {
      await agent.log("Price impact too high", { error: true });
      return;
    }
  }
}

​
Execute Quote

Execute a swap using a quote. 
async execute(quoteData: SwidgeQuoteData | SwidgeQuoteData[]): Promise<SwidgeExecuteResponse | SwidgeExecuteResponse[]>
Parameters:
  • quoteData: Complete quote object from quote(), or array of quotes for bulk execution
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 && quote.data) {
  const result = await agent.swidge.execute(quote.data);

  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

Execute multiple swaps in parallel by passing an array of quotes: 
const results = await agent.swidge.execute([quote1.data, quote2.data]);
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

Circuit queries multiple routing engines and selects the best route automatically.
EngineSupported Networks
relayEVM chains, Solana, Hyperliquid
lifiEVM chains (cross-chain and same-chain)

​
Notes

  • Always validate quotes before executing. Check price impact and slippage.
  • 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.swidge.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.swidge import SwidgeQuoteRequest, SwidgeWallet
quote = agent.swidge.quote(SwidgeQuoteRequest(
    from_=SwidgeWallet(network="ethereum:137", address=agent.sessionWalletAddress),
    to=SwidgeWallet(network="ethereum:137", address=agent.sessionWalletAddress),
    amount="1000000",
))