API Reference

Complete reference for all Bootnode REST and JSON-RPC endpoints.

Authentication

All API requests require authentication via one of two methods:

API Key Header

X-API-Key: bn_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Bearer Token

Authorization: Bearer bn_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Base URL

https://api.bootnode.dev/v1

Rate Limits

Plan	Requests / second	Requests / day
Free	10	100,000
Growth	100	5,000,000
Enterprise	Unlimited	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1706400000

RPC

POST

/v1/rpc/{chain}/{network}

Proxy a JSON-RPC request to any supported blockchain. Supports all standard JSON-RPC methods for EVM chains, and chain-specific methods for non-EVM chains like Solana.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier (ethereum, polygon, solana, base, arbitrum, etc.)
network	string	Yes	Network name (mainnet, sepolia, devnet, etc.)

Request

curl -X POST https://api.bootnode.dev/v1/rpc/ethereum/mainnet \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_blockNumber",
    "params": []
  }'

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x13a5e7f"
}

Tokens

GET

/v1/tokens/{chain}/balances/{address}

Get all ERC-20 token balances for a wallet address, including token metadata and USD values.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier (ethereum, polygon, base, etc.)
address	string	Yes	Wallet address (0x-prefixed hex)
page	integer	No	Page number for pagination (default: 1)
limit	integer	No	Results per page, max 100 (default: 50)

Request

curl https://api.bootnode.dev/v1/tokens/ethereum/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "tokens": [
    {
      "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "balance": "15230500000",
      "formatted_balance": "15230.50",
      "usd_value": "15230.50",
      "logo_url": "https://assets.bootnode.dev/tokens/usdc.png"
    },
    {
      "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "symbol": "USDT",
      "name": "Tether USD",
      "decimals": 6,
      "balance": "8500000000",
      "formatted_balance": "8500.00",
      "usd_value": "8500.00",
      "logo_url": "https://assets.bootnode.dev/tokens/usdt.png"
    }
  ],
  "page": 1,
  "total": 2
}

GET

/v1/tokens/{chain}/metadata/{contract}

Get metadata for a specific ERC-20 token contract, including name, symbol, decimals, total supply, and current price.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier
contract	string	Yes	Token contract address (0x-prefixed hex)

Request

curl https://api.bootnode.dev/v1/tokens/ethereum/metadata/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "chain": "ethereum",
  "name": "USD Coin",
  "symbol": "USDC",
  "decimals": 6,
  "total_supply": "26000000000000000",
  "formatted_total_supply": "26000000000.00",
  "price_usd": "1.00",
  "market_cap_usd": "26000000000.00",
  "logo_url": "https://assets.bootnode.dev/tokens/usdc.png"
}

NFTs

GET

/v1/nfts/{chain}/metadata/{contract}/{token_id}

Get metadata for a specific NFT including name, description, image URL, traits, and ownership info.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier
contract	string	Yes	NFT contract address
token_id	string	Yes	Token ID

Request

curl https://api.bootnode.dev/v1/nfts/ethereum/metadata/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234 \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "contract": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
  "token_id": "1234",
  "name": "Bored Ape #1234",
  "description": "A unique Bored Ape Yacht Club NFT.",
  "image_url": "ipfs://QmRRPWG96cmgTn2qSzjwr2qvfNEuhunv6FNeMFGa9bx6mQ",
  "image_gateway_url": "https://ipfs.bootnode.dev/ipfs/QmRRPWG96cmgTn2qSzjwr2qvfNEuhunv6FNeMFGa9bx6mQ",
  "standard": "ERC721",
  "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "traits": [
    { "trait_type": "Background", "value": "Aquamarine" },
    { "trait_type": "Fur", "value": "Dark Brown" },
    { "trait_type": "Eyes", "value": "Bored" },
    { "trait_type": "Mouth", "value": "Grin" }
  ]
}

GET

/v1/nfts/{chain}/collection/{contract}

