API Endpoints Reference

Comprehensive guide to all Axol API endpoints. All endpoints require authentication via X-API-Key header.

Base URL

https://api.axol.io/api/v1

Authentication

All requests require your API key in the header:

curl -H "X-API-Key: your_api_key" \
  https://api.axol.io/api/v1/...

---

Gas API Endpoints

Gas optimization and price tracking across 7+ EVM chains.

Get Current Gas Prices

GET /gas/{chain}

Get current gas prices for a specific chain.

Parameters:

• chain (path, required): Chain name (ethereum, polygon, arbitrum, etc.)

Response:

{
  "chain": "ethereum",
  "slow": 20,
  "standard": 25,
  "fast": 30,
  "instant": 35,
  "timestamp": "2025-10-12T10:30:00Z",
  "unit": "gwei"
}

CU Cost: 5

Supported Chains: ethereum, polygon, arbitrum, optimism, base, avalanche, bsc

---

Compare Gas Across Chains

GET /gas/compare?chains=ethereum,polygon,arbitrum

Compare gas prices across multiple chains.

Query Parameters:

• chains (required): Comma-separated list of chain names

Response:

{
  "comparison": [
    { "chain": "ethereum", "standard": 25, "unit": "gwei" },
    { "chain": "polygon", "standard": 80, "unit": "gwei" },
    { "chain": "arbitrum", "standard": 0.1, "unit": "gwei" }
  ],
  "cheapest": "arbitrum",
  "most_expensive": "polygon",
  "timestamp": "2025-10-12T10:30:00Z"
}

CU Cost: 10

---

Get Historical Gas Data

GET /gas/{chain}/history?days=7&interval=1h

Retrieve historical gas price data.

Parameters:

• chain (path, required): Chain name
• days (query, optional): Number of days (1-365, default: 7)
• interval (query, optional): Data granularity (1h, 6h, 1d, default: 1h)

Response:

{
  "chain": "ethereum",
  "history": [
    {
      "timestamp": "2025-10-12T09:00:00Z",
      "slow": 18,
      "standard": 22,
      "fast": 28,
      "instant": 33
    },
    ...
  ],
  "average": { "slow": 19, "standard": 24, "fast": 29, "instant": 34 },
  "min": { "slow": 15, "standard": 20, "fast": 25, "instant": 30 },
  "max": { "slow": 25, "standard": 30, "fast": 35, "instant": 40 }
}

CU Cost: 20 CUs per day requested

---

Get Gas Optimization Recommendations

GET /gas/{chain}/optimize

Get recommendations for optimal gas usage.

Response:

{
  "chain": "ethereum",
  "current_gas": { "standard": 25 },
  "recommendation": "high",
  "reasoning": "Gas prices are 40% above 24h average",
  "suggested_action": "Consider waiting or using L2",
  "predicted_trend": "decreasing",
  "optimal_time_window": "2025-10-12T14:00:00Z to 2025-10-12T16:00:00Z"
}

CU Cost: 15

---

Price API Endpoints

Real-time and historical token price data.

Get Token Price

GET /price/{chain}/{symbol}

Get current price for a specific token.

Parameters:

• chain (path, required): Chain name
• symbol (path, required): Token symbol (ETH, USDC, WBTC, etc.)

Response:

{
  "chain": "ethereum",
  "symbol": "USDC",
  "price_usd": 0.9998,
  "price_change_24h": -0.02,
  "price_change_7d": 0.01,
  "volume_24h": 5000000000,
  "market_cap": 24000000000,
  "timestamp": "2025-10-12T10:30:00Z"
}

CU Cost: 5

---

Compare Prices Across Exchanges

GET /price/{chain}/{symbol}/compare?exchanges=uniswap,sushiswap,curve

Compare token prices across multiple DEXs.

Parameters:

• chain (path, required): Chain name
• symbol (path, required): Token symbol
• exchanges (query, required): Comma-separated exchange names

Response:

{
  "symbol": "USDC",
  "comparison": [
    { "exchange": "uniswap", "price_usd": 0.9998, "liquidity": 100000000 },
    { "exchange": "sushiswap", "price_usd": 0.9997, "liquidity": 50000000 },
    { "exchange": "curve", "price_usd": 1.0000, "liquidity": 200000000 }
  ],
  "best_price": { "exchange": "curve", "price_usd": 1.0000 },
  "price_spread": 0.03,
  "arbitrage_opportunity": false
}

CU Cost: 10

---

Get Historical Price Data

GET /price/{chain}/{symbol}/history?days=30&interval=1d

Retrieve historical price data.

