Liquid staking API reference covering token accounting, route quotes, contract verification, withdrawals, and risk disclosures.

Liquid staking API design

Model liquid staking tokens, protocol deposits, swaps, wraps, quotes, contract registries, accounting rates, withdrawal queues, and claims without hiding route-specific risk.

Declare the token accounting model

A liquid staking position may be represented by a rebasing token, a fixed-share token whose exchange rate changes, or another protocol-specific claim. The API should return both token units and underlying-equivalent units, including decimals, rate, observation block, and calculation method.

Use a versioned token metadata resource. Ticker symbols are presentation, not identity. Identity requires network, canonical contract address, token standard, decimals, accounting behavior, and the verified source of that metadata.

Minimum metadata

Chain identifier and contract address
Token amount and raw integer amount
Underlying asset and conversion rate
Rebasing, share-based, or other behavior
Rate source, block reference, and observed time
Pause, deprecation, or unsupported status

Route contract

Show how the position will be created

Direct protocol deposits, token wraps, and secondary-market swaps can lead to the same asset but use different contracts, approvals, costs, slippage, and settlement guarantees.

Quote

Input, expected output, minimum received, fee components, expiration, and assumptions.

Quote fields

Ordered steps

Approvals, swaps, deposits, wraps, and destination transfers with contract roles.

Step fields

Verification

Network, allowlisted addresses, registry version, simulation, and intent digest.

Verification fields

Illustrative route object

Each step names the economic operation. The user or policy system can review the route before a wallet signs it.

{
  "route_type": "protocol_deposit_and_wrap",
  "network": "ethereum-mainnet",
  "input": {"asset":"ETH","amount_raw":"..."},
  "output": {"asset":"wrapped-LST","minimum_raw":"..."},
  "steps": [
    {"type":"deposit","contract_role":"staking_pool"},
    {"type":"wrap","contract_role":"token_wrapper"}
  ],
  "registry_version": "contracts-2026-10",
  "expires_at": "2026-10-23T20:20:00Z"
}

Withdrawal lifecycle

A request, queue, claim, and settlement are different states

Give each withdrawal its own resource and event history. Preserve the token burn or lock evidence, request amount basis, queue observations, claim eligibility, destination, claim transaction, and final receipt.

RequestedIntent accepted and payload prepared

QueuedProtocol acknowledged the request

ClaimableProtocol permits a claim action

SettledUnderlying funds observed at destination

Risk context

Return route-specific smart-contract, validator, liquidity, oracle, governance, concentration, and approval warnings with the same preview that contains the numbers.

Accounting context

Preserve raw token balances, rates, claims, transfers, fees, and valuation inputs so reports can distinguish earned value from market movement.

Read the liquid staking design guide

The journal article covers token behavior, quote paths, contract verification, accounting, withdrawals, and limits in depth.

Read full guide