Velarum REST API

The Velarum REST API is the non-custodial control plane for Agent Payments: you create payment intents, read their authoritative status, and register automation policies. Velarum assembles unsigned transactions and indexes public on-chain events — it never holds your keys and never signs or broadcasts on your behalf (HC-NC-1).

🛠 Phase-0 is testnet only (per ADR-NC-027). Any mainnet call is rejected with 409 phase_0_mainnet_disabled.

Base URL & environments

Production base URL: https://api.velarumai.com. All routes are versioned under /v1/...; a breaking change bumps the version in the path.

Authentication

Authenticate every business call with your project API key in the x-velarum-api-key header. Admin-session routes additionally accept Authorization: Bearer <session>. A custom header can never override these (the SDK enforces the same rule client-side).

curl https://api.velarumai.com/v1/agent-payments/pay_123 \
  -H "x-velarum-api-key: $VELARUM_API_KEY"

Request conventions

Every write operation accepts an Idempotency-Key header (and may also carry a body idempotency_key; when both are present they must be byte-equal, else IDEMPOTENCY_KEY_MISMATCH). Monetary amounts are always decimal strings ("5.00"), never floats. Timestamps are RFC3339 UTC.

Response envelope

Successful responses wrap the payload in a stable envelope; the SDK unwraps data for you.

{ "success": true, "data": { "id": "pay_123", "status": "intent_created" }, "request_id": "req_abc", "timestamp": "2026-06-01T10:00:00Z" }

Errors

Failures return a stable, semantic error.code. The full catalogue — HTTP status, meaning, recovery hint, and idempotency-safety — lives in Error codes.

{ "success": false, "error": { "code": "HC_NC_5_HITL_REQUIRED", "message": "Human confirmation required", "details": { "triggered_thresholds": ["single_tx_limit"] } }, "request_id": "req_abc", "timestamp": "2026-06-01T10:00:00Z" }

Automation endpoints & Human-in-the-Loop

Endpoints under /v1/automation-policies let an agent act autonomously, but only after the user opts in and fills all four thresholds (per-transaction cap, cumulative cap, validity window, allowlist). An agent intent that exceeds any threshold returns HC_NC_5_HITL_REQUIRED instead of executing — the call must be re-submitted as a human-initiated payment (HC-NC-5).

Browse the full API

The interactive reference below is rendered directly from the authoritative openapi.yaml. Expand any endpoint to see its schema, parameters, and a try-it-out panel.