Get collection-level metadata for an NFT contract, including name, floor price, total supply, and stats.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier
contract	string	Yes	NFT contract address

Request

curl https://api.bootnode.dev/v1/nfts/ethereum/collection/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "contract": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
  "chain": "ethereum",
  "name": "Bored Ape Yacht Club",
  "symbol": "BAYC",
  "standard": "ERC721",
  "total_supply": 10000,
  "num_owners": 6432,
  "floor_price_eth": "12.50",
  "floor_price_usd": "25000.00",
  "banner_url": "https://assets.bootnode.dev/collections/bayc-banner.png",
  "image_url": "https://assets.bootnode.dev/collections/bayc.png",
  "description": "The Bored Ape Yacht Club is a collection of 10,000 unique Bored Ape NFTs."
}

GET

/v1/nfts/{chain}/owned/{address}

Get all NFTs owned by a wallet address across all collections on the given chain.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier
address	string	Yes	Wallet address
page	integer	No	Page number (default: 1)
limit	integer	No	Results per page, max 100 (default: 50)

Request

curl https://api.bootnode.dev/v1/nfts/ethereum/owned/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "nfts": [
    {
      "contract": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
      "token_id": "1234",
      "name": "Bored Ape #1234",
      "collection_name": "Bored Ape Yacht Club",
      "image_url": "ipfs://QmRRPWG96cmgTn2qSzjwr2qvfNEuhunv6FNeMFGa9bx6mQ",
      "standard": "ERC721"
    }
  ],
  "page": 1,
  "total": 1
}

Wallets

POST

/v1/wallets/create

Create a new ERC-4337 smart wallet. The wallet is counterfactually deployed -- it exists at a deterministic address but is only deployed on-chain when the first transaction is sent.

Parameters

Name	Type	Required	Description
owner	string	Yes	EOA address that owns this smart wallet
chain	string	Yes	Chain to deploy on (ethereum, base, polygon, etc.)
salt	string	No	Optional salt for deterministic address generation

Request

curl -X POST https://api.bootnode.dev/v1/wallets/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ethereum"
  }'

Response

{
  "address": "0x7A0b3e4C5F1234567890abcdef1234567890ABCD",
  "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "status": "counterfactual",
  "factory": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
  "created_at": "2026-01-15T10:30:00Z"
}

GET

/v1/wallets/{address}

Get details of a specific smart wallet including its on-chain deployment status, owner, and transaction count.

Parameters

Name	Type	Required	Description
address	string	Yes	Smart wallet address

Request

curl https://api.bootnode.dev/v1/wallets/0x7A0b3e4C5F1234567890abcdef1234567890ABCD \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "address": "0x7A0b3e4C5F1234567890abcdef1234567890ABCD",
  "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "status": "deployed",
  "factory": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
  "nonce": 5,
  "created_at": "2026-01-15T10:30:00Z",
  "deployed_at": "2026-01-15T10:35:22Z",
  "deploy_tx": "0xabc123..."
}

GET

/v1/wallets

List all smart wallets associated with your API key, with pagination.

Parameters

Name	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Results per page, max 100 (default: 25)
chain	string	No	Filter by chain

Request

curl https://api.bootnode.dev/v1/wallets?chain=ethereum&limit=10 \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "wallets": [
    {
      "address": "0x7A0b3e4C5F1234567890abcdef1234567890ABCD",
      "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "chain": "ethereum",
      "status": "deployed",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "total": 1
}

Webhooks

POST

/v1/webhooks

Create a new webhook subscription. Bootnode will POST events to your URL as they occur on-chain.

Parameters

Name	Type	Required	Description
url	string	Yes	HTTPS endpoint to receive webhook events
chain	string	Yes	Chain to monitor
event_type	string	Yes	Event type: address_activity, token_transfer, nft_transfer, mined_transaction, log
config	object	No	Event-specific filter configuration

Request

curl -X POST https://api.bootnode.dev/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "url": "https://myapp.com/api/webhooks/bootnode",
    "chain": "ethereum",
    "event_type": "address_activity",
    "config": {
      "addresses": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]
    }
  }'

