Hanzo Web3 Gateway - Keyless Blockchain Access via x402

Overview

Why the Gateway?

Feedback
Zero configuration: No API key, no account, no billing
Feedback
Agent-native: Agents autonomously sign up and pay
Feedback
x402 standard: Open payment protocol (EIP-712 signed USDC on Base)
Feedback
Same coverage: All 100+ chains available through Hanzo Web3
Feedback
Micropayments: Sub-cent pricing per request ($0.000001 -$0.0001)

When to use

Feedback
The agent needs keyless blockchain access without a Hanzo account
Feedback
The agent should pay per request with USDC (x402 protocol)
Feedback
Building autonomous agents that sign up and pay independently
Feedback
No human needs to create an API key or manage billing

Hard requirements

Feedback
Wallet required. HANZO_WALLET_PRIVATE_KEY must be set to an Ethereum private key that holds USDC on Base.
Feedback
USDC on Base. The wallet must have USDC balance on Base network for x402 payments.
Feedback
Never expose the private key in user-visible output, logs, or screenshots.
Feedback
If HANZO_WEB3_API_KEY is set, prefer the hanzo-web3 skill (it is cheaper for high volume).

Preflight checks

Feedback
HANZO_WALLET_PRIVATE_KEY is set and non-empty
Feedback
If HANZO_WEB3_API_KEY is also set, warn that hanzo-web3 skill may be more cost-effective

How x402 works

Feedback
Agent sends request to gateway without auth
Feedback
Gateway responds with 402 Payment Required + payment details
Feedback
Agent signs USDC payment authorization (EIP-712)
Feedback
Agent resends request with X-Payment header containing signed authorization
Feedback
Gateway verifies signature, deducts USDC, processes request
Feedback
Response returned as normal

Quick reference

One-file quickstart

# Using cast (foundry)
cast wallet new

# Save the private key
export HANZO_WALLET_PRIVATE_KEY=0x...

# First request gets 402 with payment details
curl -X POST https://gateway.web3.hanzo.ai/v1/eth/mainnet \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Response: 402 Payment Required with X-Payment-Details header
# Agent SDK handles payment signing automatically

Using the Hanzo Agent SDK

import { HanzoWeb3Agent } from "@hanzo/web3-agent"

const agent = new HanzoWeb3Agent({
  privateKey: process.env.HANZO_WALLET_PRIVATE_KEY,
})

// Automatically handles x402 payment flow
const blockNumber = await agent.rpc("eth/mainnet", {
  method: "eth_blockNumber",
  params: [],
})

Python

from hanzo.web3 import Web3Agent

agent = Web3Agent()  # uses HANZO_WALLET_PRIVATE_KEY from env

# Automatic x402 payment handling
block = agent.rpc("eth/mainnet", method="eth_blockNumber")
balances = agent.tokens.balances(address="0x...", network="eth/mainnet")

Pricing

Endpoint selector

MCP Integration

import { MCPServer, Tool } from '@hanzo/mcp'
import { HanzoWeb3Agent } from '@hanzo/web3-agent'

const agent = new HanzoWeb3Agent({
  privateKey: process.env.HANZO_WALLET_PRIVATE_KEY,
})

const gatewayTools: Tool[] = [
  {
    name: 'web3_gateway_rpc',
    description: 'Keyless JSON-RPC call via x402 micropayment',
    parameters: {
      network: { type: 'string', required: true },
      method: { type: 'string', required: true },
      params: { type: 'array', default: [] }
    },
    async execute({ network, method, params }) {
      return await agent.rpc(network, { method, params })
    }
  },
  {
    name: 'web3_gateway_balance',
    description: 'Check USDC balance available for gateway payments',
    parameters: {},
    async execute() {
      return await agent.getBalance()
    }
  }
]

Error handling

Choosing between Web3 and Web3 Gateway

Official links

Feedback
Agent docs: https://web3.hanzo.ai/docs/agents
Feedback
x402 protocol: https://x402.org
Feedback
Dashboard: https://web3.hanzo.ai/dashboard
Feedback
Hanzo AI: https://hanzo.ai
Feedback
Hanzo Bot: https://hanzo.bot