Swidge (swaps + bridges)

Cross-chain token swaps and bridges using Circuit's swap engine. The engine automatically selects the best route across multiple liquidity sources.

Workflow

1. Get a quote with quote()

2. Execute the swap with execute()

3. Check execution status

Get Quote

Get pricing and routing information for a swap.

TypeScript

async quote(request: SwidgeQuoteRequest): Promise<SwidgeQuoteResponse>

Python

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): Constrain which engines to query. If omitted, all available engines are queried and the best route is selected.

Response:

• success (boolean): Whether the quote was retrieved

• data (object): Quote data with asset details, fees, and steps

• error (string | null): Error message if quote failed

Example:

TypeScript

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;
    }
  }
}

Python

Execute Quote

Execute a swap using a quote.

TypeScript

async execute(quoteData: SwidgeQuoteData | SwidgeQuoteData[]): Promise<SwidgeExecuteResponse | SwidgeExecuteResponse[]>

Python

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:

TypeScript

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 || result.errorMessage || "Execute failed", { error: true });
  }
}

Python

Bulk Execution

Execute multiple swaps in parallel by passing an array of quotes:

TypeScript

const results = await agent.swidge.execute([quote1.data, quote2.data]);
results.forEach((result, index) => {
  if (result.success && result.data) {
    await agent.log(`Swap ${index + 1} status: ${result.data.status}`);
  }
});

Python

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. The API waits for completion and never returns "pending" or "waiting".