Parameters:

• chain (path, required): Chain name
• symbol (path, required): Token symbol
• days (query, optional): Number of days (1-365, default: 30)
• interval (query, optional): Data granularity (1h, 1d, 1w, default: 1d)

Response:

{
  "chain": "ethereum",
  "symbol": "ETH",
  "history": [
    {
      "timestamp": "2025-10-11T00:00:00Z",
      "open": 2500,
      "high": 2550,
      "low": 2480,
      "close": 2520,
      "volume": 15000000000
    },
    ...
  ],
  "period_change": 5.2,
  "volatility": 8.5
}

CU Cost: 15 CUs per day requested

---

Blockchain Data Endpoints

Unified endpoints for querying blockchain data across all supported chains.

Get Address Balance

GET /blockchain/{chain}/balance/{address}

Get balance for an address.

Parameters:

• chain (path, required): Chain name
• address (path, required): Wallet address

Response (EVM):

{
  "chain": "ethereum",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
  "balance": "12.5 ETH",
  "balance_wei": "12500000000000000000"
}

Response (Solana):

{
  "chain": "solana",
  "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "balance": "10.5 SOL",
  "balance_lamports": "10500000000"
}

CU Cost: 15

---

Get Transaction

GET /blockchain/{chain}/transaction/{hash}

Retrieve transaction details by hash.

Parameters:

• chain (path, required): Chain name
• hash (path, required): Transaction hash

Response:

{
  "chain": "ethereum",
  "hash": "0xabc...",
  "from": "0x123...",
  "to": "0x456...",
  "value": "1.5 ETH",
  "gas_used": 21000,
  "gas_price": "25 gwei",
  "block_number": 18000000,
  "timestamp": "2025-10-12T10:25:00Z",
  "status": "success"
}

CU Cost: 20

---

Get Block Data

GET /blockchain/{chain}/block/{number}

Retrieve block data by number or "latest".

Parameters:

• chain (path, required): Chain name
• number (path, required): Block number or "latest"

Response:

{
  "chain": "ethereum",
  "number": 18000000,
  "hash": "0xdef...",
  "timestamp": "2025-10-12T10:25:00Z",
  "transactions": 150,
  "gas_used": 12500000,
  "gas_limit": 30000000,
  "base_fee": "20 gwei",
  "miner": "0x789..."
}

CU Cost: 21 (without transactions), 36 (with full transaction data)

---

Call Smart Contract

POST /blockchain/{chain}/call

Execute a read-only contract call.

Parameters:

• chain (path, required): Chain name

Request Body:

{
  "to": "0x...",
  "data": "0x...",
  "block": "latest"
}

Response:

{
  "result": "0x...",
  "decoded": "1000000000000000000"
}

CU Cost: 26

---

Estimate Gas

POST /gas/estimate

Estimate gas for a transaction with optimization recommendations.

Request Body:

{
  "chain_id": "ethereum",
  "to_address": "0x...",
  "from_address": "0x...",
  "value": "1000000000000000000",
  "data": "0x",
  "transaction_type": "transfer"
}

Required Fields:

• chain_id (string): Blockchain identifier (ethereum, polygon, etc.)

Optional Fields:

• to_address (string): Destination address
• from_address (string): Source address
• value (string): Transaction value in wei (default: null)
• data (string): Transaction data (default: "0x")
• transaction_type (string): Type of transaction (transfer, swap, contract_call, etc.)

Response:

{
  "chain_id": "ethereum",
  "estimated_gas_limit": 21000,
  "gas_estimates": {
    "slow": { "gas_price": 20, "total_cost_eth": "0.00042", "estimated_time": "~5 min" },
    "standard": { "gas_price": 25, "total_cost_eth": "0.000525", "estimated_time": "~2 min" },
    "fast": { "gas_price": 30, "total_cost_eth": "0.00063", "estimated_time": "~30 sec" }
  },
  "optimization_tips": [
    "Current gas prices are 15% above 24h average",
    "Consider using Layer 2 for significant savings"
  ],
  "confidence_score": 0.92,
  "timestamp": "2025-10-13T00:30:00Z"
}

CU Cost: 87

Also Available: POST /gas/estimate/{chain} - Alternative endpoint that accepts simplified transaction data

---

Get Event Logs

GET /blockchain/{chain}/logs?address=0x...&fromBlock=1000&toBlock=2000

Query contract event logs.

Query Parameters:

• address (optional): Contract address
• topics (optional): Event topics (comma-separated)
• fromBlock (optional): Starting block number
• toBlock (optional): Ending block number

Response:

