# AgentMetal: llms.txt # An infra provider you can use start to finish. There's no signup: paying IS the signup. # Pay with USDC on Base (x402) or a card. Any plan, either rail, no account. # VMs from $1.20/day, with add-on block storage ($0.01/GB/day) and # bandwidth ($2/TB). Coming soon: Agent Memory (a cheap persistence layer in # plain Markdown for what you learn). # Status: Phase 1 is live: catalog/provision/status/list/extend/destroy/claim, # plus add-on storage/bandwidth and operate (reboot/diagnostics/exec). BASE_URL: https://api.agentmetal.dev FULL: https://agentmetal.dev/llms-full.txt # expanded manual (full endpoint + payment + MCP reference) ## Discover for free (no payment, no account) GET /v1/catalog -> plans (specs + per-day price), locations, selectable OS images, and add-on pricing (storage $/GB/day, bandwidth $/TB). Quote before you commit a payment. ## Provision a server (the whole product) 1) Request without payment: POST /v1/servers {"plan": "nano", "days": 7} Optional "os": pick an image, e.g. "debian-12" (default "ubuntu-24.04"). Optional "location": a zone. Omit it and you get Hetzner US (ash, then hil). "cdmx-1" is our own bare metal in Mexico City: Ubuntu 22.04/24.04 only, and SSH is on the box's own port of a shared IP (the 201 has ssh_port and the full ssh command). No storage, firewall or bandwidth add-ons there yet. GET /v1/catalog -> images for the list. Other fields: ssh_key, managed_key, via, code (coupon). -> 402 Payment Required listing ALL payment options: accepts[]: x402: exact USDC amount (atomic, 6dp), asset (USDC on Base), payTo address, terms in `description`. card: Stripe card rail: { checkout_url, session_id, poll, note }. 2a) USDC path (x402 v2, synchronous; use this if you're an autonomous agent): sign the accepts[0] requirement (EIP-3009 transferWithAuthorization, USDC on Base), base64-encode the payment payload, retry the identical request with: X-PAYMENT: Idempotency-Key: # replays return the original response -> 201 {id, status, plan, ipv4, ssh:"root@", expires_at, renew} NOTE: x402 is a SIGNED authorization in this header, not a transfer. Do NOT send USDC by hand to payTo: it isn't tied to a request, never provisions, and the funds are lost. Pay through an x402 client. Access: pass your own "ssh_key" (public key) in the request to authorize SSH; without one the box has no inbound SSH access. Managed key: pass "managed_key": true and we generate a server-side ed25519 keypair. You get the private key ONCE in the 201 response (we store it encrypted and never show it again). It's what lets /exec run commands. Helpers: @x402/fetch (+ @x402/evm; wraps both steps), or our MCP server (@agentmetal/mcp). Coupons: add "code":"AM-…" to the POST. A % code lowers the quoted amount on both rails (card checkout shows it). A 100% code skips payment and returns the box + a managed SSH key in the 201. Each code works once. A coupon can also grant a lease longer than the standard 1-30 cap (up to 90 days). 2b) Card path (async, human-in-the-loop): hand card.checkout_url to a human to pay in a browser, then poll card.poll (GET /v1/orders/) until it returns {status:"ready", server:{...}, ssh_private_key}. Card checkout can't carry your key, so we auto-issue a managed one and hand it back there (once; the human also sees it on /ok). If you hold a wallet, use 2a: it's one call. Failure guarantee: crypto is verify -> provision -> settle (never charged if provisioning fails). Card provisioning retries across locations and Stripe redelivers the webhook until it succeeds. We refund a charge only if no location can fulfil the server. You never keep a charge without a server. ## Plans (prepaid per day, 1-30 days per payment; any payer, no registration) nano 2vCPU/2GB/40GB $1.20/day (or $30/mo monthly with account) small 3vCPU/4GB/80GB $2.20/day (or $55/mo monthly with account) medium 4vCPU/8GB/160GB $4.20/day (or $99/mo monthly with account) All plans: 20 TB/mo egress incl., NVMe, US (ash + hil), port 25 blocked, hardened image. ## Add-ons (on a provisioned server) Bandwidth: buy extra egress at $2/TB beyond the 20 TB/mo included, via POST /v1/servers/{id}/bandwidth {"tb": N}. Storage: attach a block volume at $0.01/GB/day (prorated), via POST /v1/servers/{id}/storage {"gb": 10-1000}. Auto-mounted at /mnt/HC_Volume_. ## Accounts & claiming (optional, for convenience) Anonymous purchases keep working; the paying wallet/payment owns the server. Register an account and you 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","wallet_signature"]} -> {account, api_key, servers_claimed} (linking a wallet requires wallet_signature: sign "AgentMetal: link wallet to " with the wallet; omit it and the 400 hint returns the exact message.) ## Fair use (defaults, not gates) Default quotas (active servers per wallet/account, provisioning rate) are there to stop abuse; registered accounts get higher defaults. We may ask for verification (email/card) on risk signals, at our discretion. Quota errors say what happened and what to do next. Mining, DDoS and spam are banned. ## Endpoints GET /v1/catalog plans + locations + add-on pricing (free) 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/servers/:id/bandwidth {"tb": N} extra egress at $2/TB (402-gated) POST /v1/servers/:id/storage {"gb": 10-1000} block volume $0.01/GB/day (402-gated) POST /v1/servers/:id/reboot soft reboot (account key + ownership) GET /v1/servers/:id/diagnostics status + recent actions + VNC console + metrics, hypervisor-level, no SSH (account key + ownership) POST /v1/servers/:id/exec {"command", "timeout_seconds"?} run as root over SSH -> {exit_code, stdout, stderr}; 1-120s / 256 KB bounded; needs managed_key:true (account key + ownership) GET /v1/self who am I? call FROM the box; authed by source IP, no account (AWS-IMDS-style) -> {server_id, plan, status, ipv4, expires_at, firewall} GET /v1/servers/:id/firewall list inbound firewall rules POST /v1/servers/:id/firewall/rules {"protocol":"tcp","port":"443"} open a port DELETE /v1/servers/:id/firewall/rules {"protocol":"tcp","port":"443"} close a port (new boxes boot locked-down: inbound SSH(22)+ICMP only, everything else opened via these routes. Authed by source-IP from the box, OR account key + ownership off-box; last SSH(22) rule needs {"force":true} to remove) 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) for purchase/status; reboot/diagnostics/exec require Authorization: Bearer am_live_... AND ownership of the server. ## Connect via MCP (Model Context Protocol) Local: all tools; signs USDC payments with YOUR wallet: npx @agentmetal/mcp # set WALLET_PRIVATE_KEY = an EVM key with USDC on Base tools (13): provision_server, get_server, list_servers, extend_server, destroy_server, claim_account, verify_claim, get_catalog, reboot_server, server_logs, exec_command, get_firewall, manage_firewall Remote: 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 ## Lifecycle - T-24h before expiry: your server's preinstalled cron warns you (MOTD + file). - At expiry: status=expired, VM keeps running (2h grace). - Expiry+2h: 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. ## Guides Writeups (x402, the MCP setup, gasless USDC/EIP-3009, ephemeral compute, no-signup VPS): https://agentmetal.dev/blog/ RSS feed: https://agentmetal.dev/blog/feed.xml ## Humans Same API, same prices. Pay the card checkout link instead of signing USDC. Human docs: https://agentmetal.dev/docs/ Prefer a web console? AgentMetal Cloud (https://cloud.agentmetal.dev) is our own OpenStack cloud with a browser UI for people: VMs, private networks, load balancers, Heat stacks. Invite-only beta; not reachable through this API yet. Guide: https://agentmetal.dev/docs/#cloud