Hanzo Web3 - Blockchain API for 100+ Chains

Overview

Hanzo Web3 is the blockchain infrastructure layer of the Hanzo ecosystem. It provides unified API access to 100+ EVM and non-EVM chains including Ethereum, Solana, Base, Arbitrum, Polygon, Lux, and more. Node RPC, structured data, webhooks, smart wallets, and Solana-specific APIs are all available through a single API key.

Why Hanzo Web3?

One key, 100+ chains: No per-chain configuration or separate providers

Structured data: Token balances, NFT metadata, portfolio views without indexing

Push notifications: Managed webhooks for onchain events

Account abstraction: ERC-4337 smart wallets with gas sponsorship

Solana native: Yellowstone gRPC, DAS, and WebSocket support

Part of Hanzo ecosystem: Integrates with Hanzo Chat, Commerce, Console, and MCP

When to use

Use this skill when:

The user wants to read or write blockchain data

The user needs token balances, NFT metadata, or transaction history

The user wants to deploy or interact with smart contracts

The user needs real-time onchain event notifications via webhooks

The user wants to set up smart wallets or account abstraction

Hard requirements

API Key required. If HANZO_WEB3_API_KEY is not set, tell the user to get one free at https://web3.hanzo.ai/dashboard, or switch to the hanzo-web3-gateway skill for keyless access.

Never expose the API key in user-visible output, logs, or screenshots.

Rate limits apply. Free tier: 25 req/s, PAYG: 300 req/s. Respect 429 responses with exponential backoff.

Preflight checks

Before making any request, silently verify:

HANZO_WEB3_API_KEY environment variable is set and non-empty

If unset, suggest: export HANZO_WEB3_API_KEY=<your-key>

Quick reference

Item	Value
Base URL	`https://api.web3.hanzo.ai/v1`
Auth header	`X-API-Key: ${HANZO_WEB3_API_KEY}`
Alt auth	URL path: `https://api.web3.hanzo.ai/v1/${HANZO_WEB3_API_KEY}/eth/mainnet`
WebSocket	`wss://ws.web3.hanzo.ai/v1/${HANZO_WEB3_API_KEY}`
Status	https://status.web3.hanzo.ai
Docs	https://web3.hanzo.ai/docs
Dashboard	https://web3.hanzo.ai/dashboard

Network names

Chain	Network ID	Mainnet	Testnet
Ethereum	eth	`eth/mainnet`	`eth/sepolia`, `eth/holesky`
Base	base	`base/mainnet`	`base/sepolia`
Arbitrum	arb	`arb/mainnet`	`arb/sepolia`
Polygon	polygon	`polygon/mainnet`	`polygon/amoy`
Optimism	opt	`opt/mainnet`	`opt/sepolia`
Solana	sol	`sol/mainnet`	`sol/devnet`
Lux	lux	`lux/mainnet`	`lux/testnet`
Avalanche	avax	`avax/mainnet`	`avax/fuji`
BNB Chain	bsc	`bsc/mainnet`	`bsc/testnet`
90+ more	...	See docs	See docs

One-file quickstart

Get latest block number (Ethereum)

curl -X POST https://api.web3.hanzo.ai/v1/eth/mainnet \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${HANZO_WEB3_API_KEY}" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Get token balances

curl "https://api.web3.hanzo.ai/v1/data/tokens/balances?address=0x...&network=eth/mainnet" \
  -H "X-API-Key: ${HANZO_WEB3_API_KEY}"

Get NFT metadata

curl "https://api.web3.hanzo.ai/v1/data/nfts?owner=0x...&network=eth/mainnet" \
  -H "X-API-Key: ${HANZO_WEB3_API_KEY}"

Create webhook

curl -X POST https://api.web3.hanzo.ai/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${HANZO_WEB3_API_KEY}" \
  -d '{
    "url": "https://your-server.com/webhook",
    "network": "eth/mainnet",
    "event_type": "address_activity",
    "addresses": ["0x..."]
  }'

Python (with Hanzo SDK)

from hanzo import Hanzo

client = Hanzo()  # uses HANZO_WEB3_API_KEY from env

# JSON-RPC
block = client.web3.rpc("eth/mainnet", method="eth_blockNumber")

# Structured data
balances = client.web3.tokens.balances(
    address="0x...",
    network="eth/mainnet"
)

# Webhooks
hook = client.web3.webhooks.create(
    url="https://your-server.com/webhook",
    network="eth/mainnet",
    event_type="address_activity",
    addresses=["0x..."]
)

Endpoint selector

Task	Endpoint	Method
JSON-RPC call	`POST /v1/{network}`	POST
Get token balances	`GET /v1/data/tokens/balances`	GET
Get token prices	`GET /v1/data/tokens/prices`	GET
Get token metadata	`GET /v1/data/tokens/metadata`	GET
Get NFTs by owner	`GET /v1/data/nfts`	GET
Get NFT metadata	`GET /v1/data/nfts/metadata`	GET
Get transfers	`GET /v1/data/transfers`	GET
Get transaction history	`GET /v1/data/transactions`	GET
Get portfolio	`GET /v1/data/portfolio`	GET
Create webhook	`POST /v1/webhooks`	POST
List webhooks	`GET /v1/webhooks`	GET
Delete webhook	`DELETE /v1/webhooks/{id}`	DELETE
WebSocket subscribe	`WS /v1/{api_key}`	WS
Smart wallet create	`POST /v1/wallets/create`	POST
Smart wallet execute	`POST /v1/wallets/execute`	POST
Gas estimate	`POST /v1/gas/estimate`	POST
Simulate transaction	`POST /v1/simulate`	POST

