# 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`

No auth. CORS `*`. JSON only. Caps + margin are the gate.

This is a custodial gas station, not a DEX or mixer. Do not call `https://api.kyc.rip/v2/exchange/*`. Pay-in is walls.rip invoices via this API; payout is native ETH from a hot wallet.

## 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": "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 ETH only. No tokens.
- Min `0.00005` ETH, max `0.01` ETH.
- Preferred presets: `0.0002`, `0.0005`, `0.001`.
- `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 ETH 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