WebSocket Real-time Streaming

Connect to Axol's WebSocket API for real-time blockchain data.

Connection

Endpoint: wss://ws.axol.io

from axol import AxolWebSocket

ws = AxolWebSocket(api_key="your_key")
await ws.connect()

Channels

Gas Prices

Real-time gas price updates across chains.

await ws.subscribe("gas_prices", on_gas_update)

def on_gas_update(data):
    # {
    #   "chain": "ethereum",
    #   "slow": 20,
    #   "standard": 25,
    #   "fast": 30,
    #   "instant": 35
    # }
    print(f"{data['chain']}: {data['fast']} gwei")

New Blocks

Stream new blocks as they're mined.

await ws.subscribe("blocks:ethereum", on_block)

def on_block(block):
    # {
    #   "number": 18500000,
    #   "hash": "0x...",
    #   "timestamp": 1699000000,
    #   "transactions": 250
    # }
    print(f"Block {block['number']}: {block['transactions']} txs")

Pending Transactions

Monitor mempool transactions.

await ws.subscribe("pending:ethereum", on_pending)

def on_pending(tx):
    # {
    #   "hash": "0x...",
    #   "from": "0x...",
    #   "to": "0x...",
    #   "value": "1.5",
    #   "gas_price": 25
    # }
    if float(tx['value']) > 10:
        print(f"Large tx: {tx['value']} ETH")

Custom Filters

# Subscribe with filters
await ws.subscribe("transactions", on_tx, {
    "chain": "ethereum",
    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5",
    "min_value": "1.0"
})

Message Format

All messages follow this structure:

{
  "channel": "gas_prices",
  "event": "update",
  "data": {...},
  "timestamp": 1699000000
}

Connection Management

Auto-reconnect

ws = AxolWebSocket(
    api_key="your_key",
    auto_reconnect=True,
    max_reconnect_attempts=5
)

Heartbeat

# Automatic ping/pong
ws.heartbeat_interval = 30  # seconds

Error Handling

@ws.on_error
def handle_error(error):
    print(f"WebSocket error: {error}")

@ws.on_disconnect
def handle_disconnect():
    print("Disconnected from WebSocket")

Rate Limits

WebSocket subscriptions are subject to the same CU-based rate limiting as REST API calls:

Tier	Max Subscriptions	Throughput (CUPs)	Notes
Starter	10 concurrent	50 CUs/sec	~1 event/sec average
Growth	50 concurrent	330 CUs/sec	~8 events/sec average
Scale	200 concurrent	1,250 CUs/sec	~31 events/sec average
Enterprise	Unlimited	Custom	Custom throughput

Each WebSocket event costs 40 CUs and counts toward your standard CU pool (not trace pool).

See Rate Limits for detailed CU information.

JavaScript Client

const ws = new WebSocket('wss://ws.axol.io');

ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'auth',
    api_key: 'your_key'
  }));
  
  ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'gas_prices'
  }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  console.log(msg);
});

Available Channels

Channel	Description	Example
gas_prices	Gas price updates	All chains
blocks:{chain}	New blocks	blocks:ethereum
pending:{chain}	Mempool transactions	pending:polygon
transactions	Confirmed transactions	With filters
token_prices	Token price updates	Major tokens
defi_events	DeFi protocol events	Swaps, liquidity
alerts	Custom alerts	Price thresholds

Compute Unit (CU) Costs

WebSocket events consume CUs from your standard monthly pool:

Event Type	CU Cost	Example Frequency
New block header (newHeads)	40 CUs	~12/min (Ethereum)
Log event (logs)	40 CUs	Varies by filter
Pending transaction (pending)	40 CUs	High volume (~100s/sec)
Gas price update	40 CUs	~1/min
Token price update	40 CUs	~1/min per token

Usage Examples

Low-frequency subscription (Ethereum newHeads):

• 12 blocks/min × 60 min × 24 hours × 30 days = 518,400 blocks/month
• 518,400 blocks × 40 CUs = 20,736,000 CUs/month
• Fits comfortably in Starter tier (400M CUs)

High-frequency subscription (Pending transactions):

• 100 pending tx/sec × 60 sec × 60 min × 24 hours × 30 days = 259,200,000 events/month
• 259,200,000 events × 40 CUs = 10,368,000,000 CUs/month (10.4B CUs)
• Requires Scale tier (12B CUs) or careful filtering

Monitoring Usage

Check CU consumption via response headers:

X-RateLimit-CU-Remaining: 1950000000
X-RateLimit-CU-Reset: 1704153600

Or monitor real-time at app.axol.io/dashboard.

Next Steps

• Python SDK - Client library documentation
• Rate Limits - Detailed CU information
• Pricing - CU costs and tier comparison
• API Reference - Complete WebSocket API