Developer reference for a REST staking API
Illustrative resource patterns, response envelopes, error semantics, idempotency, versioning, webhooks, and OpenAPI documentation for staking workflows. No live endpoint is offered.
Prefer durable nouns over one-call verbs
Create intents and actions, then read their state. This structure supports asynchronous signing, protocol waiting periods, retries, webhooks, and reconciliation.
POST /v1/intents
POST /v1/actions
GET /v1/actions/{action_id}
GET /v1/positions/{position_id}
GET /v1/networks/{network_id}/capabilities
GET /v1/validators/{validator_id}
GET /v1/reward-statements/{statement_id}
GET /v1/events?position_id={position_id}Response envelope
Use predictable identifiers, timestamps, state, evidence, and error objects across resources. Amounts should include raw integer values and decimal metadata; never rely on floating-point display strings for signed or reconciled values.
{
"data": {
"id": "act_01J...",
"type": "staking_action",
"status": "awaiting_signature",
"created_at": "2026-10-23T20:00:00Z",
"expires_at": "2026-10-23T20:10:00Z"
},
"meta": {
"request_id": "req_01J...",
"api_version": "2026-10-01"
}
}Machine-readable errors
Return a stable code, plain-language message, retry safety, related resource IDs, and structured details. HTTP status communicates transport semantics; the error code communicates the domain condition.
| Status | Use | Domain example |
|---|---|---|
| 200 | Current resource returned | Position or capability read |
| 201 | Resource created synchronously | Intent record created |
| 202 | Workflow accepted, still processing | Action waiting for signing or chain state |
| 400 | Malformed request | Invalid amount encoding |
| 401 / 403 | Identity or permission failure | Wrong tenant or missing action scope |
| 409 | State conflict | Intent changed, duplicate key mismatch, or ineligible transition |
| 422 | Well-formed but unsupported intent | Capability or policy does not allow action |
| 429 | Rate or resource limit | Bounded with retry guidance |
| 503 | Required safety dependency unavailable | Signer or evidence source unavailable; fail closed |
Version schemas
Use explicit API and adapter versions. Additive fields are easier than changing existing meaning; unknown enum values must remain parseable.
Verify webhooks
Sign delivery, include event ID and timestamp, retry with backoff, and let consumers fetch the current resource after receiving an event.
Publish freshness
Every chain-derived response needs observation time, source, native reference, and a clear stale or partial state.
Start with the field guide
Read the long-form architecture article before adapting the illustrative OpenAPI document.