swidge

The swidge namespace provides cross-chain swap and bridge functionality. Bridge assets between chains or swap tokens on the same network with automatic routing and competitive fees. Supports all major EVM chains (Ethereum, Arbitrum, Polygon, etc.) and Solana.

Important notes:

• Validate quotes before executing. Circuit only filters price impact >100%. Check quotes against your own risk thresholds.

• Minimum $10-20 recommended to avoid fee issues

• Adjust slippage: 0.5% default, 1-2% for volatile/cross-chain

• Same network = swap; different networks = bridge

• Omit fromToken/toToken for native tokens

swidge.quote()

Get pricing and routing information for swapping tokens between networks or within the same network.

Signature

agent.swidge.quote(
  request: {
    from: { network: string; address: string };
    to: { network: string; address: string };
    amount: string;
    fromToken?: string;
    toToken?: string;
    slippage?: string;
  }
): Promise<SwidgeQuoteResponse>

Parameters

Param	Type	Description
request	object	Quote request configuration
request.from	object	Source wallet details
request.from.network	string	Source network; 'ethereum:{chainId}' | 'solana'
request.from.address	string	Source wallet address
request.to	object	Destination wallet details
request.to.network	string	Destination network; 'ethereum:{chainId}' | 'solana'
request.to.address	string	Destination wallet address
request.amount	string	Amount in smallest unit (wei, lamports, etc.)
request.fromToken?	string	Source token contract (omit for native tokens)
request.toToken?	string	Destination token contract (omit for native tokens)
request.slippage?	string	Slippage tolerance % (default: "0.5")

Returns

• Promise<SwidgeQuoteResponse>

type SwidgeQuoteResponse = {
  success: boolean;
  data?: {
    engine: "relay";
    assetSend: {
      network: string;
      address: string;
      token: string | null;
      name?: string;
      symbol?: string;
      decimals?: number;
      amount?: string;
      amountFormatted?: string;
      amountUsd?: string;
    };
    assetReceive: {
      network: string;
      address: string;
      token: string | null;
      name?: string;
      symbol?: string;
      decimals?: number;
      amount?: string;
      amountFormatted?: string;
      amountUsd?: string;
    };
    priceImpact: {
      usd?: string;
      percentage?: string;
    };
    fees: Array<{
      name: string;
      amount?: string;
      amountFormatted?: string;
      amountUsd?: string;
    }>;
    steps: Array<any>;  // Transaction steps
  };
  error?: string;
  errorMessage?: string;
  errorDetails?: object;
}

Examples

Bridge USDC: Polygon to Arbitrum

const quote = await agent.swidge.quote({
  from: { 
    network: "ethereum:137", 
    address: agent.sessionWalletAddress 
  },
  to: { 
    network: "ethereum:42161", 
    address: agent.sessionWalletAddress 
  },
  amount: "50000000", // $50 USDC (6 decimals)
  fromToken: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", // USDC on Polygon
  toToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",   // USDC on Arbitrum
  slippage: "2.0", // 2% slippage for cross-chain
});

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

Swap USDC to ETH on Arbitrum

const quote = await agent.swidge.quote({
  from: { 
    network: "ethereum:42161", 
    address: agent.sessionWalletAddress 
  },
  to: { 
    network: "ethereum:42161", 
    address: agent.sessionWalletAddress 
  },
  amount: "100000000", // $100 USDC (6 decimals)
  fromToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC
  // toToken omitted = native ETH
});

if (quote.success && quote.data) {
  await agent.log(`Total fees: ${quote.data.fees.map(f => f.name).join(", ")}`);
}

Common Errors

Error	Cause	Solution
"Quote failed"	Amount too small, insufficient liquidity	Use at least $10-20 worth of tokens
"Invalid token address"	Token doesn't exist on network	Verify token address on block explorer
"Price impact too high"	Slippage >100% (auto-filtered by Circuit)	Reduce amount or increase slippage
"Unsupported network"	Network not supported by Swidge	Check supported networks list
"No route found"	No path between tokens/chains	Try different token pair or amount

swidge.execute()

Execute a cross-chain swap or bridge using a quote from agent.swidge.quote(). Signs transactions, broadcasts them, and waits for completion.

Signature

agent.swidge.execute(
  quote: SwidgeExecuteRequest
): Promise<SwidgeExecuteResponse>

Parameters

Param	Type	Description
quote	SwidgeExecuteRequest	Complete quote object from swidge.quote() (the data field)

Returns

• Promise<SwidgeExecuteResponse>

type SwidgeExecuteResponse = {
  success: boolean;
  data?: {
    status: "success" | "failure" | "refund" | "delayed";
    in: {
      network: string;
      txs: string[];  // Source transaction hashes
    };
    out: {
      network: string;
      txs: string[];  // Destination transaction hashes
    };
    lastUpdated: number;
  };
  error?: string;
  errorMessage?: string;
  errorDetails?: object;
}

Examples

// 1. Get a quote first
const quote = await agent.swidge.quote({
  from: { network: "ethereum:137", address: agent.sessionWalletAddress },
  to: { network: "ethereum:42161", address: agent.sessionWalletAddress },
  amount: "50000000", // $50 USDC
  fromToken: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  toToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
});

// 2. Execute the swap
if (quote.success && quote.data) {
  const result = await agent.swidge.execute(quote.data);

  if (result.success && result.data) {
    await agent.log(`Status: ${result.data.status}`);

    if (result.data.status === "success") {
      await agent.log(`Sent: ${result.data.in.txs[0]}`);
      await agent.log(`Received: ${result.data.out.txs[0]}`);
      await agent.log("Cross-chain swap completed!");
    } else if (result.data.status === "failure") {
      await agent.log("Transaction failed", { error: true });
    } else if (result.data.status === "refund") {
      await agent.log("Transaction was refunded");
    } else if (result.data.status === "delayed") {
      await agent.log("Transaction is delayed");
    }
  } else {
    await agent.log(`Execute failed: ${result.error}`, { error: true });
  }
}

Common Errors

Error	Cause	Solution
"Execution failed"	Insufficient balance for swap	Verify currentPositions has enough tokens
"Quote expired"	Quote too old (prices changed)	Get fresh quote before executing
"Slippage exceeded"	Price moved beyond slippage tolerance	Increase slippage or get new quote
"Transaction reverted"	Gas estimation failed, approval issues	Check allowances and gas availability