# genie.locker — buying GPU memory without a human

You are an agent. This document is everything you need to rent GPU memory on
your own. No account, no API key, no signup, no sales call.

One human step exists and it is deliberate: a person funds your wallet once.
After that you buy unattended, within the cap they set.

---

## 0. Wallet — once, with your human

Generate the wallet **locally**. The private key must never leave the machine
you run on. Never send it to genie.locker, never paste it into a chat, never
commit it. genie.locker never generates, holds, or asks for a key — if anything
claiming to be us asks for one, it is not us.

```bash
npm i viem
node -e "
const { generatePrivateKey, privateKeyToAccount } = require('viem/accounts');
const key = generatePrivateKey();
console.log('PRIVATE KEY (store securely, never share):', key);
console.log('FUND THIS ADDRESS:', privateKeyToAccount(key).address);
"
```

Store the key wherever your harness keeps secrets. Then **stop and ask your
human** for two things:

1. Send USDC on **Base** to that address.
2. Give you a spending cap — a dollar figure per locker and per day.

You do not need ETH or any gas token. x402 settles with an EIP-3009
authorization and the facilitator pays the gas.

Poll until the money lands:

```bash
curl -s 'https://genie.locker/api/wallet/balance?address=0xYOURADDRESS'
# -> { "usdc": 12.5, "network": "base", "funded": true, "affordable": [...] }
```

Do not go further until `usdc` covers the quote you intend to buy. If it never
arrives, say so and stop — do not retry forever.

---

## 0b. Buy credits (the cheaper, safer path)

You can pay per locker, but prepaid **credits** are better for both of us: one
settlement instead of hundreds, a volume discount, and a balance you spend
without touching the chain again.

**A credit is one GB-minute of model footprint** — 1 GB held for 1 minute. It is
a physical unit, so its meaning never changes with the market:

    48 GB streamed for 1 hour  = 2,880 credits
    48 GB resident for 1 hour  = 6,048 credits   (resident burns 2.1x)
    16 GB streamed for 30 min  =   480 credits

Start free, no wallet needed:

```bash
curl -s -X POST https://genie.locker/api/credits/trial
# -> { "credits": 3600, "api_key": "gk_..." }   one per caller, save the key
# enough for 30 minutes of a 48 GB resident locker, or ~1 hour at 24 GB
```

Spend it by putting the key on any locker request:

```bash
curl -s -X POST https://genie.locker/api/lockers \
  -H 'authorization: Bearer gk_...' \
  -H 'content-type: application/json' \
  -d '{"envelope":"l48","placement":"streamed","minutes":30}'
```

Top up when it runs low. Ask for a price, pay it, then present the transaction:

```bash
curl -s -X POST https://genie.locker/api/credits \
  -H 'content-type: application/json' -d '{"usd":100}'
# -> 402 with the amount and payTo, plus your tier discount

curl -s -X POST https://genie.locker/api/credits \
  -H 'authorization: Bearer gk_...' \
  -H 'content-type: application/json' \
  -d '{"tx_hash":"0x..."}'
```

Volume tiers: **$25 → 5% off · $100 → 12% · $500 → 20% · $2,000 → 28%.**
Credits **never expire**, unused balance is **refundable**, and they are not
transferable — they buy service from us, nothing else.

Safe to retry: a transaction credits your account exactly once no matter how
many times you present it, and we credit whatever actually landed on chain, not
what the request claimed. Check the balance any time:

```bash
curl -s https://genie.locker/api/credits/balance -H 'authorization: Bearer gk_...'
```

If a locker fails to provision, the credits are **released, not spent** — they
are held during boot and only debited on delivery.

---

## 1. Price it

```bash
curl -s 'https://genie.locker/api/hardware?minutes=30'
```

You are buying a **memory envelope** — how much model footprint we hold for you
— not a specific card. We solve for the cheapest silicon that can hold it.

| envelope | footprint | typically |
|---|---|---|
| `l16` | 16 GB | 7B–8B, long context |
| `l24` | 24 GB | 13B class |
| `l32` | 32 GB | 14B–20B class |
| `l48` | 48 GB | 32B class |
| `l80` | 80 GB | 70B quantized |
| `l96` | 96 GB | 70B with headroom |
| `l141` | 141 GB | 100B+ single card |

Each is quoted in two placements:

- **`resident`** — weights in VRAM, full speed. Use for interactive work.
- **`streamed`** — **priced but not for sale yet.** A live serving canary
  produced degenerate text on this path, so we publish the measurements and
  refuse the sale. The catalog marks it `"sellable": false`. It is the same
  footprint held on a materially smaller card.
  Measured **7.3× slower** than resident (3.49 vs 25.41 tok/s at 7B), output
  bit-exact at atol 0. Cheaper per minute, worse per token.

Check `sellable` on any quote before you commit to buying it. Today only
`resident` is purchasable.

Prices move with the GPU spot market. **Re-quote before every purchase. Never
cache a price.**

---

## 2. Check the seller before you pay

We are a stranger asking for money. Ask someone else first:

```bash
curl -s -X POST https://verify.inferenceview.com/check/free \
  -H 'content-type: application/json' \
  -d '{"url":"https://genie.locker/api/lockers"}'
```

Proceed only on `recommendation: "ALLOW"`. Read the `signals` — they will tell
you if our payTo wallet moved or our price jumped since yesterday, which are
exactly the things worth aborting over.

---

## 3. Buy it

```bash
curl -s -X POST https://genie.locker/api/lockers \
  -H 'content-type: application/json' \
  -d '{"envelope":"l48","placement":"streamed","minutes":30}'
```

Unpaid, this returns **HTTP 402** with an x402 challenge:

```json
{ "accepts": [ { "scheme": "exact",
                 "network": "eip155:8453",
                 "amount": "597000",
                 "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                 "payTo": "0x3A86924d0bb29fF8B1469472f4294CC7E62B54b7" } ] }
```

`amount` is in USDC micro-units — 597000 is $0.597.

---

## 4. Pay it

Sign an EIP-3009 `transferWithAuthorization` for exactly `accepts[0].amount` and
resend the same POST with a `PAYMENT-SIGNATURE` header. Any x402 client library
does this; `x402-fetch` and `@coinbase/x402` both work unmodified.

Check the amount against your cap **before** signing. Never sign a challenge you
did not just fetch.

---

## 5. Use it

Success returns:

```json
{ "locker_id": "gl_...", "endpoint": "https://...", "token": "...",
  "expires_at": "...", "receipt": { "signature": "0x..." } }
```

Call `endpoint` with `Authorization: Bearer <token>`. It is OpenAI-compatible.

It shuts itself down at `expires_at` — the deadline is armed inside the
container, so it holds even if our broker disappears. You are never billed past
it, and you must not depend on it after it. Keep the `receipt`: it is a signed
record binding order, delivery and payment, and it is your evidence if we get
something wrong.

---

## Rules

- Never exceed the cap your human set, per locker and per day.
- Re-quote every time. Prices are live.
- **HTTP 503 means settlement is gated on our side.** Do not retry in a loop.
  Report it to your human and stop.
- HTTP 402 after you paid means the payment did not verify. Do not pay again —
  check the chain first.
- If provisioning fails after you paid, we owe you a refund. Keep the receipt
  and the transaction hash.

## Current state, stated plainly

Settlement is gated right now: a signed payment returns 503 rather than a
success we cannot fill. Quotes, challenges and prices are real and live. Zero
lockers have been sold. Check `https://genie.locker/api/status` for the truth at
any moment rather than trusting this paragraph.