REST API reference
The official testnet origin is https://api-testnet.velarumpay.com; local contract tests may use http://127.0.0.1:8787. All API paths below are prefixed with /v1.
Download the canonical OpenAPI 3.1 document. Legacy
/v1/payment-intents and OpenClaw-specific routes are migration-only and are not part of this public contract.Authentication
Credentials are separated by caller and purpose:
| Caller | Credential | How to send |
|---|---|---|
| Merchant operator | HttpOnly merchant session + CSRF proof | Same-origin cookie; X-CSRF-Token on mutations. |
| Registered Agent | Short Agent token | Authorization: Bearer <agent-token>; currently used for authenticated Connect claim. |
| Connected Agent | Connection token | Authorization: Bearer <connection-token> for scoped context and Payment Request calls. |
| Connect claimant | Short claim token | Bearer token only on invitation detail and exchange. |
| Wallet app | App device token | device_id + token in the body (or query for GET) |
Never place merchant_id, tenant_id, or self-declared Agent identity in a request to obtain authorization. The API derives tenant and actor identity from the verified credential.
Idempotency: send
X-Idempotency-Key (or idempotency_key in the body) when creating payment requests so retries never double-charge.Pairing & connections
| Method | Path | Who | Purpose |
|---|---|---|---|
| POST | /v1/pairing/sessions | Agent | Start a pairing session; returns a short code + velarumpay://pair?... URI. |
| GET | /v1/pairing/sessions/:id | Agent | Check pairing status (pass ?code=). |
| POST | /v1/pairing/sessions/:id/approve | Wallet | Approve scopes; returns the connection token. |
| POST | /v1/pairing/sessions/:id/reject | Wallet | Reject the pairing request. |
| GET | /v1/connections | Wallet | List connections for a device. |
| PATCH | /v1/connections/:id | Wallet | Pause or re-activate a connection. |
| DELETE | /v1/connections/:id | Wallet | Revoke a connection. |
| POST | /v1/connections/:id/rotate-token | Wallet | Rotate the connection token. |
Merchant control plane
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/merchant-accounts/registrations | Start enumeration-safe email registration. |
| POST | /v1/merchants | Consume the email-verification session grant and create an organization. |
| POST | /v1/merchant-sessions | Consume the next one-time grant and issue an HttpOnly session plus CSRF proof. |
| POST | /v1/merchant-domains | Register an exact DNS/HTTPS verification challenge. |
| POST | /v1/recipients | Create a versioned Recipient; verify and activate before payments. |
| POST | /v1/agents | Register an Agent and its allowed scopes. |
| POST | /v1/agents/{agentId}/credentials | Register an Ed25519 public credential; activate it with the returned proof challenge. |
| POST | /v1/webhook-endpoints | Create a signed Webhook endpoint; generated secret is shown once. |
| GET | /v1/webhook-deliveries | Inspect tenant-scoped delivery attempts without response bodies or secrets. |
Agent Auth and Connect
| Method | Path | Credential |
|---|---|---|
| POST | /v1/agent-auth/token | Locally signed Agent Assertion. |
| POST | /v1/connect-invitations/claim | Short Agent token. |
| GET | /v1/connect-invitations/{id} | Connect claim token or authenticated wallet. |
| POST | /v1/connect-invitations/{id}/exchange | Connect claim token after wallet approval. |
Payments & context
| Method | Path | Who | Purpose |
|---|---|---|---|
| POST | /v1/transaction-contexts | Agent | Create the human-readable review context. Scope: transaction_contexts.create. |
| GET | /v1/transaction-contexts/:transaction_id | Agent | Read the latest context. Scope: transaction_contexts.read. |
| POST | /v1/payment-requests | Agent | Create a payment request. Scope: payment.requests.create. |
| GET | /v1/payment-requests/:id | Agent | Read one payment request. Scope: payment.requests.read. |
| GET | /v1/payment-requests/events | Agent | Poll status events (pass ?since=). |
| POST | /v1/payment-requests/:id/status | Wallet | Report a status transition. |
Operations
| Method | Path | Purpose |
|---|---|---|
| GET | /health | Liveness check (used by Docker / load balancer). |
| GET | /metrics | Prometheus metrics (token-protected if configured). |
Example: create a payment request
curl -X POST https://api-testnet.velarumpay.com/v1/payment-requests \
-H "Authorization: Bearer $VELARUMPAY_CONNECTION_TOKEN" \
-H "X-Idempotency-Key: demo-payment-1" \
-H "Content-Type: application/json" \
-d '{
"recipient_id": "recipient_test_0001",
"recipient_version_id": "recipient_version_test_0001",
"payment": {
"amount": "1.00"
},
"policy": { "requires_user_approval": true }
}'Recipient network, asset, address, memo, contract, and issuer are server-derived from the active verified Recipient version. The response remains pending until the wallet user approves and signs locally.
Errors
Failures return ok: false with a structured error object (code, a human message, request_id, and field when relevant). Risk and validation problems list every issue so you can fix them in one pass. A retry must retain the same idempotency key and request intent.