Actions

Request enter, exit, and manage actions, sign the returned transactions, and track them to completion.

An action is a request to change a position on one yield. Every action has an intent: enter (open a position), exit (close or reduce one), or manage (a follow-up like claiming rewards or completing a withdrawal). The Yield API turns that request into an ordered set of unsigned transactions. It never holds keys or signs on your behalf.

Requesting an action

Call one of three endpoints with the yieldId, the user’s address, and arguments:

Intent	Endpoint
Enter	POST /v1/actions/enter
Exit	POST /v1/actions/exit
Manage	POST /v1/actions/manage

The shape of arguments is not fixed. It is defined per yield by that yield’s mechanics.arguments.enter / .exit / .manage schema (fields like amount, validatorAddress, or a Cosmos public key). Read the schema before calling the action instead of assuming a common set of fields; see Yield metadata.

POST /v1/actions/enter/simulate and POST /v1/actions/exit/simulate accept the same body and return a gas estimate for the action (an aggregate gas.amount plus a per-transaction breakdown) without creating or persisting anything. A 200 from simulate does not guarantee the real action will succeed on-chain.

The response: an action and its transactions

Every enter, exit, or manage call returns an ActionDto: an id, the intent and type (the specific operation, such as STAKE or CLAIM_REWARDS), the yieldId and address it applies to, amount / amountRaw / amountUsd, a status, and a transactions array.

Each entry in transactions is a TransactionDto with its own id, stepIndex (its position in the sequence, zero-based), type, status, and unsignedTransaction, the payload to sign. unsignedTransaction is a JSON string of serialized transaction data on EVM-style chains, and an object on non-EVM chains. Execute transactions in stepIndex order: a later step can depend on an earlier one being confirmed first (for example, an ERC-20 approval before a deposit).

The action also carries an executionPattern that describes how its transactions are meant to be run:

executionPattern	Meaning
synchronous	Submit transactions one by one, waiting for each to confirm before the next
batch	A single transaction that bundles multiple operations

asynchronous (submit all transactions at once) is also a declared value, but current actions return synchronous or batch. See Execution pattern.

Signing and submitting

We construct. You sign. The Yield API builds each transaction; your app signs it with its own wallet or custody flow (a browser wallet, a hardware device, a smart account, or an institutional custodian), then gets it on-chain in one of two ways:

• If yield.xyz should broadcast it for you: sign, then call POST /v1/transactions/{id}/submit with the signedTransaction.
• If your infrastructure broadcasts it directly: broadcast the signed transaction yourself, then report the resulting hash with PUT /v1/transactions/{id}/submit-hash.

Either path moves the transaction into tracking. Poll GET /v1/transactions/{id} for its status, or GET /v1/actions/{id} for the whole action, including every transaction in transactions.

Status lifecycle

An action’s status reflects the state of its transactions as a whole:

status	Meaning
CREATED	The action was created; no transaction has broadcasted yet
WAITING_FOR_NEXT	Waiting for your app to sign and submit the next transaction in the sequence
PROCESSING	The current transaction has broadcasted and is awaiting confirmation
SUCCESS	Every transaction confirmed (or was skipped as unnecessary)
FAILED	A transaction in the sequence failed
CANCELED	The action was canceled and will not proceed
STALE	No progress for 30 minutes: either nothing was broadcast, or a broadcast transaction never confirmed. GET /v1/actions hides stale actions that never broadcast anything unless you filter by status or statuses

A single transaction’s status moves through a finer-grained lifecycle from CREATED through WAITING_FOR_SIGNATURE, SIGNED, BROADCASTED and PENDING to CONFIRMED, FAILED or SKIPPED (BLOCKED means held back: do not sign or submit it). Exact values are listed under Transaction statuses.

CONFIRMED, FAILED, and SKIPPED are terminal: once set, that transaction’s status does not change again. Gate your flow on these terminal values rather than on intermediate ones.

Manage actions

A manage action targets one of the pending, follow-up operations available on an existing position, such as CLAIM_REWARDS or WITHDRAW. POST /v1/actions/manage takes the same yieldId, address, and arguments as enter and exit, plus two required fields:

• action: the pending-action type to execute (for example CLAIM_REWARDS)
• passthrough: the opaque, server-generated string from that same pending action

Both values come from a balance’s pendingActions, unchanged. See Balances and positions for where pendingActions come from and how to read them.

Next steps

Quickstart

Run the full enter, sign, submit, track loop end to end.

Enter/exit flows

Implementation patterns for signing and submitting across wallet types.

Balances and positions

Where pending actions and position state come from.

API reference

Full request and response schemas for every action and transaction endpoint.