# 1gwei.dev agent spec > Pay XMR or Lightning. Get a little native gas (ETH, POL, HYPE or BNB) on Ethereum, Arbitrum, Base, Robinhood Chain, Polygon, HyperEVM, BNB Chain, or Sepolia. Base URL: `https://1gwei.dev` Tor mirror: `http://gweidevwva6wggquryozfuihb6iahdrcwnzjokurpkhxi46lavwkkbid.onion` (same routes, same API, no auth) OpenAPI 3.0 JSON spec: `https://1gwei.dev/openapi.json` No auth. CORS `*`. JSON only. Caps + margin are the gate. This is a custodial gas station, not a DEX or mixer. Pay-in is via this API; payout is native gas (ETH, POL, HYPE or BNB) from a hot wallet. ## Referrals - Any EVM address is a referral code. Send it as `ref` on `POST /api/orders` (`"ref": "0x…"` or `"ref": "arbitrum:0x…"` to be paid on Arbitrum instead of Base). Invalid codes are ignored, never rejected. - Credit: 15% of the invoice excluding the pass-through gas fee, i.e. 0.15 × spot × (1 + margin), booked in USD when the referred order reaches `sent`. Orders whose destination is the referrer's own address earn nothing. - Payout: automatic, in ETH at spot on the code's chain, once the balance reaches `REFERRAL_PAYOUT_USD` (default $5), minus that one network fee. Deferred while gas is above the cap or the float is short. - `GET /api/referrals/{code}` → `{ code, chain, address, shareBps, thresholdUsd, balanceUsd, creditedUsd, paidUsd, orders, onHold, payouts: [{ usd, feeUsd, ethAmount, chain, txHash, explorerUrl, status, at }] }`. No order ids, destinations or payment ids are exposed. ## Flow 1. `GET /api/quote?ethAmount=0.0002` (optional, to show the user the USD invoice). 2. `POST /api/orders` with destination, chain, amount, and `XMR` or `LN`. 3. Show `payment.address` (XMR address or Lightning invoice) and `payment.amount`. 4. Poll `GET /api/orders/{id}` every 3–8s until a terminal status. 5. On `sent`, give the user `txHash` and `explorerUrl`. The server re-checks the invoice on each GET while `status` is `awaiting_payment`. A Worker cron also polls and dispatches. You do not need a webhook. ## Quote `GET /api/quote?ethAmount=0.0002` `ethAmount` is required (alias `eth`). 400 if missing or out of range. 503 if the ETH/USD feed is down. ```json { "ethAmount": "0.0002", "ethUsd": 0.72, "margin": 0.5, "spotUsd": 0.72, "invoiceUsd": 1.08, "feeUsd": 0.36 } ``` `invoiceUsd` is what the user pays. `margin` is currently `0.5` (50%). Confirm live values with `/api/meta`. ## Create order `POST /api/orders` ```json { "destAddress": "0x...", "chain": "sepolia", "ethAmount": "0.0002", "method": "LN" } ``` Optional: - `sendAt`: unix milliseconds or ISO-8601. If in the future, after payment the order becomes `scheduled` and ETH is sent at that time. - `walletToken`: opaque string you round-trip; echoed on the order. Do not put secrets here. `201` body (public order): ```json { "id": "ord_...", "status": "awaiting_payment", "destAddress": "0x...", "chain": "sepolia", "ethAmount": "0.0002", "quote": { "ethAmount": "0.0002", "ethUsd": 0.72, "margin": 0.5, "spotUsd": 0.72, "invoiceUsd": 1.08, "feeUsd": 0.36 }, "payment": { "method": "LN", "address": "lnbc...", "amount": "1080", "usd": 1.08, "paymentId": "..." }, "sendAt": null, "txHash": null, "explorerUrl": null, "error": null, "walletToken": null, "createdAt": 0, "updatedAt": 0 } ``` For `method: "XMR"`, `payment.address` is a Monero address and `payment.amount` is the XMR amount to send. For `LN`, `payment.address` is a BOLT11 invoice. Errors: `400` invalid input, `502` payment create or feed failed. ## Poll `GET /api/orders/{id}` Same public order shape. `404` if unknown. Statuses: - `awaiting_payment` — show invoice, keep polling - `paid` — payout in flight, keep polling - `scheduled` — paid, waiting for `sendAt` - `sent` — done; use `txHash` / `explorerUrl` - `expired` — invoice timed out; create a new order - `failed` — payout failed; `error` may explain Terminal: `sent`, `expired`, `failed`. ## Meta / health `GET /api/meta` ```json { "chains": [ { "key": "ethereum", "label": "Ethereum", "chainId": 1, "explorerTx": "https://etherscan.io/tx/", "nativeSymbol": "ETH" }, { "key": "arbitrum", "label": "Arbitrum", "chainId": 42161, "explorerTx": "https://arbiscan.io/tx/", "nativeSymbol": "ETH" }, { "key": "base", "label": "Base", "chainId": 8453, "explorerTx": "https://basescan.org/tx/", "nativeSymbol": "ETH" }, { "key": "robinhood", "label": "Robinhood", "chainId": 4663, "explorerTx": "https://robinhoodchain.blockscout.com/tx/", "nativeSymbol": "ETH" }, { "key": "polygon", "label": "Polygon", "chainId": 137, "explorerTx": "https://polygonscan.com/tx/", "nativeSymbol": "POL" }, { "key": "hyperevm", "label": "HyperEVM", "chainId": 999, "explorerTx": "https://hyperevmscan.io/tx/", "nativeSymbol": "HYPE" }, { "key": "bnb", "label": "BNB Chain", "chainId": 56, "explorerTx": "https://bscscan.com/tx/", "nativeSymbol": "BNB" }, { "key": "sepolia", "label": "Sepolia", "chainId": 11155111, "explorerTx": "https://sepolia.etherscan.io/tx/", "nativeSymbol": "ETH" } ], "presets": ["0.0002", "0.0005", "0.001"], "margin": 0.5, "tagline": "Pay XMR or Lightning. Get a little gas." } ``` `GET /api/health` → `{ "ok": true, "service": "1gwei.dev", "walletConfigured": true }` If `walletConfigured` is false, do not create orders. ## Float `GET /api/float` Unauthenticated. Reports the hot wallet address (derived from the configured key; the key itself is never returned) and native balances on each chain. ```json { "address": "0x...", "walletConfigured": true, "chains": [ { "key": "ethereum", "chainId": 1, "label": "Ethereum", "nativeSymbol": "ETH", "balanceWei": "0", "balanceEth": "0", "rpcOk": true } ] } ``` If no key is configured, `address` is `null`, `walletConfigured` is false, and chain rows skip balance reads (`rpcOk` false). A per-chain RPC failure sets `rpcOk` false and may include `error`. ## Limits - Native gas only (ETH, POL, HYPE, or BNB depending on chain). No ERC-20/wrapped tokens. - Min `0.00005` ETH, max `0.01` ETH (on ETH chains). - Preferred presets: `0.0002`, `0.0005`, `0.001` ETH. - `destAddress` must be a checksum-or-any `0x` EOA/contract on that chain. - `chain` must be one of `ethereum` | `arbitrum` | `base` | `robinhood` | `polygon` | `hyperevm` | `bnb` | `sepolia`. On `polygon` the amount is in POL, on `hyperevm` in HYPE, on `bnb` in BNB (each chain's gas token), everywhere else in ETH; see `tokens` in `/api/meta` for presets and bounds per token. ## Agent notes - Prefer a preset amount. Tiny gas is the product; large swaps belong elsewhere. - High margin is intentional (small gas, high UX). Show `invoiceUsd` honestly. - Do not invent other endpoints. Do not scrape the HTML console. - Human UI: https://1gwei.dev - Short index: https://1gwei.dev/llms.txt - OpenAPI spec: https://1gwei.dev/openapi.json - Guides & Comparisons: - https://1gwei.dev/guides/fund-gas-without-kyc - https://1gwei.dev/guides/unstick-bep20-usdt-zero-bnb - https://1gwei.dev/guides/polymarket-usdc-without-pol - https://1gwei.dev/guides/buy-sepolia-eth-with-monero - https://1gwei.dev/guides/gas-station-vs-bridges - https://1gwei.dev/guides/gas-station-vs-centralized-exchanges - https://1gwei.dev/guides/gas-station-vs-dex-swaps - https://1gwei.dev/guides/move-usdc-hyperevm-zero-hype - https://1gwei.dev/guides/move-usdc-base-zero-eth-no-coinbase - https://1gwei.dev/guides/gas-station-vs-smolrefuel-gaszip-walletgas - https://1gwei.dev/guides/buy-evm-gas-with-bitcoin-lightning - https://1gwei.dev/guides/xmr-micro-gas-vs-xmr-eth-swap-minimums - https://1gwei.dev/guides/arbitrum-claim-or-move-tokens-zero-eth - https://1gwei.dev/guides/fix-metamask-insufficient-funds-for-gas-without-kyc - https://1gwei.dev/guides/robinhood-chain-eth-gas-stock-tokens - https://1gwei.dev/guides/airdrop-claim-no-eth-fund-gas-privately - https://1gwei.dev/guides/agent-api-scripted-gas-top-ups - https://1gwei.dev/guides/buy-gas-with-x402-zero-base-eth - https://1gwei.dev/guides/fresh-wallet-first-gas-without-kyc - https://1gwei.dev/guides/move-erc20-ethereum-zero-eth - https://1gwei.dev/guides/pay-gas-with-usdc-usdt-reality