# Stablerails

> Free, open-source (AGPL-3.0), self-hosted, non-custodial stablecoin payment
> software. Watch-only server + local signer. USDT on Tron today;
> Polygon/Ethereum/USDC on the roadmap. 0% fees — the only cost is network gas,
> paid to the blockchain. No-KYC, not anonymous.

Security contract: the server holds no keys and physically cannot move funds;
AI agents get readonly access and physically cannot move funds; funds move ONLY
when a human types the seed passphrase at a local terminal.

## Setup

- Agent runbook: /agents.md (hand this file to your AI agent)
- One-command bootstrap (operator box, DATABASE_URL set):
  npx stablerails init --format json
  → emits { operatorId, adminKey, mcpKey, eventId, seedStatus, magicLinkUrl, expiresAt }
- Seed encryption is always a human TTY step: stablerails seed init
- Sweep execution is always a human TTY step: stablerails sweep execute --intent <id>

## Key URLs

- /docs — human-readable API reference (auth, invoices, webhooks, HMAC signing)
- /agents.md — AI-agent onboarding runbook (this server, markdown)
- /llms.txt — this file
- /pay/:id — hosted checkout page for an invoice (public)
- /v1 — JSON API base (Bearer auth; key scopes: readonly < merchant < admin)

## API quick reference

- POST /v1/invoices — create invoice (merchant+); Idempotency-Key supported
- GET /v1/public/invoices/:id — sanitized status for checkout polling (public)
- POST /v1/webhooks — register HTTPS webhook (admin); HMAC-SHA256 signed deliveries
- POST /v1/sweeps/prepare — build unsigned sweep transfers (no keys involved)
- MCP server (readonly key via STABLERAILS_MCP_KEY): event/invoice/webhook reads,
  sweep_prepare, sweep_status — no tool can move funds, passphrase is never a
  tool parameter.