Gas Fee Predictor L2 API

openapi: 3.2.0
info:
  title: Gas Fee Predictor L2 API
  description: 'Free public JSON API for live Ethereum mainnet + Layer 2 gas fees, with active failover across multiple public RPCs, pattern-based 24h forecasts, and full wallet-fee estimates including L1 data fees on OP Stack chains. No API key, no signup. Methodology: https://gasfeepredictor.com/methodology'
  version: 1.0.0
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: Gas Fee Predictor
    url: https://gasfeepredictor.com
servers:
- url: https://api.gasfeepredictor.com
  description: Production (DNS-only subdomain — reachable from servers, workers, and curl; not behind the bot challenge)
tags:
- name: l2
  description: Layer 2 (Arbitrum, Optimism, Base, Polygon) gas data
paths:
  /api/l2-gas:
    get:
      tags:
      - l2
      summary: Live L2 gas across Arbitrum, Optimism, Base, Polygon
      description: Per-network execution gas + full wallet-fee estimate. For OP Stack chains (Optimism, Base), estimatedL1DataFeeUsd is queried live from the GasPriceOracle predeploy; for Arbitrum it is Nitro poster gas (NodeInterface.gasEstimateL1Component) × L2 base fee. Either way it is added to executionGasCostUsd. For Polygon (sidechain), no L1 fee applies.
      responses:
        '200':
          description: L2 gas snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/L2GasResponse'
      operationId: getApiL2Gas
      x-operation-id-source: derived
  /api/l2-gas-history:
    get:
      tags:
      - l2
      summary: Historical L2 gas prices
      description: 90-second-cadence samples for the requested L2 network and window, persisted to Postgres.
      parameters:
      - name: network
        in: query
        required: true
        schema:
          type: string
          enum:
          - arbitrum
          - optimism
          - base
          - polygon
      - name: hours
        in: query
        required: true
        schema:
          type: integer
          enum:
          - 1
          - 6
          - 24
          - 168
      responses:
        '200':
          description: L2 gas history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/L2GasHistoryResponse'
      operationId: getApiL2GasHistory
      x-operation-id-source: derived
components:
  schemas:
    L2NetworkReading:
      type: object
      properties:
        id:
          type: string
          enum:
          - arbitrum
          - optimism
          - base
          - polygon
        name:
          type: string
        nativeToken:
          type: string
          enum:
          - ETH
          - POL
        gasPriceGwei:
          type: number
        nativeUsd:
          type: number
        executionGasCostUsd:
          type: number
          description: L2 execution gas cost for a 21,000-gas transfer
        estimatedL1DataFeeUsd:
          type:
          - number
          - 'null'
          description: 'L1 data fee for a representative transfer: GasPriceOracle on OP Stack, Nitro poster gas × L2 base fee on Arbitrum. null for Polygon (sidechain, no L1) or when the live lookup failed.'
        estimatedWalletFeeUsd:
          type:
          - number
          - 'null'
          description: Full estimated wallet fee = executionGasCostUsd + estimatedL1DataFeeUsd. For Arbitrum/Polygon, equals executionGasCostUsd.
        feeCompleteness:
          type: string
          enum:
          - execution_only
          - full_estimate
        feeModel:
          type: string
          enum:
          - rollup_arbitrum_nitro
          - rollup_op_stack
          - sidechain
        blurb:
          type: string
        feeNote:
          type: string
    L2GasHistoryResponse:
      allOf:
      - $ref: '#/components/schemas/ApiMeta'
      - type: object
        properties:
          network:
            type: string
          hours:
            type: integer
          points:
            type: array
            items:
              type: object
              properties:
                timestamp:
                  type: string
                  format: date-time
                gas_price_gwei:
                  type: number
                execution_gas_cost_usd:
                  type: number
    ApiMeta:
      type: object
      description: Every public endpoint includes these fields. citation is a copy-paste-ready attribution string for AI agents and integrators. tier indicates the API tier (currently always 'free').
      properties:
        citation:
          type: string
          description: 'Stable attribution string. Format: ''Gas data from Gas Fee Predictor, gasfeepredictor.com, updated <ISO-8601>''.'
          example: Gas data from Gas Fee Predictor, gasfeepredictor.com, updated 2026-05-26T16:30:00Z
        tier:
          type: string
          enum:
          - free
          description: API tier. Currently 'free' for all requests.
      required:
      - citation
      - tier
    L2GasResponse:
      allOf:
      - $ref: '#/components/schemas/ApiMeta'
      - type: object
        properties:
          networks:
            type: array
            items:
              $ref: '#/components/schemas/L2NetworkReading'
          fetchedAt:
            type: string
            format: date-time
x-provenance:
  method: harvested
  publisher: Gas Fee Predictor
  source: https://api.gasfeepredictor.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)