# AgentMetal — llms.txt
# The server provider you can use end-to-end: discover -> pay -> provision -> operate -> renew.
# No signup, no API key to buy. Pay USDC over x402 (v2) on Base, or a card.

BASE_URL: https://api.agentmetal.dev

## Start here: the free catalog (no payment, no account)

  GET /v1/catalog
  -> { plans:[{ id, vcpu, memory_gb, disk_gb, usd_per_day, usd_per_month }],
       locations:[{ code, city, country }],
       bandwidth:{ included_tb, extra_usd_per_tb },
       storage:{ usd_per_gb_day, min_gb, max_gb } }

  Call this first to see sizes, regions, and prices before you pay anything.

## Provision a server

1) Request without payment:
     POST /v1/servers
     {"plan": "nano", "days": 7}          # plan: nano|small|medium, days: 1-30
   optional fields:
        os:           OS image, e.g. "ubuntu-24.04" (default) or "debian-12".
                      See GET /v1/catalog -> images for the full list.
        ssh_key:      your public key (root@<ip> login)
        via:          free-form attribution tag (e.g. the calling skill/agent);
                      recorded for our channel stats. NOT a location selector —
                      location is chosen automatically (EU when available, else US).
        managed_key:  true -> we generate the keypair; the 201 returns
                      ssh_private_key ONCE (stored only encrypted server-side).
                      Lets you SSH in (and use /exec) without bringing a key.
        code:         a single-use coupon. A % code lowers the quoted amount on
                      BOTH rails (and shows in card checkout); a 100% code skips
                      payment entirely -> 201 with the box + a managed SSH key.
                      A coupon may also grant a longer lease (up to 90 days) than
                      the standard 1-30 cap.
   -> 402 Payment Required. The body is an x402 v2 PaymentRequired:
        x402Version: 2
        accepts[]: { scheme:"exact", network:"eip155:8453",
                     asset:"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" (USDC), amount:"<atomic, 6dp>",
                     payTo:"0x...", maxTimeoutSeconds:120 }
        resource: { url, description }
        card: optional Stripe card rail (>= $0.50): { checkout_url, session_id, poll, note }

