SKILL

Perform management actions on an existing yield position via the Yield.xyz API, including claiming rewards, restaking, claiming unstaked tokens, rebonding, voting, and other lifecycle operations. Use when the user wants to manage, claim, restake, or perform maintenance on an active yield position.

Manage Position

Generate the transactions needed to perform management actions on an existing yield position. This includes claiming rewards, restaking rewards, claiming unstaked tokens after cooldown, rebonding, voting, and other position lifecycle operations.

When to Use

Activate this skill when the user asks to:

• Claim staking rewards (e.g., “Claim my ATOM rewards”)
• Restake/compound rewards (e.g., “Restake my Cosmos rewards”)
• Claim unstaked tokens after cooldown (e.g., “Claim my unstaked DOT”)
• Rebond unstaking tokens (cancel unstake)
• Vote or re-vote with staked tokens
• Migrate a position
• Perform any maintenance on an existing position

Authentication

x-api-key: YOUR_API_KEY

Base URL

https://api.yield.xyz/v1

Step-by-Step Instructions

Step 1: Check Current Position and Available Actions

First, check the user’s balances to see what management actions are available:

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": "0xUserWalletAddress"
  }'

The response shows balance types that indicate available actions:

• rewards > 0 → CLAIM_REWARDS or RESTAKE_REWARDS available
• unstaked > 0 → CLAIM_UNSTAKED available
• unstaking > 0 → REBOND may be available
• locked > 0 → UNLOCK_LOCKED may be available
• staked > 0 → VOTE, REVOTE may be available

Step 2: Determine the Management Action

Action	Description	When to Use
CLAIM_REWARDS	Claim accumulated staking/yield rewards	User has claimable rewards
RESTAKE_REWARDS	Auto-compound rewards back into the position	User wants to restake rewards
CLAIM_UNSTAKED	Claim tokens after cooldown period completes	Unstaking cooldown has ended
REBOND	Cancel an unstaking request and restake	User changed their mind about unstaking
UNLOCK_LOCKED	Unlock locked tokens	Locked tokens ready for unlock
STAKE_LOCKED	Stake locked tokens	User has locked tokens to stake
VOTE	Vote with staked tokens	Governance voting
VOTE_LOCKED	Vote with locked tokens	Governance with locked tokens
REVOTE	Change vote	Update existing vote
MIGRATE	Migrate position to new contract/version	Protocol migration required
WITHDRAW	Withdraw specific balance type	After unlock or claim
DELEGATE	Re-delegate to different validator	User wants to switch validators
VERIFY_WITHDRAW_CREDENTIALS	Verify ETH withdrawal credentials	Ethereum staking setup

Step 3: Create the Manage Action

Endpoint: POST /v1/actions/manage

Request Body (CreateManageActionDto):

{
  "yieldId": "cosmos-atom-native-staking",
  "address": "cosmos1youraddress...",
  "action": "CLAIM_REWARDS",
  "arguments": {}
}

The action field is required and must be one of the action types listed above.

Example: Claim rewards

curl -X POST "https://api.yield.xyz/v1/actions/manage" \
  -H "x-api-key: $YIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "yieldId": "cosmos-atom-native-staking",
    "address": "cosmos1abc...",
    "action": "CLAIM_REWARDS",
    "arguments": {
      "validatorAddress": "cosmosvaloper1..."
    }
  }'

Example: Restake rewards

{
  "yieldId": "cosmos-atom-native-staking",
  "address": "cosmos1abc...",
  "action": "RESTAKE_REWARDS",
  "arguments": {
    "validatorAddress": "cosmosvaloper1..."
  }
}

Example: Claim unstaked tokens (after cooldown)

{
  "yieldId": "polkadot-dot-native-staking",
  "address": "1abc...",
  "action": "CLAIM_UNSTAKED",
  "arguments": {}
}

Example: Rebond (cancel unstake)

{
  "yieldId": "polkadot-dot-native-staking",
  "address": "1abc...",
  "action": "REBOND",
  "arguments": {
    "amount": "10000000000"
  }
}

Response (ActionDto):

{
  "id": "action_manage_456",
  "intent": "manage",
  "type": "CLAIM_REWARDS",
  "status": "CREATED",
  "transactions": [
    {
      "id": "tx_010",
      "type": "CLAIM_REWARDS",
      "status": "CREATED",
      "unsignedTransaction": "..."
    }
  ]
}

Step 4: Sign and Submit Transactions

For each transaction in the response:

1. Sign the unsignedTransaction
2. Broadcast to the blockchain
3. Submit the hash:

curl -X PUT "https://api.yield.xyz/v1/transactions/{transactionId}/submit-hash" \
  -H "x-api-key: $YIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "hash": "0xTransactionHashHere..." }'

Step 5: Verify Completion

curl "https://api.yield.xyz/v1/actions/{actionId}" \
  -H "x-api-key: $YIELD_API_KEY"

Common Workflows

Claim and Restake Rewards (Compound)

1. Check balances → confirm rewards > 0
2. Call POST /v1/actions/manage with action: "RESTAKE_REWARDS"
3. Sign and submit transactions
4. Rewards are automatically re-deposited into the yield

Claim Unstaked After Cooldown

1. Check balances → confirm unstaked > 0 (cooldown must be complete)
2. Call POST /v1/actions/manage with action: "CLAIM_UNSTAKED"
3. Sign and submit transactions
4. Tokens are returned to the user’s wallet

Switch Validators (Redelegate)

1. Query available validators: GET /v1/yields/{yieldId}/validators
2. Call POST /v1/actions/manage with action: "DELEGATE" and the new validatorAddress
3. Sign and submit

Error Handling

Status Code	Meaning	Action
400	Invalid action or parameters	Verify the action type is supported for this yield; check balance types
401	Unauthorized	Verify API key
403	Geoblocked	User’s region is restricted
404	Yield or position not found	Verify yield ID and user address
429	Rate limited	Wait and retry

Edge Cases

• No rewards to claim: If rewards balance is 0, CLAIM_REWARDS will return a 400. Always check balances first.
• Cooldown not complete: CLAIM_UNSTAKED will fail if the cooldown period hasn’t elapsed. Check the balance’s completionDate field.
• Action not supported: Not all manage actions are available for all yields. Lending protocols may not support CLAIM_REWARDS. Check the yield metadata.
• Validator required: For staking yields, most manage actions require validatorAddress in the arguments.
• Multiple validators: If the user is staked with multiple validators, manage actions may need to be called per validator.
• Minimum claim amount: Polygon native staking requires > 1 POL in claimable rewards before claiming is allowed.