Payment Fallback

Learn how AgentBank's intelligent fallback system ensures your payments always go through, even when networks are congested or unavailable.

How It Works

The x402 protocol implements a sophisticated fallback mechanism that automatically routes payments to alternative blockchains when the primary chain fails or is too expensive. This ensures maximum reliability for autonomous AI agents.

Fallback Triggers

AgentBank will automatically fallback to the next chain when:

  • Network Congestion: Gas prices exceed your configured threshold
  • Transaction Timeout: Transaction doesn't confirm within the timeout period
  • RPC Failure: The blockchain RPC endpoint is unavailable
  • Insufficient Balance: Not enough funds on the current chain

Configuration

You can customize the fallback behavior when initializing the client:

import { AgentBank } from 'agentbank-sdk'

const bank = new AgentBank({
  apiKey: process.env.AGENTBANK_API_KEY,
  fallback: {
    // Maximum gas price in gwei before fallback
    maxGasPrice: 100,
    // Timeout before trying next chain (ms)
    timeout: 30000,
    // Maximum retry attempts per chain
    maxRetries: 3,
    // Delay between retries (ms)
    retryDelay: 1000
  }
})

Chain Priority

When you specify multiple chains, AgentBank tries them in order. You can customize the priority based on your needs:

// Cost-optimized: Try cheaper chains first
const result = await bank.pay({
  amount: 100,
  currency: 'USDC',
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  chains: ['polygon', 'arbitrum', 'ethereum']
})

// Speed-optimized: Try fastest chains first
const result = await bank.pay({
  amount: 100,
  currency: 'USDC',
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  chains: ['solana', 'arbitrum', 'polygon']
})

Important Note

Make sure you have sufficient balance on multiple chains to take full advantage of the fallback system. The SDK will skip chains where you don't have enough funds.

Monitoring Fallbacks

You can track when fallbacks occur by listening to events:

bank.on('fallback', (event) => {
  console.log('Fallback triggered:', {
    fromChain: event.fromChain,
    toChain: event.toChain,
    reason: event.reason,
    attempt: event.attempt
  })
})

bank.on('payment:success', (event) => {
  console.log('Payment completed:', {
    chain: event.chain,
    txHash: event.txHash,
    attempts: event.attempts
  })
})

Best Practices

  • Always specify at least 2-3 fallback chains for maximum reliability
  • Order chains based on your priority (cost vs speed vs reliability)
  • Monitor fallback events to understand network conditions
  • Keep sufficient balance across multiple chains
  • Set appropriate timeout values based on your use case