Overview
Earn is exposed as a single product called Auto-Earn. You don’t allocate balances per strategy — you flip a per-yield-source switch for the user and Payward picks strategies and routes eligible balances. Payward absorbs any on-chain bonding or unbonding periods, so allocated assets stay liquid and remain at the user’s disposal at all times. Today the only yield source isstaking; more may be added without breaking the response shape.
The integration shape is six endpoints:
| Goal | Endpoint | Method |
|---|---|---|
| Discover Auto-Earn eligibility by country | /v1/earn/auto/assets | GET |
| Discover Auto-Earn eligibility for an account | /v1/accounts/{account_id}/earn/auto/assets | GET |
| Set Auto-Earn preferences (per yield source) | /v1/accounts/{account_id}/earn/auto | PUT |
| Read current preferences (incl. pending state) | /v1/accounts/{account_id}/earn/auto | GET |
| List the user’s current per-asset allocations | /v1/accounts/{account_id}/earn/auto/allocations | GET |
| List historical rewards & next payout estimate | /v1/accounts/{account_id}/earn/auto/rewards | GET |
If you have used Kraken’s Spot REST Earn endpoints
(
Strategies, Allocations, Allocate, Deallocate), the PWS Earn API is a higher-level abstraction of the same
product. PWS picks strategies, routes eligible balances, and hides any on-chain bonding or unbonding so allocated
assets remain liquid for the user. You see the result through the six endpoints above and through the Portfolio API,
which surfaces each settled reward as an earn_reward transaction.Prerequisites
- Payward Services API credentials (see the Authentication guide).
- A verified user with at least one account and sufficient balance in the source asset.
- Examples target
https://api.services.payward.comand read credentials from thePWS_API_KEYandPWS_API_SECRETenvironment variables.
Workflow
Discover Auto-Earn assets (optional, pre-account)
Show what’s available in a country before you have an account. User-agnostic.
GET /v1/earn/auto/assets?country=USDiscover Auto-Earn assets for an account
Show APY and per-user allocation cap for the account’s eligible assets.
GET /v1/accounts/{account_id}/earn/auto/assetsSet Auto-Earn preferences
Enable or disable a yield source. Async.
PUT /v1/accounts/{account_id}/earn/autoPoll until preferences settle
Read current preferences and watch
pending_enabled / pending_disabled resolve.GET /v1/accounts/{account_id}/earn/autoAuto-Earn preference lifecycle
Each yield source has one of four states. Only the yield sources the user is eligible for appear inGET /v1/accounts/{account_id}/earn/auto; missing fields mean the user can’t enable that source today and the corresponding field on PUT is a no-op. There is no separate eligibility endpoint — presence in this response is the eligibility check.
| State | Meaning | What to show |
|---|---|---|
enabled | Yield source is active. Eligible balances are earning. | ”On”. |
disabled | Yield source is off. No new allocations. | ”Off”. |
pending_enabled | PUT accepted; provisioning in progress. | ”Enabling…” with a spinner. Don’t allow re-toggling. |
pending_disabled | PUT accepted; unallocation in progress. | ”Disabling…” with a spinner. Don’t allow re-toggling. |
PUT /v1/accounts/{account_id}/earn/auto returns immediately with an empty body. Poll GET /v1/accounts/{account_id}/earn/auto until the pending state resolves.
Asset, amount, and quote-currency conventions
Allocation and reward entries describe an asset at the top level using three fields:| Field | Description |
|---|---|
symbol | Ticker symbol (e.g. ETH, EUR). |
type | fiat, crypto, stablecoin, or xstock. |
name | Human-readable name (e.g. "Ethereum"). |
| Suffix | Denominated in |
|---|---|
| (none) | The entry’s own asset. allocated: "100.1234" means 100.1234 ETH on an ETH entry. |
_in_quote | The request’s quote currency. allocated_in_quote: "12345.12" is 12,345.12 EUR when quote_symbol=EUR. |
quote_symbol and quote_type to choose the quote asset, and echo both at the top level of the response so you can format *_in_quote values without re-stating the choice. Today only quote_type=fiat is supported; quote_symbol defaults to USD. Pass the same values across Earn and the Portfolio API so totals reconcile.
Authentication setup
Authenticated endpoints require an HMAC-SHA512 request signature in theAPI-Sign header and a monotonically increasing nonce in the API-Nonce header. The helper below derives the signature from the URL path, request body, and nonce. See the Authentication guide for the full algorithm.
Every PWS write endpoint (
POST / PUT / DELETE) accepts an Idempotency-Key header containing a UUIDv4. Generate
a fresh key per logical attempt — replays of the same key return the original response body and the
Idempotent-Replayed: true response header, which keeps retries safe under timeouts and connection drops.params argument.
Step 1: discover Auto-Earn assets by country
GET /v1/earn/auto/assets is user-agnostic. Use it to surface the value proposition before sign-up — for example on a landing page filtered by the visitor’s country. Pagination is via page_token / page_size.
Response example
| Field | How to use it |
|---|---|
apy | Estimated annual percentage yield as a decimal string (e.g. "3.41" for 3.41%). |
user_cap | Hard maximum a single user is allowed to auto-earn for this asset, in the entry’s asset. Show as a “max” hint. |
next_page_token | Opaque cursor; pass back as page_token to fetch the next page. |
Step 2: discover Auto-Earn assets for an account
GET /v1/accounts/{account_id}/earn/auto/assets returns the same shape as Step 1 but scoped to a specific account. Use it after sign-up to confirm exactly what that account can auto-earn.
Response example
Step 3: set Auto-Earn preferences
Send aPUT to /v1/accounts/{account_id}/earn/auto with the desired state of each yield source you want to change. All body fields are optional — yield sources you omit keep their current preference, so you can flip a single source without touching the others.
Supported yield sources today: staking. Allowed values: "enabled", "disabled".
Response example
The
200 OK confirms the preference change was accepted, not that every eligible balance is already earning.
Provisioning runs asynchronously; observe pending_enabled / pending_disabled on GET /v1/accounts/{account_id} /earn/auto to know when the change has settled. A second PUT issued before the pending state resolves returns 409 Conflict — see the preference lifecycle above.Step 4: poll until preferences settle
GET /v1/accounts/{account_id}/earn/auto returns the current preference for every yield source the user is eligible for. Eligibility is country-aware: if a user moves to a region where staking isn’t supported, the staking field disappears from this response and the corresponding field on PUT becomes a no-op.
Response example
Step 5a: list current allocations
GET /v1/accounts/{account_id}/earn/auto/allocations returns the user’s current per-asset allocation, plus the all-asset total in the requested quote currency. The endpoint is cursor-paginated; next_page_token is absent on the last page. All amounts inside entries are plain decimal strings; the response echoes quote_symbol / quote_type at the top level so you know how to format *_in_quote values.
Response example
| Field | How to use it |
|---|---|
quote_symbol / quote_type | Echo of the requested quote asset. Use to format *_in_quote values. |
total_allocated_in_quote | Cross-asset allocation total in the quote currency. Use it for a dashboard hero value. |
data[].allocated | Per-asset amount currently earning, in the entry’s asset. |
data[].allocated_in_quote | Same per-asset amount in the quote currency. |
next_page_token | Opaque cursor; pass back as page_token for the next page. |
Auto-Earn allocations are liquid. The
allocated amount is the user’s current earning balance and is always at the
user’s disposal — PWS absorbs any on-chain bonding or unbonding so there are no “in-transit” amounts for you to track
on the Earn side.Step 5b: list rewards
GET /v1/accounts/{account_id}/earn/auto/rewards returns historical rewards per asset, the all-time total in the quote currency, and the next payout estimate. Same quote_symbol / quote_type / page_token / page_size semantics as allocations, and the same envelope (quote_symbol / quote_type echoed at the top level).
estimated_next_reward, estimated_next_reward_in_quote, and the top-level next_reward_date are absent when no reward is pending. other_assets is absent on an entry when every reward for that asset was paid in the entry’s own asset.
Response example
| Field | How to use it |
|---|---|
quote_symbol / quote_type | Echo of the requested quote asset. Use to format *_in_quote values. |
total_rewarded_in_quote | All-time, cross-asset rewards in the quote currency. Headline figure for the rewards card. |
next_reward_date | Timestamp of the next payout across all assets. Absent when nothing is pending. |
data[].rewarded / _in_quote | Per-asset all-time rewards, in the entry’s asset and in the quote currency. |
data[].estimated_next_reward / _in_quote | Best-effort estimate of the upcoming reward for that asset. Absent when no payout is pending. |
data[].other_assets | Rewards paid in a different asset than the entry’s own (e.g. restaking-style side rewards). Same shape minus a nested other_assets. Absent when all rewards are in the entry’s asset. |
next_page_token | Opaque cursor; pass back as page_token for the next page. |
Reward amounts can be very small for low-APY assets — a value like
"0.00000001" is common. Decide up front how to
render near-zero values (for example, “<0.00000001 ETH” or “~0”).Reconciling rewards in Portfolio
When a payout settles, it appears in the Portfolio activity feed as anearn_reward transaction:
Error handling
| HTTP status | Cause | Remediation |
|---|---|---|
400 Bad Request | Invalid country (not ISO 3166-1 alpha-2), unsupported quote_type, bad enum value in the PUT body, or bad pagination tokens | Validate query parameters and body before sending. |
401 Unauthorized | Missing or invalid signature, key, or nonce | Verify API-Key, API-Sign, and API-Nonce. The nonce must increase. |
403 Forbidden | Account is not authorized to use Earn | Confirm the account’s product entitlements. |
404 Not Found | Unknown account_id | Verify the account_id belongs to your partner. |
409 Conflict | An Auto-Earn preference change is already in progress for this user — only one may be in flight at a time | Poll GET /v1/accounts/{account_id}/earn/auto until no yield source is in pending_enabled / pending_disabled, then retry. |
429 Too Many Requests | Rate limit hit | Honor Retry-After and back off exponentially. |
Best practices
- Treat the
PUTas eventually consistent. A200 OKconfirms the change was accepted, not that balances are already earning. - Only one preference change in flight per user. Wait for the pending state to resolve before submitting another change; otherwise the second
PUTreturns409 Conflict. - Only send the yield sources you actually want to change. Omit the others to keep their preferences untouched.
- Pass
quote_symbolconsistently across allocations, rewards, and Portfolio so converted totals line up across views. - Don’t assume APY is fixed. Refetch the asset list whenever you display APY; it drifts with network conditions and country availability.
- Capture
Request-Idfrom response headers. It speeds up support investigations.
API reference
| Endpoint | Method | Description |
|---|---|---|
/v1/earn/auto/assets | GET | List Auto-Earn assets eligible in a country (user-agnostic). Required country query parameter. |
/v1/accounts/{account_id}/earn/auto/assets | GET | List Auto-Earn assets available to the given account, with APY and per-user cap. |
/v1/accounts/{account_id}/earn/auto | PUT | Set Auto-Earn preferences per yield source. Async; empty data: {} on success. |
/v1/accounts/{account_id}/earn/auto | GET | Get current Auto-Earn preferences. Includes pending_enabled / pending_disabled while a PUT is being applied. |
/v1/accounts/{account_id}/earn/auto/allocations | GET | List the user’s current per-asset allocations and the cross-asset total in the requested quote currency. |
/v1/accounts/{account_id}/earn/auto/rewards | GET | List historical rewards per asset, the all-time total in the quote currency, and the next payout estimate. |