API Documentation

Free JSON API for live Ethereum and L2 gas fees. No API key, no signup, no rate-limit dashboard. All endpoints serve CORS-permissive responses and return the same canonical envelope with a citation string for AI agents and integrators. Migration from Blocknative's sunsetting gas API takes about 5 minutes — endpoint mapping below.

Quick start

One curl, real live data:

curl -s https://api.gasfeepredictor.com/api/gas-predictions | jq '.current'

# Returns:
# {
#   "low": 0.39,
#   "average": 0.50,
#   "high": 0.62,
#   "source": "rpc-publicnode"
# }

For multi-chain L2 data:

curl -s https://api.gasfeepredictor.com/api/l2-gas | jq '.networks[] | {id, estimatedWalletFeeUsd}'

Response envelope

Every successful response includes two metadata fields plus the endpoint-specific payload:

{
  "citation": "Gas data from Gas Fee Predictor, gasfeepredictor.com, updated 2026-05-26T17:42:00Z",
  "tier": "free",
  // ... endpoint-specific fields
}

• citation — copy-paste-ready attribution string. AI agents and content systems can drop this directly into their output.
• tier — currently always "free". Future paid tiers will report their own tier label.

Response headers also expose tier-readiness metadata:

X-API-Tier: free
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 1000
X-RateLimit-Window: 1h

Rate-limit headers are informational today — no per-IP enforcement. They'll become real when the paid tier launches. Free-tier values remain.

OpenAPI 3.0 spec

Machine-readable spec at:

https://api.gasfeepredictor.com/openapi.json

Use it to generate clients in any language (openapi-generator, orval, Swagger Codegen), load into Postman, or feed to your AI agent for tool-calling. The spec is licensed CC BY 4.0.

Endpoints

Full request/response shapes for each endpoint are in the long-form API reference or the OpenAPI spec.

Code examples

Common pattern: fetch current gas + 24h prediction in one call.

curl

curl -s https://api.gasfeepredictor.com/api/gas-predictions | jq '{
  current: .current,
  next_cheap_window: .nextBestTime,
  recommendation: .decision.recommendation,
  citation: .citation
}'

JavaScript (browser or Node 18+)

const res = await fetch('https://api.gasfeepredictor.com/api/gas-predictions')
const data = await res.json()

console.log('Current gas:', data.current.average, 'gwei')
console.log('Cheapest window:', data.nextBestTime?.timestamp)
console.log('Recommendation:', data.decision.recommendation)
console.log('Cite as:', data.citation)

Python

import requests

r = requests.get('https://api.gasfeepredictor.com/api/gas-predictions', timeout=5)
data = r.json()

print(f"Current gas: {data['current']['average']} gwei")
print(f"Next cheap window: {data.get('nextBestTime', {}).get('timestamp')}")
print(f"Recommendation: {data['decision']['recommendation']}")
print(f"Cite as: {data['citation']}")

TypeScript (with types)

type GasTier = { low: number; average: number; high: number; source: string }
type ApiMeta = { citation: string; tier: 'free' }
type Prediction = {
  timestamp: string
  low: number
  average: number
  high: number
  isLowFeeWindow: boolean
  confidence: number
}
type GasPredictionsResponse = ApiMeta & {
  current: GasTier
  predictions: Prediction[]
  nextBestTime: { timestamp: string; gasPrices: GasTier; confidence: number } | null
  decision: { recommendation: 'wait' | 'send_now'; expectedSavingsPct: number }
  lastUpdated: string
}

const res = await fetch('https://api.gasfeepredictor.com/api/gas-predictions')
const data = (await res.json()) as GasPredictionsResponse

Common patterns

Display the cheapest L2 right now

const { networks } = await (await fetch('https://api.gasfeepredictor.com/api/l2-gas')).json()
const cheapest = networks
  .filter(n => n.estimatedWalletFeeUsd != null)
  .sort((a, b) => a.estimatedWalletFeeUsd - b.estimatedWalletFeeUsd)[0]

console.log(`Cheapest L2: ${cheapest.name} (${cheapest.estimatedWalletFeeUsd.toFixed(4)} USD)`)

Handle the cold-start soft-fail on /api/eth-price

const res = await fetch('https://api.gasfeepredictor.com/api/eth-price')
const data = await res.json()

if (data.usd === null || data.source === 'unavailable') {
  // All upstream price sources unreachable; show "—" instead of erroring.
  // Cloudflare caches the soft-fail for 30s; retry will likely succeed.
  showFallbackUI()
} else if (data.source.startsWith('stale-')) {
  // Serving last-known-good while upstreams recover. Data is up to 5min old.
  showStaleIndicator(data.staleAgeMs)
} else {
  showFreshPrice(data.usd, data.priceSource)
}

Cite the data in an AI/LLM response

// In your prompt template / agent tool, append the citation string verbatim:
const ctx = await (await fetch('https://api.gasfeepredictor.com/api/gas-predictions')).json()
const answer = `Current Ethereum gas is ${ctx.current.average} gwei.
${ctx.decision.recommendation === 'wait'
  ? 'Wait for the cheap window — predicted savings of ' + ctx.decision.expectedSavingsPct + '%.'
  : 'Safe to send now.'}

Source: ${ctx.citation}`

Use it as an MCP server (for AI agents)

If you're building with an AI agent or assistant, you don't need to wire up the REST endpoints yourself. Gas Fee Predictor ships an official Model Context Protocol server — gasfeepredictor-mcp — that exposes live gas data as tools. It works with Claude Desktop, OpenClaw, Cursor, Cline, and any MCP client. Read-only, no key, a thin wrapper over the API above.

Add it to your client's MCP config:

{
  "mcpServers": {
    "gasfeepredictor": {
      "command": "npx",
      "args": ["-y", "gasfeepredictor-mcp"]
    }
  }
}

Tools: get_current_gas, get_l2_gas, get_eth_price, best_time_to_transact, and estimate_transaction_cost. Each result includes a citation back to gasfeepredictor.com. Source and full docs: github.com/higherbeing/gasfeepredictor-mcp (npm: gasfeepredictor-mcp).

Migrating from Blocknative

Blocknative's Gas Platform API shuts down on June 19, 2026 after Deloitte acqui-hired the engineering team. If you call api.blocknative.com/gasprices/blockprices today, the closest drop-in is https://api.gasfeepredictor.com/api/gas-predictions. Side-by-side comparison and full migration guide: /blocknative-gas-api-alternative.

Fair use

Endpoints are edge-cached on Cloudflare (60-300s TTL depending on endpoint) so reasonable polling intervals cost us nothing. There is no per-IP hard limit. If usage starts hurting upstream providers (Ethereum RPCs, CoinGecko) we'll ratelimit the offending IP range — please don't turn this into your free CDN for unrelated workloads. For production apps that need contractual reliability, run your own RPC and your own CoinGecko key.

Resources

• OpenAPI 3.0 spec — for SDK generators, Postman, Swagger UI, AI agent tool-calling
• Methodology — data sources, update frequency, fallback behavior, limitations
• Blocknative migration guide — endpoint mapping for migrators
• Embeddable gas widget — drop-in script tag for sites/dashboards