Intent resource
An immutable record of network, asset, amount, destination, authorities, policy context, and user-approved assumptions.
Review intent modelStaking API architecture guide covering intent, action, position, capability, idempotency, evidence, and protocol lifecycle design.
Staking API architecture
A production staking API should preserve user intent, signing boundaries, protocol-native state, and evidence across asynchronous workflows. This reference defines a durable resource model for REST staking APIs.
Action resource
A versioned preparation, signing, submission, and evidence workflow with idempotency and expiration.
Review action modelPosition resource
The durable on-chain or protocol position, including native state, normalized state, history, and available actions.
Review position modelBegin with economic intent
A client should be able to state what it wants without submitting a transaction. The intent captures the requested network, asset, amount, validator or route, withdrawal destination, authority expectations, and policy facts. It receives an immutable digest so approvals and prepared payloads can be tied to the exact decision.
Intent is not chain truth. It is a decision record. The API still needs to validate current capabilities, balances, limits, fees, contract addresses, and protocol conditions before returning a preparation. Any material change after approval produces a new intent version.
Recommended intent fields
- Tenant, actor, environment, network, asset, and action type
- Amounts with raw integer value, decimals, and display value
- Validator, vote account, contract route, or strategy selection
- Destination and authority roles
- Policy version, approval state, expiration, and idempotency key
Actions are durable workflows
Preparation, wallet or custody authorization, broadcast, confirmation, activation, and reconciliation should not be hidden inside a long HTTP request. Persist each step and return the current state.
- Client idempotency key
- Immutable intent digest
- Prepared payload expiration
- Signer requirements
- Submission evidence
- Outcome-unknown state
POST /v1/actions
Idempotency-Key: client-7c29
{
"intent_id": "int_01J...",
"operation": "delegate",
"mode": "prepare_only"
}
202 Accepted
Location: /v1/actions/act_01J...Position contract
Return native state and a normalized view
Normalization should help clients without erasing the reason a position behaves differently on Ethereum, Solana, or a liquid staking protocol.
| Field | Purpose | Design rule |
|---|---|---|
native_state | Protocol-specific status | Never discard an unknown future value. |
status | Stable product grouping | Version and document the mapping. |
observed_at | Freshness | Use protocol and wall-clock context. |
evidence[] | Verification | Name source, identifier, and confidence. |
balances[] | Amounts | Return raw values, decimals, role, and unit. |
next_actions[] | Current eligibility | Drive from capabilities and fresh native state. |
Read consistency
State which upstream produced the observation, how recent it is, and whether a stronger finalized reference exists. Critical clients should be able to distinguish stale, partial, contradictory, and verified data.
Mutation safety
On uncertain outcomes, reconcile before retrying. “Outcome unknown” is a legitimate state when the API cannot yet prove whether the external effect occurred.
Capability discovery
Return supported actions, signer roles, limits, queue behavior, and environment-specific restrictions before the client renders controls.
Versioning
Version schemas, adapters, capabilities, and policy behavior. Keep active workflows bound to the interpretation used when they began.
See the complete architecture guide
The long-form guide connects resources, lifecycle states, capabilities, and evaluation questions.