2) USDC path (synchronous — recommended for autonomous agents): sign the accepts[0] requirement
   with your wallet, base64-encode the x402 payment payload, and resend the identical request with:
        X-PAYMENT: <base64 payload>
        Idempotency-Key: <uuid>     # replays return the original response
   NOTE: x402 is a SIGNED authorization carried in this header, NOT a transfer. Do not manually
   send USDC to payTo — an out-of-band transfer is not tied to any request, never provisions a
   server, and the funds are lost. Always pay through an x402 client (below).
   -> 201 { id, status, plan, ipv4, ssh:"root@<ip>", expires_at, renew }
        (+ ssh_private_key once, if you sent managed_key:true)
   NOTE: sshd is still booting at the 201 — the box accepts SSH ~10-15s later. Retry on
   "connection refused" for the first ~20s.
   If the payment is rejected you get 402 again with a "payment_error" object:
        { reason, required_atomic, required_usdc, message, hint }
   The usual cause is the payer wallet holding less USDC than required_usdc — top up and retry.

   Free trial / pre-flight: add "dry_run": true to the POST body to validate your WHOLE
   payment pipeline at no cost — the API verifies your signed X-PAYMENT (signature + on-chain
   funds) and returns { dry_run, payment_valid, would_provision, quote } WITHOUT charging or
   provisioning. Use it to confirm you can pay before committing real money.

   Card path (async, human-in-the-loop — a card cannot be signed by an autonomous agent): hand
   card.checkout_url to a human to pay in a browser, then poll card.poll (GET /v1/orders/<session_id>)
   every few seconds. While the payment is unconfirmed it returns { status:"pending" }; once paid +
   provisioned it returns { status:"ready", server:{ id, ipv4, ssh, ... }, ssh_private_key } — that
   closes the loop and hands you the box plus its auto-issued managed SSH key (card checkout can't
   carry your own key, so we generate one; save it, it's only available briefly). The human also
   sees the key on the /ok page. Autonomous agents should prefer the USDC path (one call, no polling).

   Helpers (recommended — they hide the EIP-3009 signing): the @agentmetal/mcp MCP server, or
   the x402 *v2* client (@x402/fetch + @x402/evm). NOTE: the old x402-fetch v1 does NOT parse
   this v2 quote (eip155:8453, nested resource) — use the scoped @x402/* v2 packages, or just
   use @agentmetal/mcp. With @x402/evm, sign with a viem LocalAccount (not a WalletClient).

## Endpoints

  GET    /v1/catalog                  plans/locations/prices (PUBLIC, FREE)
  POST   /v1/servers                  provision (402-gated)
  GET    /v1/servers?wallet=0x...     list your fleet (or Bearer am_live_... key)
  GET    /v1/servers/{id}             status (incl. bandwidth usage + storage volumes)
  POST   /v1/servers/{id}/extend      renew the lease (402-gated)        {"days": 7}
  POST   /v1/servers/{id}/bandwidth   buy extra egress, $2/TB (402-gated) {"tb": 5}
  POST   /v1/servers/{id}/storage     attach a block volume (402-gated)  {"gb": 50}
  POST   /v1/servers/{id}/reboot      soft reboot (account key + ownership)
  GET    /v1/servers/{id}/diagnostics hypervisor view, no login (account key + ownership)
  POST   /v1/servers/{id}/exec        run a root command over SSH (see below)
  DELETE /v1/servers/{id}             destroy early (account key + ownership)
  GET    /v1/self                     who am I? (call FROM the box; no account — see below)
  GET    /v1/servers/{id}/firewall    list inbound firewall rules
  POST   /v1/servers/{id}/firewall/rules   open a port  {"protocol":"tcp","port":"443"}
  DELETE /v1/servers/{id}/firewall/rules   close a port {"protocol":"tcp","port":"443"}
  POST   /v1/claim                    {"email"} -> 6-digit OTP emailed (AWS SES)
  POST   /v1/claim/verify             {"email","code","wallet?","wallet_signature?"}
                                      -> { account, api_key: "am_live_..." }
  POST   /v1/billing/checkout         monthly card subscription (account key)
  POST   /v1/webhooks/stripe          Stripe fulfillment webhook
  GET    /health
  GET    /llms.txt , /agents.md       this manual + a short manifest
  /mcp                                remote MCP endpoint (see below)

## Add-ons (buy against a running server, each 402-gated)

  Bandwidth: every server includes 20 TB/mo egress; buy more at $2/TB:
    POST /v1/servers/{id}/bandwidth {"tb": N}
  Storage:   attach block storage at $0.01/GB/day (prorated to the remaining lease),
    POST /v1/servers/{id}/storage {"gb": 10-1000}
    -> auto-formatted + mounted at /mnt/HC_Volume_<id> (returned in the response).

## Operate a running server (account key + ownership required)

  /reboot       soft (graceful ACPI) reboot.
  /diagnostics  hypervisor-level view WITHOUT logging into the box: status, recent
                provider actions (with errors), a VNC console URL, and live CPU/disk/
                network metrics. (The provider exposes no text boot log.)
  /exec         POST {"command", "timeout_seconds"?} -> run as root over SSH; returns
                { exit_code, stdout, stderr, timed_out }. Requires the server to have
                been provisioned with managed_key:true. Bounded: 1-120s timeout
                (default 60), 256 KB output cap.

## Self-management from the box (no account, no key — like AWS IMDS)

  If you can run commands ON your box, you can manage it WITHOUT an account or any
  stored secret. Authentication is your source IP: a request that originates from the
  box's own public IP is trusted as that box (AWS-IMDS-style — being on the box is the
  credential). So, from a shell on the box:
    curl -s https://api.agentmetal.dev/v1/self                       # { server_id, plan, status, ipv4, expires_at, firewall }
    curl -s -X POST https://api.agentmetal.dev/v1/servers/<id>/firewall/rules -d '{"protocol":"tcp","port":"443"}'
    curl -s -X DELETE https://api.agentmetal.dev/v1/servers/<id>/firewall/rules -d '{"protocol":"tcp","port":"443"}'
  Boxes boot locked-down (inbound SSH + ICMP only) when edge-firewalled; open the ports
  you serve. Closing the last SSH(22) rule needs {"force":true}. Off-box / fleet owners
  use the same routes with an account key (Authorization: Bearer am_live_...).

## Connect via MCP (Model Context Protocol)

  Local server — full tools, signs USDC payments with YOUR wallet:
    npx @agentmetal/mcp        (set WALLET_PRIVATE_KEY = an EVM key with USDC on Base)
    tools: provision_server, get_server, list_servers, extend_server, destroy_server, get_catalog, reboot_server, exec_command, server_logs, get_firewall, manage_firewall, claim_account, verify_claim
  Remote server — no key; discover + quote + status only. Add this URL as a
  custom/remote MCP connector in ChatGPT (Developer mode), Claude.ai, or Le Chat:
    https://api.agentmetal.dev/mcp
    tools: list_plans, get_payment_options, get_server, list_servers

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

  nano    2vCPU/2GB/40GB   $1.20/day  (or $30/mo with an account)
  small   3vCPU/4GB/80GB   $2.20/day  (or $55/mo with an account)
  medium  4vCPU/8GB/160GB   $4.20/day  (or $99/mo with an account)

  Locations: ash (Ashburn, US), hil (Hillsboro, US). See /v1/catalog for the live list.
  USDC amounts are atomic (6 decimals): $1.20 = "1200000".

## Accounts (optional)

  Anonymous purchase works forever; the paying wallet owns the server. Claim an
  account (email OTP via AWS SES) to get one am_live_ key that manages your fleet
  and unlocks reboot, diagnostics, exec, early destroy, and monthly card billing.

## Notes

  - Every box boots with /root/SERVER.md describing itself + how to renew/spawn.
  - Errors are JSON envelopes: { error, message, docs }.