Response

{
  "id": "wh_a1b2c3d4e5f6",
  "url": "https://myapp.com/api/webhooks/bootnode",
  "chain": "ethereum",
  "event_type": "address_activity",
  "config": {
    "addresses": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]
  },
  "signing_secret": "whsec_k7m9p2q4r6s8t0v2w4x6y8z0",
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z"
}

GET

/v1/webhooks

List all webhook subscriptions for your account.

Parameters

Name	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Results per page, max 100 (default: 25)
status	string	No	Filter by status: active, paused, disabled

Request

curl https://api.bootnode.dev/v1/webhooks \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "webhooks": [
    {
      "id": "wh_a1b2c3d4e5f6",
      "url": "https://myapp.com/api/webhooks/bootnode",
      "chain": "ethereum",
      "event_type": "address_activity",
      "status": "active",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "total": 1
}

PATCH

/v1/webhooks/{id}

Update a webhook subscription. You can change the URL, status, or filter configuration.

Parameters

Name	Type	Required	Description
id	string	Yes	Webhook ID (e.g. wh_a1b2c3d4e5f6)
url	string	No	New webhook URL
status	string	No	Set status: active, paused
config	object	No	Updated filter configuration

Request

curl -X PATCH https://api.bootnode.dev/v1/webhooks/wh_a1b2c3d4e5f6 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "status": "paused"
  }'

Response

{
  "id": "wh_a1b2c3d4e5f6",
  "url": "https://myapp.com/api/webhooks/bootnode",
  "chain": "ethereum",
  "event_type": "address_activity",
  "status": "paused",
  "updated_at": "2026-01-15T12:00:00Z"
}

DELETE

/v1/webhooks/{id}

Permanently delete a webhook subscription. This action cannot be undone.

Parameters

Name	Type	Required	Description
id	string	Yes	Webhook ID

Request

curl -X DELETE https://api.bootnode.dev/v1/webhooks/wh_a1b2c3d4e5f6 \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "id": "wh_a1b2c3d4e5f6",
  "deleted": true
}

Gas

GET

/v1/gas/{chain}/prices

Get current gas prices for a chain, including slow, standard, and fast estimates.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier (ethereum, polygon, base, etc.)

Request

curl https://api.bootnode.dev/v1/gas/ethereum/prices \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "chain": "ethereum",
  "block_number": 20574335,
  "base_fee_gwei": "12.50",
  "estimates": {
    "slow": {
      "max_fee_gwei": "14.00",
      "max_priority_fee_gwei": "0.50",
      "estimated_seconds": 60
    },
    "standard": {
      "max_fee_gwei": "16.00",
      "max_priority_fee_gwei": "1.50",
      "estimated_seconds": 15
    },
    "fast": {
      "max_fee_gwei": "20.00",
      "max_priority_fee_gwei": "3.00",
      "estimated_seconds": 5
    }
  },
  "updated_at": "2026-01-15T10:30:00Z"
}

POST

/v1/gas/policies

Create a gas sponsorship policy. Policies define rules for when Bootnode will pay gas fees on behalf of your users.

Parameters

Name	Type	Required	Description
name	string	Yes	Human-readable policy name
chain	string	Yes	Chain this policy applies to
rules	object	Yes	Sponsorship rules (max_gas_usd, allowed_contracts, rate_limit, etc.)

Request

curl -X POST https://api.bootnode.dev/v1/gas/policies \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "My App Free Gas",
    "chain": "base",
    "rules": {
      "max_gas_usd": "0.50",
      "max_per_user_per_day": 10,
      "allowed_contracts": [
        "0x1234567890abcdef1234567890abcdef12345678"
      ],
      "allowed_methods": ["transfer", "approve", "mint"]
    }
  }'

Response

