# SiloVPS — VPS Compute API

> VPS compute for autonomous agents.
> Spin up servers, pay with crypto via MPP on Tempo.
> Prepaid compute billed per-minute. Buy as much time as you want, extend anytime. Expired servers are snapshotted for 72 hours.

## Authentication

All paid endpoints use the Machine Payments Protocol (MPP).
Send an unauthenticated request to receive a 402 challenge, then pay via Tempo and retry with your credential.
Your wallet address is your identity — it determines server ownership.

Free endpoints: GET /, GET /health, GET /llms.txt, GET /v1/catalog/*

## Pricing

Servers are billed **per minute** (minimum purchase: 1 minute).
A minimum charge of $0.01 applies to any single paid request, mirroring DigitalOcean's own per-droplet floor.

Server creation charges a one-time create fee plus prepaid compute time:
- small (1 vCPU, 1 GB): $0.02 create + $0.015/hr ($0.00025/min)
- medium (2 vCPU, 2 GB): $0.05 create + $0.045/hr ($0.00075/min)
- large (4 vCPU, 8 GB): $0.10 create + $0.155/hr ($0.00258/min)

Examples:
- Small server for 20 minutes = $0.02 + (20 × $0.00025) = $0.025
- Medium server for 6 hours = $0.05 + (360 × $0.00075) = $0.32
- Extend small by 1 minute = $0.00025 → floored to $0.01

Other charges:
- Extend time: hourly rate × (minutes / 60), with $0.01 minimum charge
- Reboot: $0.005
- Power on/off: $0.005
- SSH key registration: $0.001
- All other endpoints (list, get, delete, snapshots): free

## Workflow

1. Browse the catalog (free) — see available sizes, regions, images
2. Optionally register an SSH key ($0.001)
3. Create a server with prepaid minutes — single charge covers create fee + compute time
4. Poll for server status until active — response includes IP + root password
5. SSH in and do your work
6. Extend time if needed — POST /v1/servers/:id/extend with more minutes
7. Delete when done — snapshot saved for 72 hours automatically

If prepaid time runs out, the server is automatically snapshotted and destroyed.
You can restore from a snapshot within 72 hours by creating a new server with snapshot_id.

## Endpoints

### Catalog (free)

GET /v1/catalog/sizes
  Available server sizes with pricing (hourly rate and create fee).

GET /v1/catalog/regions
  Available regions: nyc1 (New York), sfo3 (San Francisco), ams3 (Amsterdam).

GET /v1/catalog/images
  Available OS images: Ubuntu 24.04 LTS, Debian 12.

### Servers

POST /v1/servers
  Create a new server. Charge: create fee + (hourly rate × minutes / 60).
  Body: { "size": "small|medium|large", "region": "nyc1|sfo3|ams3", "image": "ubuntu-24-04-x64", "minutes": 60, "ssh_key_ids": ["key_abc"], "snapshot_id": "snap_abc" }
  minutes defaults to 1 if omitted. No maximum — prepay as much as you want.
  Returns: { "id": "srv_abc", "status": "provisioning", "paid_until": "...", "minutes_purchased": 60, "total_charged": "0.035" }

POST /v1/servers/:id/extend
  Add more prepaid time. Charge: hourly rate × minutes / 60, minimum $0.01.
  Body: { "minutes": 120 }
  Returns: { "id": "srv_abc", "paid_until": "...", "minutes_added": 120, "charged": "0.03" }

GET /v1/servers
  List your active servers. Free. Requires wallet auth.

GET /v1/servers/:id
  Get server details including IP, root password, and remaining time. Free.

DELETE /v1/servers/:id
  Destroy server. A snapshot is saved for 72 hours automatically. Free.
  Returns: { "deleted": true, "snapshot": { "id": "snap_abc", "expires_in_hours": 72 } }

POST /v1/servers/:id/reboot
  Reboot server. Charge: $0.005.

POST /v1/servers/:id/power
  Power on or off. Charge: $0.005.
  Body: { "action": "on|off" }

### Snapshots

GET /v1/servers/snapshots/list
  List your available snapshots (not yet expired). Free.

### SSH Keys

POST /v1/keys
  Register an SSH key. Charge: $0.001.
  Body: { "name": "my-key", "public_key": "ssh-ed25519 AAAA..." }

GET /v1/keys
  List your registered SSH keys. Free.

DELETE /v1/keys/:id
  Remove an SSH key. Free.

## Snapshot Recovery

When a server is deleted or runs out of prepaid time, a snapshot is automatically saved.
Snapshots are retained for 72 hours. To restore:

POST /v1/servers { "size": "small", "region": "nyc1", "snapshot_id": "snap_abc", "minutes": 360 }

This creates a new server from the snapshot. Standard create fee + compute time applies.
After 72 hours, unclaimed snapshots are permanently deleted.