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: str; address: str },
        to: { network: str; address: str },
        amount: str,
        fromToken: str | None,
        toToken: str | None,
        slippage: str | None
    }
) -> SwidgeQuoteResponse

Parameters

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

Returns

• SwidgeQuoteResponse

class SwidgeQuoteResponse:
    success: bool
    data: {
        engine: "relay",
        assetSend: {
            network: str,
            address: str,
            token: str | None,
            symbol: str | None,
            amount: str | None,
            amountFormatted: str | None,
            amountUsd: str | None
        },
        assetReceive: {
            network: str,
            address: str,
            token: str | None,
            symbol: str | None,
            amount: str | None,
            amountFormatted: str | None,
            amountUsd: str | None
        },
        priceImpact: {
            usd: str | None,
            percentage: str | None
        },
        fees: list[{
            name: str,
            amount: str | None,
            amountFormatted: str | None,
            amountUsd: str | None
        }],
        steps: list  # Transaction steps
    } | None
    error: str | None
    error_details: dict | None

Examples

Bridge USDC: Polygon to Arbitrum

quote = 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 and quote.data:
    agent.log(f"You'll receive: {quote.data.assetReceive.amountFormatted}")
    agent.log(f"Price impact: {quote.data.priceImpact.percentage}%")

Swap USDC to ETH on Arbitrum

quote = 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 and quote.data:
    agent.log(f"Total fees: {', '.join([f.name for f in quote.data.fees])}")

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: SwidgeData
) -> SwidgeExecuteResponse

Parameters

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

Returns

• SwidgeExecuteResponse

class SwidgeExecuteResponse:
    success: bool
    data: {
        status: "success" | "failure" | "refund" | "delayed",
        in_: {
            network: str,
            txs: list[str]  # Source transaction hashes
        },
        out: {
            network: str,
            txs: list[str]  # Destination transaction hashes
        },
        lastUpdated: int
    } | None
    error: str | None
    error_details: dict | None

Examples

# 1. Get a quote first
quote = 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 and quote.data:
    result = agent.swidge.execute(quote.data)

    if result.success and result.data:
        agent.log(f"Status: {result.data.status}")

        if result.data.status == "success":
            agent.log(f"Sent: {result.data.in_.txs[0]}")
            agent.log(f"Received: {result.data.out.txs[0]}")
            agent.log("Cross-chain swap completed!")
        elif result.data.status == "failure":
            agent.log("Transaction failed", error=True)
        elif result.data.status == "refund":
            agent.log("Transaction was refunded")
        elif result.data.status == "delayed":
            agent.log("Transaction is delayed")
    else:
        agent.log(f"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