Skill map

Node APIs

Core JSON-RPC access for 100+ chains with load balancing and automatic failover.

Endpoint	Description
`POST /v1/{network}`	Standard JSON-RPC proxy (eth_call, eth_sendRawTransaction, etc.)
`POST /v1/{network}/debug`	Debug namespace (debug_traceTransaction, debug_traceCall)
`POST /v1/{network}/trace`	Trace namespace (trace_block, trace_transaction)
`WS /v1/{api_key}`	WebSocket for subscriptions (newHeads, logs, pendingTransactions)

Data APIs

Structured onchain data across tokens, NFTs, transfers, and portfolio views.

Endpoint	Description
`GET /v1/data/tokens/balances`	ERC-20 balances for any address
`GET /v1/data/tokens/prices`	Real-time token prices (USD, ETH, BTC)
`GET /v1/data/tokens/metadata`	Token name, symbol, decimals, logo
`GET /v1/data/nfts`	NFTs owned by address
`GET /v1/data/nfts/metadata`	NFT metadata, media, traits
`GET /v1/data/transfers`	Token and NFT transfer history
`GET /v1/data/transactions`	Full transaction history
`GET /v1/data/portfolio`	Aggregated portfolio across chains

Solana APIs

High-throughput Solana access with Yellowstone gRPC and DAS.

Endpoint	Description
`POST /v1/sol/mainnet`	Solana JSON-RPC
`gRPC /v1/sol/yellowstone`	Yellowstone gRPC streams (accounts, transactions, blocks)
`POST /v1/sol/das`	Digital Asset Standard API (compressed NFTs, Metaplex)
`WS /v1/sol/ws`	Solana WebSocket subscriptions

Webhooks

Push-based notifications for onchain events with managed delivery.

Endpoint	Description
`POST /v1/webhooks`	Create webhook subscription
`GET /v1/webhooks`	List active webhooks
`GET /v1/webhooks/{id}`	Get webhook details
`DELETE /v1/webhooks/{id}`	Delete webhook
`POST /v1/webhooks/{id}/test`	Send test event

Supported event types: address_activity, token_transfer, nft_transfer, new_block, contract_event, pending_transaction.

Smart Wallets

ERC-4337 account abstraction with gas sponsorship and social login.

Endpoint	Description
`POST /v1/wallets/create`	Create smart wallet
`POST /v1/wallets/execute`	Execute user operation
`POST /v1/wallets/batch`	Batch multiple operations
`POST /v1/gas/estimate`	Estimate gas for user operation
`POST /v1/gas/sponsor`	Sponsor gas for user

Recipes

Practical integration patterns.

Recipe	Description
Token swap monitoring	Watch DEX swaps and notify on price impact
NFT mint tracker	Alert when new NFTs are minted in a collection
Wallet portfolio	Build multi-chain portfolio dashboard
Transaction relay	Submit and track transactions with retry logic
Airdrop checker	Check eligibility across protocols

MCP Integration

Expose Hanzo Web3 as MCP tools for agentic workflows:

import { MCPServer, Tool } from '@hanzo/mcp'

const web3Tools: Tool[] = [
  {
    name: 'web3_rpc',
    description: 'Execute JSON-RPC call on any supported chain',
    parameters: {
      network: { type: 'string', required: true },
      method: { type: 'string', required: true },
      params: { type: 'array', default: [] }
    },
    async execute({ network, method, params }) {
      const res = await fetch(`https://api.web3.hanzo.ai/v1/${network}`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': process.env.HANZO_WEB3_API_KEY
        },
        body: JSON.stringify({ jsonrpc: '2.0', method, params, id: 1 })
      })
      return await res.json()
    }
  },
  {
    name: 'web3_token_balances',
    description: 'Get token balances for an address',
    parameters: {
      address: { type: 'string', required: true },
      network: { type: 'string', default: 'eth/mainnet' }
    },
    async execute({ address, network }) {
      const res = await fetch(
        `https://api.web3.hanzo.ai/v1/data/tokens/balances?address=${address}&network=${network}`,
        { headers: { 'X-API-Key': process.env.HANZO_WEB3_API_KEY } }
      )
      return await res.json()
    }
  }
]

Error handling

Code	Meaning	Action
200	Success	Process response
400	Bad request	Check parameters
401	Unauthorized	Check API key
429	Rate limited	Exponential backoff (1s, 2s, 4s, 8s, max 30s)
500	Server error	Retry up to 3 times
502/503	Upstream error	Retry with different endpoint

Official links

Dashboard: https://web3.hanzo.ai/dashboard

Documentation: https://web3.hanzo.ai/docs

API Reference: https://web3.hanzo.ai/docs/api

Status: https://status.web3.hanzo.ai

Hanzo AI: https://hanzo.ai

Hanzo Bot: https://hanzo.bot

Hanzo Web3 - Blockchain API for 100+ Chains

On this page