{
  "id": "gp_x1y2z3w4v5u6",
  "name": "My App Free Gas",
  "chain": "base",
  "rules": {
    "max_gas_usd": "0.50",
    "max_per_user_per_day": 10,
    "allowed_contracts": [
      "0x1234567890abcdef1234567890abcdef12345678"
    ],
    "allowed_methods": ["transfer", "approve", "mint"]
  },
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z"
}

POST

/v1/gas/sponsor

Sponsor a specific UserOperation. Returns a signed paymaster data field to include in the UserOperation.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier
policy_id	string	Yes	Gas policy ID
user_operation	object	Yes	The UserOperation to sponsor

Request

curl -X POST https://api.bootnode.dev/v1/gas/sponsor \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "chain": "base",
    "policy_id": "gp_x1y2z3w4v5u6",
    "user_operation": {
      "sender": "0x7A0b3e4C5F1234567890abcdef1234567890ABCD",
      "nonce": "0x0",
      "callData": "0xb61d27f6...",
      "callGasLimit": "0x5208",
      "verificationGasLimit": "0x186a0",
      "preVerificationGas": "0xc350",
      "maxFeePerGas": "0x3b9aca00",
      "maxPriorityFeePerGas": "0x59682f00"
    }
  }'

Response

{
  "paymaster": "0xBootnodePaymasterAddress",
  "paymasterData": "0x0000000067b2c3d4...signed_data",
  "paymasterVerificationGasLimit": "0x30000",
  "paymasterPostOpGasLimit": "0x10000",
  "sponsored_gas_usd": "0.03"
}

Bundler

POST

/v1/bundler/{chain}/{network}

ERC-4337 bundler JSON-RPC endpoint. Supports eth_sendUserOperation, eth_estimateUserOperationGas, eth_getUserOperationByHash, eth_getUserOperationReceipt, and eth_supportedEntryPoints.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier
network	string	Yes	Network name (mainnet, sepolia, etc.)

Request

curl -X POST https://api.bootnode.dev/v1/bundler/ethereum/mainnet \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_sendUserOperation",
    "params": [
      {
        "sender": "0x7A0b3e4C5F1234567890abcdef1234567890ABCD",
        "nonce": "0x0",
        "initCode": "0x",
        "callData": "0xb61d27f6...",
        "callGasLimit": "0x5208",
        "verificationGasLimit": "0x186a0",
        "preVerificationGas": "0xc350",
        "maxFeePerGas": "0x3b9aca00",
        "maxPriorityFeePerGas": "0x59682f00",
        "paymasterAndData": "0x",
        "signature": "0xabcdef..."
      },
      "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"
    ]
  }'

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

WebSocket

/v1/ws/{chain}/{network}

WebSocket endpoint for real-time blockchain subscriptions. Supports eth_subscribe for newHeads, logs, newPendingTransactions, and syncing.

Parameters

Name	Type	Required	Description
chain	string	Yes	Chain identifier
network	string	Yes	Network name (mainnet, sepolia, etc.)

Request

wscat -c "wss://api.bootnode.dev/v1/ws/ethereum/mainnet?apiKey=YOUR_API_KEY"

> {"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}

Response

{"jsonrpc":"2.0","id":1,"result":"0x1a2b3c4d"}

// Subsequent messages:
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x1a2b3c4d",
    "result": {
      "number": "0x13a5e80",
      "hash": "0xabc123...",
      "parentHash": "0xdef456...",
      "timestamp": "0x67890abc",
      "gasUsed": "0xe4e1c0",
      "gasLimit": "0x1c9c380",
      "baseFeePerGas": "0x2e90edd00"
    }
  }
}

Error Codes

HTTP Status	Error Code	Description
400	invalid_request	Malformed request body or missing required parameters
401	unauthorized	Missing or invalid API key
403	forbidden	API key does not have access to this resource
404	not_found	Resource does not exist
429	rate_limited	Rate limit exceeded. Check X-RateLimit headers.
500	internal_error	Internal server error. Retry with exponential backoff.

All error responses follow this format:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 1 second.",
    "status": 429
  }
}