# ethgasnow

> Ethereum gas state for agents. One free endpoint, two paid ones. Paid calls cost a fraction of a cent in USDC on Base, settled over x402. No account and no signup.

All data is recomputed every 5 minutes from Ethereum mainnet. Every payload carries `timestamp` and `block_number` so you can judge its age yourself. The prediction is for the block after `block_number`, which can be up to 5 minutes old.

## Endpoints

- [GET /v1/status](https://api.ethgasnow.com/v1/status): free. Base fee and ETH price, 5 minutes delayed, plus feed health.
- [GET /v1/predict](https://api.ethgasnow.com/v1/predict): 0.001 USDC. Next-block base fee prediction, an execute or wait signal, and the USD cost of four common actions.
- [GET /v1/matrix](https://api.ethgasnow.com/v1/matrix): 0.002 USDC. USD cost of eight common actions at slow, standard and fast gas, a Base, Arbitrum and Optimism swap comparison, and 24h base fee percentiles.

## How to pay

1. Call a paid endpoint with no payment. You get `402 Payment Required` and a base64 `PAYMENT-REQUIRED` header with the price.
2. Sign a USDC payment for that amount and call again with it in the `PAYMENT-SIGNATURE` header.
3. You get `200` with the data and a `PAYMENT-RESPONSE` header with the settlement.

- Protocol: x402 version 2, scheme `exact`
- Network: Base mainnet (`eip155:8453`)
- Token: USDC
- Pay to: `0x604E663D5d1A04266D3565E7A5A915439F2b5E01`

If the data is not available you get a 503 and you are not charged.

Holders of a prepaid key send it as `X-API-Key`. Each paid call uses one credit and skips the 402.

## Reading the signal

`agent_signal.action` is one of:

- `EXECUTE_NOW`: the base fee is in the cheapest 35% of the last 24h, or the next block is set to rise more than 5%.
- `WAIT`: the base fee is in the most expensive 30% of the last 24h and falling.
- `HOLD_OR_STANDARD`: neither. Send at the standard tier if you need to send.

`percentile_24h` is the share of the last 24h with a base fee below the current one. 0 is the cheapest moment of the day. `confidence` runs from 0.50 to 0.99 and falls as the base fee gets more volatile across the last 10 blocks.

## GET /v1/predict example

```json
{
  "timestamp": 1794355200,
  "block_number": 24718350,
  "eth_usd": 3412.55,
  "agent_signal": {
    "action": "EXECUTE_NOW",
    "confidence": 0.91,
    "reason": "Base fee is lower than 78.4% of the last 24h."
  },
  "eip1559": {
    "current_base_fee_gwei": 0.8421,
    "predicted_next_block_base_fee_gwei": 0.8105,
    "gas_used_ratio": 0.35,
    "priority_fee_gwei": {
      "p10": 0.01,
      "p50": 0.05,
      "p90": 0.5
    },
    "max_fee_gwei": {
      "slow": 0.8205,
      "standard": 0.8605,
      "fast": 1.3105
    },
    "percentile_24h": 21.6,
    "samples_24h": 288
  },
  "execution_costs_usd": [
    {
      "slug": "eth_transfer",
      "name": "ETH transfer",
      "gas_limit": 21000,
      "cost_usd": 0.0617
    },
    {
      "slug": "erc20_transfer",
      "name": "ERC-20 transfer",
      "gas_limit": 65000,
      "cost_usd": 0.1909
    },
    {
      "slug": "opensea_seaport_buy",
      "name": "OpenSea Seaport buy",
      "gas_limit": 145000,
      "cost_usd": 0.4258
    },
    {
      "slug": "uniswap_v3_swap",
      "name": "Uniswap V3 swap",
      "gas_limit": 184500,
      "cost_usd": 0.5418
    }
  ]
}
```

## GET /v1/matrix example

One entry of `actions` and one of `chains` shown. The live response has eight actions and three chains.

```json
{
  "timestamp": 1794355200,
  "block_number": 24718350,
  "eth_usd": 3412.55,
  "gas_gwei": {
    "slow": 0.8205,
    "standard": 0.8605,
    "fast": 1.3105
  },
  "actions": [
    {
      "slug": "eth_transfer",
      "name": "ETH transfer",
      "category": "transfer",
      "gas_limit": 21000,
      "cost_usd": {
        "slow": 0.0588,
        "standard": 0.0617,
        "fast": 0.0939
      }
    }
  ],
  "l2_swap_comparison": {
    "reference_action": "uniswap_v3_swap",
    "gas_limit": 184500,
    "l1_swap_cost_usd": 0.5418,
    "chains": [
      {
        "chain": "base",
        "chain_id": 8453,
        "gas_price_gwei": 0.0061,
        "swap_cost_usd": 0.003841,
        "vs_l1_pct": -99.29
      }
    ],
    "note": "L2 figures are execution gas only."
  },
  "base_fee_24h": {
    "samples": 288,
    "min_gwei": 0.41,
    "p10_gwei": 0.62,
    "p50_gwei": 1.18,
    "p90_gwei": 2.9,
    "max_gwei": 7.3,
    "current_percentile": 21.6
  }
}
```

## Machine-readable

- [x402 manifest](https://api.ethgasnow.com/.well-known/x402.json)
