> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 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.

# SKILL

# 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:

```bash theme={null}
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):**

```json theme={null}
{
  "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**

```bash theme={null}
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**

```json theme={null}
{
  "yieldId": "cosmos-atom-native-staking",
  "address": "cosmos1abc...",
  "action": "RESTAKE_REWARDS",
  "arguments": {
    "validatorAddress": "cosmosvaloper1..."
  }
}
```

**Example: Claim unstaked tokens (after cooldown)**

```json theme={null}
{
  "yieldId": "polkadot-dot-native-staking",
  "address": "1abc...",
  "action": "CLAIM_UNSTAKED",
  "arguments": {}
}
```

**Example: Rebond (cancel unstake)**

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

**Response (ActionDto):**

```json theme={null}
{
  "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:

```bash theme={null}
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

```bash theme={null}
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.