{
  "logs": [
    {
      "address": "0x...",
      "topics": ["0x...", "0x..."],
      "data": "0x...",
      "block_number": 1500,
      "transaction_hash": "0x...",
      "log_index": 0
    },
    ...
  ],
  "total": 45
}

CU Cost: 75 base + 5 per 1000 blocks queried (max 500 CUs)

---

Chain Status Endpoints

Endpoint Availability

The /blockchain/{chain}/status endpoint has been removed in v0.6.0. Use /blockchain/{chain}/blocks/latest or /blockchain/{chain}/info to get chain information.

---

Get Chain Info

GET /blockchain/{chain}/info

Get static information about a blockchain.

Response:

{
  "chain": "ethereum",
  "chain_id": 1,
  "network_type": "mainnet",
  "consensus": "pos",
  "block_time": 12,
  "native_currency": {
    "symbol": "ETH",
    "decimals": 18
  },
  "explorer": "https://etherscan.io"
}

CU Cost: 5

---

Trace & Debug Endpoints

Advanced tracing and debugging methods. Requires Starter tier or higher.

Trace Transaction

GET /blockchain/{chain}/trace/transaction/{hash}

Get detailed trace of a transaction execution.

CU Cost: 1,000

---

Debug Trace Transaction

POST /blockchain/{chain}/debug/trace-transaction

Get detailed debug trace with EVM execution.

Request Body:

{
  "hash": "0x...",
  "options": {
    "tracer": "callTracer",
    "timeout": "10s"
  }
}

CU Cost: 5,000

---

Trace Block

GET /blockchain/{chain}/trace/block/{number}

Get traces for all transactions in a block.

CU Cost: 2,500

---

Analytics Endpoints

Get Usage Statistics

GET /analytics/usage?start_date=2025-10-01&end_date=2025-10-12

Get your API usage statistics.

Response:

{
  "period": {
    "start": "2025-10-01",
    "end": "2025-10-12"
  },
  "total_cu_used": 50000000,
  "total_requests": 2000000,
  "by_chain": {
    "ethereum": 30000000,
    "polygon": 15000000,
    "solana": 5000000
  },
  "by_method": {
    "gas_queries": 1000000,
    "balance_queries": 25000000,
    "transaction_queries": 20000000
  }
}

CU Cost: 10

---

WebSocket Endpoints

Real-time subscriptions via WebSocket.

Connection

wss://api.axol.io/ws/v1/{chain}

Subscribe to New Blocks

{
  "action": "subscribe",
  "channel": "newHeads"
}

Events:

{
  "channel": "newHeads",
  "data": {
    "number": 18000000,
    "hash": "0x...",
    "timestamp": "2025-10-12T10:30:00Z"
  }
}

CU Cost: 40 CUs per event received

---

Subscribe to Event Logs

{
  "action": "subscribe",
  "channel": "logs",
  "params": {
    "address": "0x...",
    "topics": ["0x..."]
  }
}

CU Cost: 40 CUs per event received

Full WebSocket guide →

---

Response Headers

All responses include usage information:

X-RateLimit-CU-Limit: 150000000
X-RateLimit-CU-Remaining: 149950000
X-RateLimit-CU-Used: 5
X-RateLimit-CU-Reset: 1704153600
X-RateLimit-Trace-CU-Limit: 0
X-RateLimit-Trace-CU-Remaining: 0

---

Error Responses

Standard Error Format

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Monthly CU limit exceeded",
    "details": {
      "limit": 150000000,
      "used": 150000000,
      "reset_at": "2025-11-01T00:00:00Z"
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
INVALID_API_KEY	401	API key is invalid or missing
RATE_LIMIT_EXCEEDED	429	Monthly CU limit reached
THROUGHPUT_EXCEEDED	429	CUs per second limit reached
INVALID_CHAIN	400	Chain not supported
INVALID_ADDRESS	400	Address format invalid
METHOD_NOT_ALLOWED	403	Method requires higher tier
INTERNAL_ERROR	500	Server error

Error handling guide →

---

Rate Limits

CU-Based Limits

• Monthly CU Pool: Based on your tier (150M - 3B+)
• Trace CU Pool: Separate allocation for trace/debug methods
• Throughput (CUPs): CUs per second limit (500 - 25,000+)

Request Rate Limits

• Free: 25 RPS
• Starter: 100 RPS
• Base: 250 RPS
• Growth: 500 RPS
• Scale: 1,250 RPS

Rate limits explained →

---

Next Steps

• View CU Costs →
• Getting Started Guide →
• SDK Documentation →
• WebSocket Guide →