SKILL

Exit (withdraw from) a yield position on yield.xyz by creating an exit action, including unstake flows with cooldowns. Use when the user wants to unstake, withdraw, redeem, or leave a yield position.

Exit position

Create an exit action with POST /v1/actions/exit. The API returns ordered unsigned transactions, submitted the same way as an enter action.

When to use

• Unstake tokens (for example, “Unstake my ETH from Lido”)
• Withdraw from a lending market or vault
• Remove liquidity
• Leave a position entirely or partially

Authentication and host

Send the project API key in the x-api-key header.

https://api.yield.xyz/v1

Step 1: Check the yield allows exits

curl "https://api.yield.xyz/v1/yields/{yieldId}" -H "x-api-key: $YIELD_API_KEY"

Confirm status.exit is true. Read mechanics.cooldownPeriod ({ seconds }) for any waiting period, and mechanics.arguments.exit.fields[] for the arguments.

Step 2: Check the position (recommended)

curl -X POST "https://api.yield.xyz/v1/yields/{yieldId}/balances" \
  -H "x-api-key: $YIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "address": "0xYOUR_WALLET_ADDRESS" }'

Balance type values are active, entering, exiting, withdrawable, claimable, and locked. Exit from active balances.

Step 3: Create the exit action

POST /v1/actions/exit. yieldId and address are required. Pass the fields the exit schema lists.

{
  "yieldId": "ethereum-eth-lido-staking",
  "address": "0xYOUR_WALLET_ADDRESS",
  "arguments": { "amount": "0.5" }
}

amount is a human-readable decimal string. amountRaw is the smallest-unit alternative; send one, not both. Other arguments, when the schema lists them:

Argument	Notes
validatorAddress	Validator to unstake from.
useMaxAmount	Withdraw the full ERC-4626 vault position.
shareAmount, shareAmountRaw	Withdraw by share amount.
percentage, tokenId	Partial exit from a liquidity position (0 to 100) and its NFT ID.
outputToken, outputTokenNetwork	Receive a different token, or on another network.
useInstantExecution	Faster exit that may have fees, where supported.

Optionally call POST /v1/actions/exit/simulate first to estimate gas.

The response is 201 with an ActionDto: id, intent: "exit", type, status, executionPattern, and transactions[].

Step 4: Sign and submit

Same as enter-position: process transactions[] in stepIndex order, sign each unsignedTransaction, then use one path per transaction.

• POST /v1/transactions/{transactionId}/submit with { "signedTransaction": "..." } for yield.xyz to broadcast.
• PUT /v1/transactions/{transactionId}/submit-hash with { "hash": "0x..." } if you broadcast.

executionPattern is synchronous or batch on current actions. asynchronous is also a declared value, but current actions return synchronous or batch.

Step 5: Cooldowns and claiming

Many staking yields hold funds through a cooldown after the exit. The exiting amount shows as an exiting balance, then a withdrawable balance when it is ready. Claim it with manage-position using the pending action on that balance (for example CLAIM_UNSTAKED or WITHDRAW). Cooldown length is yield-specific: read mechanics.cooldownPeriod.

Track the action with GET /v1/actions/{actionId} until SUCCESS, FAILED, or CANCELED.

Errors

Status	Meaning	Action
400	Invalid arguments, amount above balance, or yield not enabled for the project	Check the balance and the exit schema.
401	Missing or invalid API key	Check the x-api-key header.
403	Geo-blocked region	Stop.
429	Rate limited	Wait for retry-after seconds.

Edge cases

• Partial exits: Most yields accept an exact amount. Check the exit schema.
• Existing cooldowns: Some protocols allow further unstake requests during a cooldown; others do not. Read the exiting balances first.
• Vault shares: Vault exits convert shares at the current price per share, which can differ from the deposit amount.
• Closed exits: If status.exit is false, do not create the action.