Skip to main content

Overview

This page covers Auto Earn. To allocate into a specific strategy yourself, see Bonded Earn. Auto Earn is a single product. You don’t allocate balances per asset: you flip a per-yield-source switch for the user and Payward picks assets 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. The supported yield sources are staking, base_rewards, and opt_in_rewards; more may be added without breaking the response shape. The integration shape is eight endpoints, listed with their API key permissions in the API reference at the end of this page.
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 assets, 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 eight endpoints in the API reference and through the Portfolio API, which surfaces each settled reward as an earn_reward transaction.

Prerequisites

  • Payward Services API credentials (see the Authentication guide). The API key needs the earn-auto-read permission, plus earn-auto-write to change preferences (see API key permissions).
  • A verified user with at least one account.
  • Examples target https://api.services.payward.com and read credentials from the PWS_API_KEY and PWS_API_SECRET environment variables.

Workflow

1

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=US
2

Discover 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/assets
3

Set Auto Earn preferences

Enable or disable a yield source. Async.PATCH /v1/accounts/{account_id}/earn/auto
4

Poll until preferences settle

Read current preferences and watch pending_enabled / pending_disabled resolve.GET /v1/accounts/{account_id}/earn/auto
5

Read allocations and rewards

Show how much is currently earning, and historical / upcoming rewards.
  • GET /v1/accounts/{account_id}/earn/auto/allocations
  • GET /v1/accounts/{account_id}/earn/auto/rewards/summary
  • GET /v1/accounts/{account_id}/earn/auto/rewards
  • GET /v1/accounts/{account_id}/earn/auto/rewards/upcoming

Auto Earn preference lifecycle

Each yield source has one of four states. A yield source appears in GET /v1/accounts/{account_id}/earn/auto if the account is eligible for it, is enrolled in it, or has an enable in flight. A missing yield source means none of these apply. Enabling a yield source the account isn’t eligible for fails with not_eligible. Disabling always works. There is no separate eligibility endpoint. PATCH /v1/accounts/{account_id}/earn/auto returns immediately with an empty data object. Poll GET /v1/accounts/{account_id}/earn/auto until the pending state resolves.
Only one Auto Earn preference change can be in progress per account at a time. Submitting a PATCH while any yield source is in pending_enabled or pending_disabled returns 409 Conflict with the code allocation_in_progress. Wait for the pending state to resolve in GET /v1/accounts/{account_id}/earn/auto before issuing the next change.

Asset, amount, and quote-currency conventions

Allocation and reward entries describe an asset at the top level using three fields: All monetary fields inside an entry are plain decimal strings: The allocations and rewards endpoints accept 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 the API-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.
Unless an endpoint documents an exception, 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.
The Earn endpoints either accept query parameters or a JSON body. Include the query string in the path you sign: the helper supports this through its params argument.

API key permissions

Create the API key in the Payward Console with the permissions your integration needs: Grant both to an integration that sets preferences and then polls them.

Step 1: discover Auto Earn assets by country

GET /v1/earn/auto/assets is user-agnostic. country is required and must be a two-letter ISO 3166-1 alpha-2 code. 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. To list only assets backed by specific yield sources, repeat the optional yield_source query parameter (for example, yield_source=staking&yield_source=base_rewards).

Response example

APY is an estimate, not a guarantee. Display the value with a % suffix and label it “estimated”, since realized yield depends on network conditions and fees.

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 and accepting the same page_token, page_size, and yield_source parameters. Use it after sign-up to confirm exactly which assets are eligible for Auto Earn in that account.

Response example

Step 3: set Auto Earn preferences

Send a PATCH 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: staking, base_rewards, opt_in_rewards. Allowed values: "enabled", "disabled". Enabling a yield source the account isn’t eligible for fails with not_eligible. Disabling always works.

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 PATCH issued before the pending state resolves returns 409 Conflict with the code allocation_in_progress: 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 account is eligible for, is enrolled in, or has an enable in flight. Eligibility is country-aware: if a user who isn’t enrolled moves to a region where staking isn’t supported, the staking field disappears from this response. Enabling it then fails with not_eligible.

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. Assets with a zero balance aren’t listed. 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

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: read rewards

Rewards are split across three endpoints, so you fetch only what a screen needs: All three accept quote_symbol and quote_type with the same semantics as allocations, and echo both at the top level of the response. The per-asset and upcoming endpoints also accept page_token / page_size. All reward amounts are net of any reward fee.

Total rewards

GET /v1/accounts/{account_id}/earn/auto/rewards/summary returns the lifetime total across every Auto Earn asset, converted to the quote currency. Use it for the headline figure of a rewards card.
Each payout is valued when it is paid, so the total doesn’t move with asset prices. For a non-USD quote, the USD total is converted at today’s USD rate, so it still moves with that rate.

Rewards per asset

GET /v1/accounts/{account_id}/earn/auto/rewards returns the lifetime rewards of each asset, sorted by symbol, A-Z. Assets that have never paid a reward are omitted.

Response example

Upcoming rewards

GET /v1/accounts/{account_id}/earn/auto/rewards/upcoming returns the reward each asset expects to pay out at its next payout, together with the date of that payout. The amount is what has accrued so far plus an estimate up to the payout date. It leaves out rewards that belong to a later payout period. The amounts are estimates and the date is a target, so payouts can be delayed. next_reward_date is one date for the whole account: the earliest payout among the assets. Each amount is for its asset’s own next payout, which can be later than that date. The date covers every asset, not just the current page, so it reads the same on every page. Assets with nothing pending are omitted, and next_reward_date is then absent. other_assets is usually an empty array. When a reward is paid in other assets (e.g., EIGEN paid on the ETH entry), it lists that part separately.
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 an earn_reward transaction:
Use the Portfolio guide for the activity feed and pagination, and the Reports endpoints for downloadable settlement statements.

Error handling

All error responses share a standard envelope:

Best practices

  1. Treat the PATCH as eventually consistent. A 200 OK confirms the change was accepted, not that balances are already earning.
  2. Only one preference change in flight per account. Wait for the pending state to resolve before submitting another change; otherwise the second PATCH returns 409 Conflict.
  3. Only send the yield sources you actually want to change. Omit the others to keep their preferences untouched.
  4. Pass quote_symbol consistently across allocations, rewards, and Portfolio so converted totals line up across views.
  5. Don’t assume APY is fixed. Refetch the asset list whenever you display APY; it drifts with network conditions and country availability.
  6. Capture X-Trace-Id from response headers. It speeds up support investigations.

API reference