switchboard. getting started

Switchboard is the wallet runtime for autonomous AI agents. It handles the three hardest parts of putting an agent on-chain:

• Agent wallets -- client-side nonce management with reorg protection, so a bursty agent never bricks its own transaction queue. Key custody via MPC or local keystore.
• Gas budgets -- rolling hourly and daily spend limits that auto-pause an agent before it drains its wallet. Configurable per-agent, per-chain.
• Agent-to-agent escrow payments -- on-chain escrow (AgentEscrow.sol) with timeout + challenge-period refund. One agent locks funds, the other delivers, and the payer confirms or the timeout triggers a refund.

Switchboard is not a payment rail. It sits underneath the open rails of April 2026 -- x402 (Linux Foundation), MPP (Tempo mainnet), AP2 (Google), Circle Nanopayments -- and manages the agent-side wallet state they all need.

Switchboard is a Python package. Install it from PyPI:

pip install switchboard-agent

Verify the install by importing the core modules:

python -c "from switchboard.gas_budget import GasBudgetTracker; from switchboard.payment_protocol import PaymentClient; print('switchboard OK')"

You should see switchboard OK. If not, make sure you are running Python 3.10+ and have web3 installed (pip install web3).

The GasBudgetTracker enforces rolling spend limits so your agent cannot accidentally drain its wallet on gas. You configure an hourly cap, a daily cap, and the tracker handles the rest -- including raising BudgetExhausted when a transaction would breach the limit.

from switchboard.gas_budget import GasBudgetTracker, BudgetExhausted

# Create a tracker with hourly and daily limits (in ETH)
tracker = GasBudgetTracker(
    hourly_limit=0.05,   # 0.05 ETH per rolling hour
    daily_limit=0.5,     # 0.5 ETH per rolling 24h
)

# Before sending a transaction, check if it fits
estimated_gas_cost = 0.003  # ETH

if tracker.fits(estimated_gas_cost):
    # Send the transaction via web3 / your wallet provider
    tx_hash = send_my_transaction()

    # Record the actual spend so the rolling window stays accurate
    tracker.record_spend(estimated_gas_cost)
    print(f"Sent tx {tx_hash}, budget remaining: {tracker.remaining_hourly()} ETH (hourly)")
else:
    print("Transaction would exceed budget -- skipping")

# Or use the strict mode that raises on breach
try:
    tracker.require_budget(0.06)  # exceeds hourly limit
except BudgetExhausted as e:
    print(f"Budget exhausted: {e}")
    # e.limit_type  -> "hourly" or "daily"
    # e.requested   -> 0.06
    # e.remaining   -> current remaining budget

The tracker uses a sliding window internally. Old spends roll off as time passes, so an agent that was paused at 2pm will automatically resume spending by 3pm if the hourly window clears.

The PaymentClient wraps the on-chain AgentEscrow.sol contract. It gives your agent a three-step flow: create escrow, the counterparty delivers work, and the payer confirms release. If the payer disappears, the payee can claim after the timeout + challenge period.

from switchboard.payment_protocol import PaymentClient

# Connect to your agent's wallet + the escrow contract
client = PaymentClient(
    rpc_url="https://rpc.mychain.example",
    private_key="0x...",
    escrow_address="0x...deployed_escrow...",
)

# Step 1: Lock funds in escrow for the payee agent
payment_id = client.create_payment(
    payee="0x...payee_agent_address...",
    amount_eth=0.1,
    timeout_blocks=100,
    challenge_period_blocks=10,
)
print(f"Escrow created: payment_id={payment_id}")

# Step 2: Wait for payee to deliver (off-chain coordination)
# ... your agent receives the work product ...

# Step 3: Confirm -- funds release to the payee
tx = client.confirm_payment(payment_id)
print(f"Payment confirmed, tx: {tx}")

# On the payee side, listen for incoming escrow payments
payee_client = PaymentClient(
    rpc_url="https://rpc.mychain.example",
    private_key="0x...payee_key...",
    escrow_address="0x...deployed_escrow...",
)

# Check payment status
status = payee_client.get_payment_status(payment_id)
print(f"Payment {payment_id}: {status.state}, amount={status.amount} ETH")

# If payer vanishes, claim after timeout + challenge period
if status.state == "timed_out":
    tx = payee_client.claim_timed_out(payment_id)
    print(f"Claimed timed-out escrow: {tx}")

x402 is the HTTP 402 Payment Required standard, now under the Linux Foundation (April 2026) with founding members including Google, AWS, Microsoft, Stripe, Visa, and Mastercard. When an API server responds 402, it includes a PaymentRequirements header describing the accepted payment scheme, asset, and amount.

Switchboard's upcoming x402 middleware (#16) will intercept 402 responses, sign the payment using the agent's managed wallet, and retry the request automatically -- all subject to the gas budget.

from switchboard.x402 import X402Client

# Wrap your agent's HTTP session with x402 auto-pay
session = X402Client(
    wallet=my_wallet,
    budget=tracker,   # GasBudgetTracker from step 3
)

# This request may trigger a 402 -- switchboard handles it
response = session.get("https://api.example.com/v1/premium-data")
# If the server sent 402 + PaymentRequirements:
#   1. switchboard checks budget.fits(amount)
#   2. signs a PAYMENT-SIGNATURE header with the agent wallet
#   3. retries the request
#   4. records the spend in the budget tracker
print(response.json())  # the paid-for resource

Track progress at issue #16. Explore the protocol flow visually at switchboard.kcolbchain.com.

MPP (Machine Payments Protocol) is co-authored by Stripe and Tempo, live on Tempo L1 mainnet since March 2026. Unlike per-request payments, MPP introduces a session: the agent authorises a spending cap upfront, then streams micro-payments without a separate transaction per interaction. Settlement happens once at session close.

Switchboard's MPP integration (#17) will bind the MPP session cap to the agent's gas budget. When you open a session with a $5 limit, switchboard ensures that $5 is deducted from the daily budget immediately, preventing over-commitment across multiple concurrent sessions.

from switchboard.mpp import MPPSession

# Open a session -- budget is reserved upfront
session = MPPSession(
    wallet=my_wallet,
    budget=tracker,
    limit_usd=5.00,
    ttl_seconds=3600,
)

# Stream micro-payments within the session
result = session.pay_and_request(
    url="https://merchant.example/api/infer",
    amount_usd=0.003,
)

# On close, net settlement hits Tempo L1
session.close()

This ensures agents operating across multiple MPP sessions, x402 endpoints, and direct escrow payments never exceed their aggregate budget.

ElizaOS is the largest open-source agent framework (16K+ agents deployed as of April 2026). Switchboard will ship as a first-class ElizaOS plugin (#18), making it the default wallet runtime for any ElizaOS agent that needs to transact on-chain.

The plugin will expose switchboard's wallet management, gas budgets, and payment capabilities as ElizaOS actions and providers. An agent developer configures their budget in the character file and switchboard handles everything from nonce management to 402 auto-pay.

{
  "name": "my-trading-agent",
  "plugins": ["@kcolbchain/switchboard-eliza"],
  "settings": {
    "switchboard": {
      "chain": "base",
      "hourly_gas_limit": "0.05 ETH",
      "daily_gas_limit": "0.5 ETH",
      "x402_auto_pay": true,
      "mpp_enabled": true
    }
  }
}

You have a gas-budget-tracked wallet and can create escrow payments between agents. Here is where to go next: