Guides
Log inRegister interest
Start typing to search…

Actions

The Yield.xyz Actions turns complex yield workflows into simple, intent-based operations. Whether you're staking, exiting, claiming rewards, or redelegating, the API returns fully constructed transactions — ready for you to sign and submit.

Use Cases

Use this when you want to initiate or manage a yield position through a single, declarative API.
Whether you're building a wallet, agent, or yield aggregator — Actions let you abstract protocol logic without writing custom transaction flows.

Overview

  • Actions are intent-based: enter, exit, or manage
  • Returns fully constructed transactions via ActionDto
  • All inputs are schema-driven
  • Signing and execution remain self-custodial

Core Concepts

Supported Intents

  • enter: create a position (e.g. stake, lend, deposit)
  • exit: unwind a position (e.g. unstake, withdraw)
  • manage: follow-up actions (e.g. claim, restake, redelegate)

DTOs Involved

  • ActionDto: includes transaction steps, arguments, metadata
  • TransactionDto[]: unsigned transactions, gas estimates, decoded content

Schema-Driven UX

Each action exposes a formal schema under mechanics.arguments, which defines:

  • Field names and types (e.g. string, number, enum)
  • Which fields are required vs optional
  • Dynamic references for validator lists
  • Nested structures like additionalAddresses

This was intentionally designed so that you can generate dynamic forms in your frontend directly from the schema — no hardcoded fields required. Think of it as form-level introspection: all fields, types, and UI labels are part of the contract.

Typical Flow

1. Fetch the Action Schema

Use GET /v1/yields/{yieldId} to retrieve required arguments for each action under mechanics.arguments.enter, exit.

This schema defines:

  • Required fields like amount, validatorAddress, etc.
  • Optional fields like additionalAddresses.cosmosPubKey (used by Cosmos, Tezos, etc.)
  • Supported formats (address, number, options, dynamic refs)

You must read the schema before calling an action to pass the correct input.

2. Declare the Intent

Call one of:

  • POST /v1/actions/enter
  • POST /v1/actions/exit
  • POST /v1/actions/manage

Each call requires:

  • yieldId: ID of the yield opportunity
  • address: user’s wallet address
  • arguments: schema-compliant input,
  • passthrough: (optional) if manage
  • action: (optional) if manage

Example: Redelegating to a new validator

  • Intent: manage
  • Action: REDELEGATE
  • Includes passthrough from balances + new validatorAddress

3. Handle the Response

Each action returns:

  • A list of transactions (TransactionDto[])
  • Metadata and status tracking
  • Raw and annotated arguments

Transaction Details

Each transaction includes:

  • title, type, network, stepIndex
  • unsignedTransaction: raw data to sign
  • annotatedTransaction: decoded method + args (e.g., stake, validatorAddress)
  • structuredTransaction: full structured version (useful for simulations or MPCs)
  • Optional: gasEstimate, explorerUrl, description, isMessage

Transactions are stateless and can be regenerated anytime using the same input.

4. Sign and Broadcast

Use any signing infrastructure:

  • Yield.xyz SDK (@stakekit/signers)
  • Native SDKs (ethers, cosmjs, solana/web3.js)
  • Smart wallets (Safe)
  • Hardware wallets or institutional custody

The API never signs or submits transactions — this is entirely in your control.

Managing Positions

Use the manage intent to perform post-entry actions like:

  • CLAIM_REWARDS
  • RESTAKE_REWARDS
  • REDELEGATE (e.g. switch validators)

You must retrieve the pending action payload via:

GET /v1/yields/{yieldId}/balances

This gives you:

  • The passthrough blob
  • Optional schema (arguments) for things like new validator selection

Use this data to construct your POST /v1/actions/manage request.

Notes on Additional Context

Some chains require extra fields like cosmosPubKey. These are exposed in the mechanics.arguments schema under additionalAddresses.

If you use the SDK, these fields are handled automatically.

Summary

  • All actions are schema-first: no hardcoded fields
  • The API builds full transaction flows — you sign and submit
  • enter, exit, and manage cover all yield lifecycle needs
  • Validator selection, cooldown logic, and approvals are fully abstracted
  • Self-custody and signer flexibility are preserved

➡️ Explore API Reference for full schema and action details.

Updated 8 days ago