API Overview

PayWarden exposes a REST API for creating and managing payment orders.

Base URL

http://localhost:3000/api/v1      # local development
https://pay.yourdomain.com/api/v1 # production[^1]

[^1]: pay.yourdomain.com is illustrative. The operator is responsible for placing PayWarden behind a reverse proxy (TLS termination, hostname, rate limiting) in production.

Authentication

PayWarden has two auth surfaces — see Authentication for details.

• Merchant API — X-API-Key header. Required on all merchant endpoints.
• Admin API — httpOnly admin_token cookie. No Bearer token support.

The following endpoints are public (no authentication required):

Endpoint	Purpose
GET /api/v1/health	Readiness probe (ok / degraded)
GET /api/v1/health/live	Liveness probe (process up)
GET /api/v1/checkout/:id/status	Public order status for the checkout page

curl -H "X-API-Key: your-api-key" https://pay.yourdomain.com/api/v1/payments

Response format

All responses are JSON. Errors follow this structure:

{
  "error": "Human-readable message",
  "code": "ERROR_CODE"
}

Monetary amounts are always strings (e.g. "100.500000"), never numbers. See DECISIONS.md in the core repo for the rationale.

Endpoint index

Method	Path	Auth	Description
POST	/payments	X-API-Key	Create a payment order
GET	/payments/:id	X-API-Key	Get order details
GET	/payments	X-API-Key	List orders (paginated)
GET	/checkout/:id/status	public	Public order status
GET	/health	public	Readiness probe
GET	/health/live	public	Liveness probe
POST	/admin/auth/login	public	Admin login (sets admin_token cookie)
POST	/admin/auth/logout	cookie	Admin logout
GET	/admin/stats	cookie	Dashboard stats
GET	/admin/merchants	cookie	List merchants
POST	/admin/merchants	cookie	Create merchant
GET	/admin/merchants/:id	cookie	Merchant detail with stats
PUT	/admin/merchants/:id	cookie	Update merchant
POST	/admin/merchants/:id/rotate-api-key	cookie	Rotate merchant API key
GET	/admin/orders	cookie	List all orders
GET	/admin/orders/:id	cookie	Order detail with events
POST	/admin/orders/:id/retry-webhook	cookie	Re-enqueue webhook delivery
POST	/admin/orders/:id/retry-sweep	cookie	Re-enqueue fund sweep
GET	/admin/wallet	cookie	Hot/cold wallet + address pool + sweep queue

See individual pages for full request/response schemas:

• Payments
• Webhooks
• Merchants
• Admin
• Authentication

Rate limiting

Admin login is rate-limited to 5 attempts per 15 minutes per IP. Other endpoints inherit the Fastify instance's default limits; tune at the reverse proxy if you need tighter per-route controls. PayWarden does not currently ship a per-merchant token bucket.