{ "openapi": "3.0.3", "info": { "title": "1gwei.dev API", "version": "1.0.0", "description": "Custodial gas station API. Pay Monero (XMR) or Bitcoin Lightning to receive native gas (ETH, POL, HYPE, BNB) directly to any EVM wallet address across 8 chains in minutes. No account, no KYC, no API keys.", "contact": { "name": "1gwei.dev", "url": "https://1gwei.dev" } }, "x-service-info": { "categories": [ "cryptocurrency", "developer-tools", "infrastructure" ], "description": "Non-KYC crypto gas station API payable via Lightning or Monero." }, "servers": [ { "url": "https://1gwei.dev", "description": "Production HTTPS Gateway" }, { "url": "http://gweidevwva6wggquryozfuihb6iahdrcwnzjokurpkhxi46lavwkkbid.onion", "description": "Tor Hidden Service" } ], "paths": { "/api/v1": { "get": { "summary": "x402 Agent-Native Payment Gateway", "description": "Protected API gateway implementing the x402 payment protocol. Returns HTTP 402 with PAYMENT-REQUIRED header (USDC on Base) when accessed without payment signature.", "operationId": "x402Gateway", "x-payment-info": { "intent": "charge", "method": "tempo", "amount": 0.01, "currency": "USD", "description": "Agent-native micro-payment via x402 protocol (Base USDC)" }, "responses": { "200": { "description": "Access granted with verified payment", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string" }, "authenticated": { "type": "boolean" }, "x402": { "type": "boolean" } } } } } }, "402": { "description": "Payment Required via x402 Protocol", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded payment requirements object", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "number", "example": 2 }, "error": { "type": "string", "example": "Payment required" }, "resource": { "type": "object" }, "accepts": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/v1/orders": { "post": { "summary": "Create and fulfill gas order via x402 payment", "description": "Agent-native endpoint to order instant gas. An unpaid request returns HTTP 402 with dynamic USDC invoice for the specified amount and chain. When fulfilled with a signed x402 payment-signature header, native gas is immediately broadcast on-chain to the destination address.", "operationId": "createX402Order", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["destAddress", "chain", "ethAmount"], "properties": { "destAddress": { "type": "string", "description": "Recipient EVM wallet address", "example": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045" }, "chain": { "type": "string", "enum": ["ethereum", "arbitrum", "base", "polygon", "hyperevm", "bnb", "robinhood", "sepolia"], "example": "arbitrum" }, "ethAmount": { "type": "string", "description": "Amount of gas token (e.g. 0.005 ETH)", "example": "0.005" }, "sendAt": { "type": "string", "description": "Optional ISO 8601 timestamp for scheduled delivery" }, "ref": { "type": "string", "description": "Optional referral code/address" } } } } } }, "responses": { "201": { "description": "Payment verified and gas transaction broadcast", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "message": { "type": "string" }, "order": { "$ref": "#/components/schemas/PublicOrder" } } } } } }, "402": { "description": "Payment required with dynamic quote in body and PAYMENT-REQUIRED header" } } } }, "/api/quote": { "get": { "summary": "Get price quote", "description": "Calculate USD invoice amount based on live spot price and service margin for a desired gas amount.", "operationId": "getQuote", "parameters": [ { "name": "ethAmount", "in": "query", "required": true, "description": "Amount of native gas token desired (e.g. 0.0002 for ETH, 5 for POL, 0.01 for HYPE, 0.002 for BNB). Alias: eth.", "schema": { "type": "string", "example": "0.0002" } }, { "name": "chain", "in": "query", "required": false, "description": "Target EVM network.", "schema": { "type": "string", "enum": [ "ethereum", "arbitrum", "base", "polygon", "hyperevm", "bnb", "robinhood", "sepolia" ], "default": "ethereum" } } ], "responses": { "200": { "description": "Quote calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ethAmount": { "type": "string", "example": "0.0002" }, "ethUsd": { "type": "number", "example": 0.72 }, "spotUsd": { "type": "number", "example": 0.72 }, "margin": { "type": "number", "example": 0.5 }, "feeUsd": { "type": "number", "example": 0.36 }, "invoiceUsd": { "type": "number", "example": 1.08 } } } } } }, "400": { "description": "Invalid amount or unsupported chain" }, "503": { "description": "Price feed unavailable" } } } }, "/api/orders": { "post": { "summary": "Create a gas top-up order", "description": "Creates an order and returns payment details (Lightning invoice or Monero integrated address).", "operationId": "createOrder", "x-payment-info": { "intent": "charge", "method": "lightning", "amount": 1.00, "currency": "USD", "description": "Micro crypto gas top-up payable via Bitcoin Lightning invoice or Monero" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destAddress", "chain", "ethAmount", "method" ], "properties": { "destAddress": { "type": "string", "description": "Target EVM 0x wallet address to receive native gas.", "example": "0x1234567890123456789012345678901234567890" }, "chain": { "type": "string", "enum": [ "ethereum", "arbitrum", "base", "polygon", "hyperevm", "bnb", "robinhood", "sepolia" ], "example": "base" }, "ethAmount": { "type": "string", "description": "Amount of native gas token to dispense.", "example": "0.0002" }, "method": { "type": "string", "enum": [ "LN", "XMR" ], "description": "Payment rail: Bitcoin Lightning (LN) or Monero (XMR).", "example": "LN" }, "sendAt": { "type": "string", "nullable": true, "description": "Optional delayed payout time as unix milliseconds or ISO-8601 string." }, "walletToken": { "type": "string", "nullable": true, "description": "Optional client reference token echoed in order status." }, "ref": { "type": "string", "nullable": true, "description": "Optional referrer EVM address to earn 15% commission (prefix with arbitrum: for Arbitrum payout)." } } } } } }, "responses": { "201": { "description": "Order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Invalid parameters or bounds exceeded" }, "502": { "description": "Payment gateway creation failed" } } } }, "/api/orders/{id}": { "get": { "summary": "Get order status", "description": "Poll order state until terminal status (sent, failed, or expired).", "operationId": "getOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID (e.g. ord_...)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current order state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "description": "Order not found" } } } }, "/api/float": { "get": { "summary": "Get hot wallet float balances", "description": "Public hot-wallet address and live native gas balances across all supported chains.", "operationId": "getFloat", "responses": { "200": { "description": "Float balances per chain", "content": { "application/json": { "schema": { "type": "object", "properties": { "walletConfigured": { "type": "boolean" }, "address": { "type": "string", "example": "0x..." }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string" }, "balance": { "type": "string" }, "nativeSymbol": { "type": "string" }, "updatedAt": { "type": "number", "nullable": true }, "ok": { "type": "boolean" } } } } } } } } } } } }, "/api/meta": { "get": { "summary": "Get station metadata", "description": "Returns supported chains, preset packs, bounds, and service margin.", "operationId": "getMeta", "responses": { "200": { "description": "Metadata information", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/referrals/{address}": { "get": { "summary": "Get referral ledger", "description": "Returns referral credit ledger, accrued balance, and automatic payout history for an EVM address.", "operationId": "getReferralLedger", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Referrer EVM address (e.g. 0x... or arbitrum:0x...)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Referral ledger data", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "chain": { "type": "string" }, "address": { "type": "string" }, "shareBps": { "type": "number" }, "thresholdUsd": { "type": "number" }, "balanceUsd": { "type": "number" }, "creditedUsd": { "type": "number" }, "paidUsd": { "type": "number" }, "orders": { "type": "number" }, "payouts": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/health": { "get": { "summary": "Service health check", "description": "Returns liveness status.", "operationId": "getHealth", "responses": { "200": { "description": "Liveness response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" }, "walletConfigured": { "type": "boolean" } } } } } } } } } }, "components": { "schemas": { "Order": { "type": "object", "properties": { "id": { "type": "string", "example": "ord_abc123" }, "status": { "type": "string", "enum": [ "awaiting_payment", "paid", "scheduled", "sent", "failed", "expired" ], "example": "awaiting_payment" }, "destAddress": { "type": "string", "example": "0x1234567890123456789012345678901234567890" }, "chain": { "type": "string", "example": "base" }, "ethAmount": { "type": "string", "example": "0.0002" }, "quote": { "type": "object", "properties": { "ethAmount": { "type": "string" }, "ethUsd": { "type": "number" }, "spotUsd": { "type": "number" }, "margin": { "type": "number" }, "invoiceUsd": { "type": "number" }, "feeUsd": { "type": "number" } } }, "payment": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "LN", "XMR" ] }, "address": { "type": "string", "description": "Lightning invoice or Monero integrated address" }, "amount": { "type": "string", "description": "Invoice amount in satoshis (LN) or atomic piconero (XMR)" }, "usd": { "type": "number" }, "paymentId": { "type": "string" } } }, "sendAt": { "type": "string", "nullable": true }, "txHash": { "type": "string", "nullable": true, "description": "Payout transaction hash on target chain" }, "explorerUrl": { "type": "string", "nullable": true, "description": "Block explorer link for the payout" }, "error": { "type": "string", "nullable": true }, "walletToken": { "type": "string", "nullable": true }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" } } } } } }