{
  "openapi": "3.1.0",
  "info": {
    "title": "mppgas",
    "version": "0.3.0",
    "description": "Multi-chain gas toolkit. Gas prices, EIP-1559 breakdown, 30-min forecasts, spike detection, and cheapest-time finder for Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, Tempo.",
    "x-guidance": "Call GET /api/gas for a quick 7-chain summary ($0.01). Use /api/gas/deep for full EIP-1559 breakdown ($0.02), /api/gas/forecast for 30-min trend ($0.02), /api/gas/spike?chain=X for spike detection ($0.01), /api/gas/best-time?chain=X for cheapest-hour analysis ($0.01). All paid endpoints use Tempo MPP x402. Agents only need USDC.e — gas-abstracted via feePayer."
  },
  "paths": {
    "/api/gas": {
      "get": {
        "operationId": "getGasPrices",
        "summary": "Gas prices for all 7 chains",
        "description": "Returns slow/standard/fast gas prices in gwei, native token USD price, and estimated 21000-gas transfer cost in USD. Results cached 10s per chain.",
        "x-payment-info": {
          "authMode": "paid",
          "protocols": ["x402"],
          "price": "0.01",
          "currency": "USDC.e",
          "currencyAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "network": "tempo",
          "chainId": 4217,
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "feePayer": true,
          "gasAbstracted": true
        },
        "x-mpp": {
          "price": 10000,
          "token": "USDC.e",
          "tokenAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "network": "tempo",
          "feePayer": true
        },
        "responses": {
          "200": {
            "description": "Gas data for all chains",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "chains": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "chain": { "type": "string" },
                          "slow": { "type": "number" },
                          "standard": { "type": "number" },
                          "fast": { "type": "number" },
                          "nativeUsd": { "type": "number" },
                          "transferCostUsd": { "type": "number" }
                        }
                      }
                    },
                    "cachedFor": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": { "description": "Payment required — attach x402 header with USDC.e." }
        }
      }
    },
    "/api/gas/deep": {
      "get": {
        "operationId": "getDeepGasPrices",
        "summary": "EIP-1559 breakdown for all 7 chains",
        "description": "Returns baseFee, priorityFee (slow/standard/fast), EIP-1559 maxFeePerGas and maxPriorityFeePerGas recommendations, latest block number and timestamp. Falls back to legacy gasPrice for non-EIP-1559 chains.",
        "x-payment-info": {
          "authMode": "paid",
          "protocols": ["x402"],
          "price": "0.02",
          "currency": "USDC.e",
          "currencyAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "network": "tempo",
          "chainId": 4217,
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "feePayer": true,
          "gasAbstracted": true
        },
        "x-mpp": {
          "price": 20000,
          "token": "USDC.e",
          "tokenAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "network": "tempo",
          "feePayer": true
        },
        "responses": {
          "200": {
            "description": "Deep EIP-1559 gas data per chain",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "chains": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "chain": { "type": "string" },
                          "chainId": { "type": "number" },
                          "blockNumber": { "type": "number" },
                          "blockTimestamp": { "type": "number" },
                          "eip1559": { "type": "boolean" },
                          "baseFee": { "type": ["number", "null"] },
                          "slow": { "type": "number" },
                          "standard": { "type": "number" },
                          "fast": { "type": "number" },
                          "priorityFee": { "type": ["object", "null"] },
                          "maxFeePerGas": { "type": ["object", "null"] },
                          "maxPriorityFeePerGas": { "type": ["object", "null"] }
                        }
                      }
                    },
                    "cachedFor": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": { "description": "Payment required." }
        }
      }
    },
    "/api/gas/forecast": {
      "get": {
        "operationId": "getGasForecast",
        "summary": "30-minute gas price forecast per chain",
        "description": "Linear trend forecast based on rolling 10-minute sample buffer (sampled every 60s). Returns now, in15min, in30min in gwei. Returns 'insufficient data' if fewer than 5 samples collected since last cold start.",
        "x-payment-info": {
          "authMode": "paid",
          "protocols": ["x402"],
          "price": "0.02",
          "currency": "USDC.e",
          "currencyAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "network": "tempo",
          "chainId": 4217,
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "feePayer": true,
          "gasAbstracted": true
        },
        "x-mpp": {
          "price": 20000,
          "token": "USDC.e",
          "tokenAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "network": "tempo",
          "feePayer": true
        },
        "responses": {
          "200": {
            "description": "Gas forecast per chain",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "chains": { "type": "array" },
                    "note": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": { "description": "Payment required." }
        }
      }
    },
    "/api/gas/spike": {
      "get": {
        "operationId": "detectGasSpike",
        "summary": "Gas spike detector for a single chain",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "default": "ethereum" },
            "description": "Chain name: ethereum, base, arbitrum, optimism, polygon, bsc, tempo"
          }
        ],
        "description": "Compares current standard gwei against rolling 1-hour average. Returns isSpike=true if current > avg + 2*stddev.",
        "x-payment-info": {
          "authMode": "paid",
          "protocols": ["x402"],
          "price": "0.01",
          "currency": "USDC.e",
          "currencyAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "network": "tempo",
          "chainId": 4217,
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "feePayer": true,
          "gasAbstracted": true
        },
        "x-mpp": {
          "price": 10000,
          "token": "USDC.e",
          "tokenAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "network": "tempo",
          "feePayer": true
        },
        "responses": {
          "200": {
            "description": "Spike detection result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "chain": { "type": "string" },
                    "current": { "type": "number" },
                    "avg1h": { "type": ["number", "null"] },
                    "stddev": { "type": ["number", "null"] },
                    "deviation": { "type": ["number", "null"] },
                    "isSpike": { "type": ["boolean", "null"] },
                    "status": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": { "description": "Payment required." }
        }
      }
    },
    "/api/gas/best-time": {
      "get": {
        "operationId": "getBestTimeToSend",
        "summary": "Cheapest hour to send a transaction",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "default": "ethereum" },
            "description": "Chain name: ethereum, base, arbitrum, optimism, polygon, bsc, tempo"
          }
        ],
        "description": "Analyzes 24-hour rolling buffer to find the UTC hour with minimum average standard gwei. Returns cheapestHourUtc, currentVsCheapest (%), and recommendation: send now | wait.",
        "x-payment-info": {
          "authMode": "paid",
          "protocols": ["x402"],
          "price": "0.01",
          "currency": "USDC.e",
          "currencyAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "network": "tempo",
          "chainId": 4217,
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "feePayer": true,
          "gasAbstracted": true
        },
        "x-mpp": {
          "price": 10000,
          "token": "USDC.e",
          "tokenAddress": "0x20C000000000000000000000b9537d11c60E8b50",
          "recipient": "0x0d509f743bc6fc907d5f63d8b0dae1fca8d80897",
          "network": "tempo",
          "feePayer": true
        },
        "responses": {
          "200": {
            "description": "Best time analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "chain": { "type": "string" },
                    "cheapestHourUtc": { "type": ["number", "null"] },
                    "currentHourUtc": { "type": "number" },
                    "currentVsCheapest": { "type": ["string", "null"] },
                    "recommendation": { "type": "string" },
                    "status": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": { "description": "Payment required." }
        }
      }
    },
    "/api/info": {
      "get": {
        "operationId": "getServiceInfo",
        "summary": "Service metadata",
        "description": "Returns service info, payment details, and endpoint list. Free, no payment required.",
        "responses": {
          "200": { "description": "Service metadata" }
        }
      }
    }
  }
}