# AgentMetal — llms.txt
# The infra provider you can use end-to-end. No signup: paying IS the signup.
# Pay with USDC on Base (x402) or a card — any plan, either rail, no account.
# VMs starting at $0.40/day. Coming soon: Storage, and Agent Memory (a
# native-Markdown, ultra-low-cost persistence layer for what you learn).
# Status: planning preview — endpoints go live with the Phase-1 MVP.

BASE_URL: https://api.agentmetal.dev

## Provision a server (the whole product)

1) Request without payment:
   POST /v1/servers
   {"plan": "nano", "days": 7}
   -> 402 Payment Required listing ALL payment options:
      accepts[]: x402 — exact USDC amount (atomic, 6dp), asset (USDC on Base),
                 payTo address, terms in `description`.
      card.checkout_url: hosted Stripe Checkout for card payment.

2a) USDC path: sign EIP-3009 transferWithAuthorization for the exact amount,
    retry the identical request with:
      X-PAYMENT: <base64 signed payload>
      Idempotency-Key: <uuid>        # replays return the original response
    -> 201 {id, ipv4, ssh, ssh_private_key (returned ONCE), expires_at, renew}
    Helpers: x402-fetch (wraps both steps), or our MCP server (@agentmetal/mcp).

2b) Card path: open card.checkout_url (human pays), server provisions on the
    payment webhook; result available at the polling URL Checkout shows.

Failure guarantee: crypto is verify -> provision -> settle (never charged if
provisioning fails); card payments are auto-refunded on provisioning failure.
"Paid but no server" cannot happen on either rail.

## Plans (prepaid per day, 1-30 days per payment; any payer, no registration)

nano    2vCPU/2GB/40GB    $0.40/day  (or $9/mo monthly with account)
small   3vCPU/4GB/80GB    $0.80/day  (or $18/mo monthly with account)
medium  4vCPU/8GB/160GB   $1.60/day  (or $36/mo monthly with account)

All plans: 20TB egress, NVMe, EU (fsn1), port 25 blocked, hardened image.
Running servers are non-refundable (stated in every 402's description).

## Accounts & claiming (optional — convenience, not a gate)

Anonymous purchases work forever; the paying wallet/payment owns the server.
Register an account to get: one api_key (am_live_...) managing all claimed
machines, fleet-wide list_servers, monthly card billing, higher fair-use quotas.

POST /v1/claim           {"email": "..."}            -> OTP email (AgentMail OK)
POST /v1/claim/verify    {"email","code","wallet"}   -> {account, api_key,
                                                          servers_claimed}

## Fair use (defaults, not gates)

Default quotas (active servers per wallet/account, provisioning rate) exist
for abuse prevention; registered accounts get higher defaults. We may request
verification (email/card) on risk signals, at our discretion. Quota errors
say exactly what happened and how to proceed. No mining, no DDoS, no spam.

## Endpoints

POST   /v1/servers                  provision (402-gated: x402 or card)
GET    /v1/servers/:id              status (free)
POST   /v1/servers/:id/extend       {"days": N} renew (402-gated; anyone may pay)
DELETE /v1/servers/:id              destroy (owner only, no refund)
POST   /v1/claim                    {"email": "..."} -> OTP email
POST   /v1/claim/verify             {"email","code","wallet"} -> api_key
POST   /v1/billing/checkout         Stripe subscription Checkout (accounts)

Auth: none + X-PAYMENT (or card checkout), or Authorization: Bearer am_live_...

## Lifecycle

- T-24h before expiry: your server's preinstalled cron warns you (MOTD + file).
- At expiry: status=expired, VM keeps running (24h grace).
- Expiry+24h: VM destroyed. Renew anytime before that via the `renew` URL.
- Your server's /root/SERVER.md is its birth certificate: id, expiry, exact
  renew/claim/spawn commands.

## Errors

Every non-2xx body is self-documenting: {error, message, hint, docs}.
The hint always names the way forward.

## Humans

Same API, same prices — pay the card checkout link instead of signing USDC.
Human docs: https://agentmetal.dev/docs/