Yield.xyz

https://docs.yield.xyz/
Admin
Yield.xyz provides a comprehensive API and documentation for accessing and managing various staking...
Tokens:21,202
Snippets:215
Trust Score:7.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install AgentKit Skills

Source: https://docs.yield.xyz/docs/agent-skills

Use the CLI to add the AgentKit repository to your project.

```bash
npx skills add https://github.com/stakekit/agentkit
```

--------------------------------

### Install Yield.xyz AgentKit Plugin

Source: https://docs.yield.xyz/docs/claude-plugin

Commands to add the marketplace and install the plugin within the Claude Code environment.

```bash
/plugin marketplace add stakekit/agentkit
```

```bash
/plugin install yield_agentkit_agent@agentkit
```

--------------------------------

### Configure Skill via Agent

Source: https://docs.yield.xyz/docs/agent-skills

Command to initialize a specific skill after installation.

```text
Set up the <skill-name> skill
```

--------------------------------

### YieldBalanceDto API 1.0 Example

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Represents the legacy balance structure using grouped identifiers and specific balance types.

```json
[
    {
        "groupId": "6bbd9825-6e98-57ac-a93f-f80fce6416d5",
        "type": "staked",
        "amount": "4.000000000000000000",
        "pricePerShare": "1.00308",
        "pendingActions": [],
        "token": {
            "network": "ethereum",
            "name": "Polygon Ecosystem Token",
            "decimals": 18,
            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
            "symbol": "POL",
            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
            "coinGeckoId": "polygon-ecosystem-token"
        },
        "validatorAddress": "0x35B1CA0F398905Cf752e6FE122b51c88022FCa32"
    },
    {
        "groupId": "6bbd9825-6e98-57ac-a93f-f80fce6416d5",
        "type": "rewards",
        "amount": "0.012320444949004356",
        "pricePerShare": "1.00308",
        "pendingActions": [],
        "token": {
            "network": "ethereum",
            "name": "Polygon Ecosystem Token",
            "decimals": 18,
            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
            "symbol": "POL",
            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
            "coinGeckoId": "polygon-ecosystem-token"
        },
        "validatorAddress": "0x35B1CA0F398905Cf752e6FE122b51c88022FCa32"
    },
]
```

--------------------------------

### YieldBalanceDto API 2.0 Example

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Represents the updated balance structure featuring a flat list of positions and unified lifecycle states.

```json
{
    "yieldId": "ethereum-matic-native-staking",
    "balances": [
        {
            "address": "0x6877BB79f680216BbdF01704939037F22193e771",
            "amount": "4.012320000000000000",
            "amountRaw": "4012320000000000000",
            "type": "active",
            "token": {
                "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
                "decimals": 18,
                "name": "Polygon Ecosystem Token",
                "symbol": "POL",
                "logoURI": "https://assets.stakek.it/tokens/pol.svg",
                "network": "ethereum",
                "isPoints": false,
                "coinGeckoId": "polygon-ecosystem-token"
            },
            "pendingActions": [],
            "amountUsd": "0.753225",
            "isEarning": true,
	          "validator": {
                "address": "0xa6e768fEf2D1aF36c0cfdb276422E7881a83e951",
                "preferred": true,
                "name": "Luganodes",
                "logoURI": "https://assets.stakek.it/validators/luganodes.png",
                "website": "https://luganodes.com/",
                "commission": 0.1,
                "votingPower": 0.0007025174416982057,
                "status": "active",
                "providerId": "9ef6235e-b039-4619-8307-c675d374ef8c",
                "tvl": "261849883",
                "rewardRate": {
                    "total": 0.034445959222433965,
                    "rateType": "APR",
                    "components": []
                }
            }
        },
        {
            "address": "0x6877BB79f680216BbdF01704939037F22193e771",
            "amount": "0.012358391919447289",
            "amountRaw": "12358391919447289",
            "type": "claimable",
            "token": {
                "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
                "decimals": 18,
                "name": "Polygon Ecosystem Token",
                "symbol": "POL",
                "logoURI": "https://assets.stakek.it/tokens/pol.svg",
                "network": "ethereum",
                "isPoints": false,
                "coinGeckoId": "polygon-ecosystem-token"
            },
            "pendingActions": [],
            "amountUsd": "0.002320",
            "isEarning": false,
            "validator": {
                "address": "0xa6e768fEf2D1aF36c0cfdb276422E7881a83e951",
                "preferred": true,
                "name": "Luganodes",
                "logoURI": "https://assets.stakek.it/validators/luganodes.png",
                "website": "https://luganodes.com/",
                "commission": 0.1,
                "votingPower": 0.0007025174416982057,
                "status": "active",
                "providerId": "9ef6235e-b039-4619-8307-c675d374ef8c",
                "tvl": "261849883",
                "rewardRate": {
                    "total": 0.034445959222433965,
                    "rateType": "APR",
                    "components": []
                }
            }
        },
    ]
}
```

--------------------------------

### Stake ATOM using v1 API

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

The legacy v1 process for staking involved multiple transaction steps, starting with POST /v1/actions/enter and followed by PATCH /transactions/{id} calls.

```json
POST /v1/actions/enter
PATCH /transactions/{id}
```

--------------------------------

### GET /v1/yields/{yieldId}/balances

Source: https://docs.yield.xyz/docs/balances

Fetch balances for a specific yield position associated with a wallet address.

```APIDOC
## GET /v1/yields/{yieldId}/balances

### Description
Retrieves the balance details for a specific yield position for a given wallet address.

### Method
GET

### Endpoint
/v1/yields/{yieldId}/balances

### Parameters
#### Path Parameters
- **yieldId** (string) - Required - The unique identifier for the yield position.

#### Query Parameters
- **address** (string) - Required - The wallet address owning the position.

### Response
#### Success Response (200)
- **BalanceDto** (object) - Returns one or more balance objects containing token amounts, lifecycle status, validator info, and pending actions.
```

--------------------------------

### GET /v1/yields/{yieldId}/balances

Source: https://docs.yield.xyz/docs/actions

Retrieves current position balances and necessary metadata for managing existing yield positions.

```APIDOC
## GET /v1/yields/{yieldId}/balances

### Description
Retrieves the pending action payload, including the 'passthrough' blob and any required schema arguments for managing a position.

### Method
GET

### Endpoint
/v1/yields/{yieldId}/balances

### Parameters
#### Path Parameters
- **yieldId** (string) - Required - The unique identifier of the yield opportunity.
```

--------------------------------

### Fetch Single Balance using v2 API

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Use the read-only GET endpoint for quick look-ups of a single balance by specifying the yieldId and address.

```json
GET /v1/yields/{yieldId}/balances?address=
```

--------------------------------

### YieldDto JSON Structure Example

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

This JSON object represents the YieldDto, detailing token information, staking arguments for entering and exiting, status, APY, and metadata. It's an example of the data structure used for yield-related information.

```json
{
    "id": "ethereum-matic-native-staking",
    "token": {
        "network": "ethereum",
        "name": "Polygon Ecosystem Token",
        "decimals": 18,
        "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
        "symbol": "POL",
        "logoURI": "https://assets.stakek.it/tokens/pol.svg",
        "coinGeckoId": "polygon-ecosystem-token"
    },
    "tokens": [
        {
            "network": "ethereum",
            "name": "Polygon Ecosystem Token",
            "decimals": 18,
            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
            "symbol": "POL",
            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
            "coinGeckoId": "polygon-ecosystem-token"
        },
        {
            "network": "ethereum",
            "name": "Polygon",
            "decimals": 18,
            "address": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
            "symbol": "MATIC",
            "logoURI": "https://assets.stakek.it/tokens/matic.svg",
            "coinGeckoId": "matic-network"
        }
    ],
    "args": {
        "enter": {
            "addresses": {
                "address": {
                    "required": true,
                    "network": "ethereum"
                }
            },
            "args": {
                "amount": {
                    "required": true,
                    "minimum": 1
                },
                "validatorAddress": {
                    "required": true
                },
                "inputToken": {
                    "required": false,
                    "options": [
                        {
                            "network": "ethereum",
                            "name": "Polygon Ecosystem Token",
                            "decimals": 18,
                            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
                            "symbol": "POL",
                            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
                            "coinGeckoId": "polygon-ecosystem-token"
                        },
                        {
                            "network": "ethereum",
                            "name": "Polygon",
                            "decimals": 18,
                            "address": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
                            "symbol": "MATIC",
                            "logoURI": "https://assets.stakek.it/tokens/matic.svg",
                            "coinGeckoId": "matic-network"
                        }
                    ]
                }
            }
        },
        "exit": {
            "addresses": {
                "address": {
                    "required": true,
                    "network": "ethereum"
                }
            },
            "args": {
                "amount": {
                    "required": true,
                    "minimum": 1
                },
                "validatorAddress": {
                    "required": true
                }
            }
        }
    },
    "status": {
        "enter": true,
        "exit": true
    },
    "apy": 0.03957252184265532,
    "rewardRate": 0.03957252184265532,
    "rewardType": "apr",
    "metadata": {
        "name": "Native Staking",
        "logoURI": "https://assets.stakek.it/tokens/matic.svg",
        "description": "Stake your MATIC natively",
        "documentation": "https://docs.stakek.it/docs/ethereum-matic-native-staking",
        "gasFeeToken": {
            "network": "ethereum",
            "name": "Ethereum",
            "symbol": "ETH",
            "decimals": 18,
            "coinGeckoId": "ethereum",
            "logoURI": "https://assets.stakek.it/tokens/eth.svg"
        },
        "token": {
            "network": "ethereum",
            "name": "Polygon Ecosystem Token",
            "decimals": 18,
            "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
            "symbol": "POL",
            "logoURI": "https://assets.stakek.it/tokens/pol.svg",
            "coinGeckoId": "polygon-ecosystem-token"
        },
        "tokens": [
            {
                "network": "ethereum",
                "name": "Polygon Ecosystem Token",
                "decimals": 18,
                "address": "0x455e53cbb86018ac2b8092fdcd39d8444affc3f6",
                "symbol": "POL",
                "logoURI": "https://assets.stakek.it/tokens/pol.svg",
                "coinGeckoId": "polygon-ecosystem-token"
            },
            {
                "network": "ethereum",
                "name": "Polygon",
                "decimals": 18,
                "address": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
                "symbol": "MATIC",
                "logoURI": "https://assets.stakek.it/tokens/matic.svg",
                "coinGeckoId": "matic-network"
            }
        ],
        "type": "staking",
        "rewardSchedule": "day"
    }
}
```

--------------------------------

### POST /v1/actions/{intent}

Source: https://docs.yield.xyz/docs/actions

Initiates a yield action (enter, exit, or manage) by providing the yield ID, user address, and schema-compliant arguments.

```APIDOC
## POST /v1/actions/{intent}

### Description
Initiates a yield action based on the specified intent. Returns a list of unsigned transactions ready for signing.

### Method
POST

### Endpoint
/v1/actions/{intent}

### Parameters
#### Path Parameters
- **intent** (string) - Required - The action intent: 'enter', 'exit', or 'manage'.

#### Request Body
- **yieldId** (string) - Required - ID of the yield opportunity.
- **address** (string) - Required - User's wallet address.
- **arguments** (object) - Required - Schema-compliant input arguments.
- **passthrough** (object) - Optional - Required for 'manage' intent.
- **action** (string) - Optional - Required for 'manage' intent (e.g., 'REDELEGATE').

### Response
#### Success Response (200)
- **TransactionDto[]** (array) - List of unsigned transactions, gas estimates, and metadata.
```

--------------------------------

### POST /v1/actions/manage

Source: https://docs.yield.xyz/docs/balances

Execute follow-up actions on a yield position, such as claiming rewards, withdrawing, or redelegating.

```APIDOC
## POST /v1/actions/manage

### Description
Executes a pending action on a yield position using the passthrough token and arguments provided by the balance endpoint.

### Method
POST

### Endpoint
/v1/actions/manage

### Request Body
- **yieldId** (string) - Required - The ID of the yield.
- **address** (string) - Required - The wallet address.
- **action** (string) - Required - The type of action (e.g., CLAIM_REWARDS, REDELEGATE).
- **passthrough** (string) - Required - Opaque server-generated string from the balance response.
- **arguments** (object) - Optional - Schema-defined inputs required for the action (e.g., validator address).

### Response
#### Success Response (200)
- **transactions** (array) - A set of constructed transactions ready for signing.
```

--------------------------------

### GET /v1/yields/{yieldId}

Source: https://docs.yield.xyz/docs/actions

Retrieves the schema for a specific yield opportunity, including required arguments for enter and exit actions.

```APIDOC
## GET /v1/yields/{yieldId}

### Description
Retrieves the schema for a specific yield opportunity. This schema defines the required and optional arguments needed to perform actions like staking or exiting.

### Method
GET

### Endpoint
/v1/yields/{yieldId}

### Parameters
#### Path Parameters
- **yieldId** (string) - Required - The unique identifier of the yield opportunity.
```

--------------------------------

### POST /v1/yields/balances

Source: https://docs.yield.xyz/docs/balances

Fetch balances across all yields and networks for a specific wallet.

```APIDOC
## POST /v1/yields/balances

### Description
Retrieves aggregated balance information across all yields and networks for a specified wallet address.

### Method
POST

### Endpoint
/v1/yields/balances

### Response
#### Success Response (200)
- **BalanceDto[]** (array) - A list of balance objects for all positions held by the user.
```

--------------------------------

### AgentKit Architecture Diagram

Source: https://docs.yield.xyz/docs/agent-skills

Visual representation of the relationship between the AgentKit MCP and the various signing implementations.

```text
                    AgentKit MCP
                   (yield discovery + tx building)
                              │
            ┌─────────────────┼────────────────┐
            │                 │                │
       Yield.xyz AgentKit    × Privy        × MoonPay
       (no signer)           (remote)        (local)
```

--------------------------------

### POST /api/v1/stake

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Initiates a staking action using the legacy API 1.0 structure.

```APIDOC
## POST /api/v1/stake

### Description
Initiates a staking action for a specific integration using the legacy API 1.0 format.

### Method
POST

### Request Body
- **addresses** (object) - Required - Contains the user address.
- **integrationId** (string) - Required - The ID of the staking integration.
- **args** (object) - Required - Arguments including tronResource, amount, and validatorAddresses.

### Response Example
{
    "id": "65be9010-2a52-41d6-9389-9594e2a0e1fd",
    "integrationId": "tron-trx-native-staking",
    "status": "CREATED",
    "type": "STAKE",
    "transactions": [...] 
}
```

--------------------------------

### Stake ATOM using v2 API

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

The new v2 API simplifies staking by returning a ready-to-sign transaction list directly after the initial POST /v1/actions/enter call.

```json
POST /v1/actions/enter
```

--------------------------------

### Fetch Batch Balances using v1/v2 API

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

The endpoint for fetching batch balances remains the same in both v1 and v2. Refer to the documentation for advanced request details.

```json
POST /v1/yields/balances
```

--------------------------------

### Claim Rewards using v1 API

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Use the legacy v1 endpoint to claim rewards by specifying the action and providing the passthrough blob from the balance endpoint.

```json
POST /v1/actions/pending
{
  "action": "CLAIM_REWARDS",
  "passthrough": "..."
}
```

--------------------------------

### Manage Actions (Claims, Restakes, Redelegations)

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Endpoint for managing various actions like claiming rewards, restaking, and redelegations. The new method supports a one-shot transaction pattern.

```APIDOC
## POST /v1/actions/manage

### Description
Endpoint for managing actions such as claiming rewards, restaking, and redelegations. Supports a one-shot transaction pattern.

### Method
POST

### Endpoint
/v1/actions/manage

### Parameters
#### Request Body
- **arguments** (object) - Required - Contains the action details.
  - **action** (string) - Required - The type of action to perform (e.g., "CLAIM_REWARDS").
  - **...** (other arguments specific to the action)
- **passthrough** (string) - Required - Blob supplied by the balance endpoint for transaction construction.

### Request Example
```json
{
  "arguments": {
    "action": "CLAIM_REWARDS",
    "yieldId": "example_yield_id"
  },
  "passthrough": "example_passthrough_blob"
}
```

### Response
#### Success Response (200)
- **transaction** (string) - The signed transaction ready to be broadcast.

#### Response Example
```json
{
  "transaction": "0x..."
}
```
```

--------------------------------

### POST /api/v2/stake

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Initiates a staking action using the modern schema-driven API 2.0 structure.

```APIDOC
## POST /api/v2/stake

### Description
Initiates a staking action using the updated schema-driven API 2.0 format, which provides more detailed transaction data including raw amounts and unsigned transactions.

### Method
POST

### Request Body
- **yieldId** (string) - Required - The ID of the yield integration.
- **address** (string) - Required - The user's wallet address.
- **arguments** (object) - Required - Staking parameters including amount, validatorAddresses, and tronResource.

### Response Example
{
    "id": "0d5a5efd-c8e6-4908-9650-2e10dea9f782",
    "intent": "enter",
    "type": "STAKE",
    "yieldId": "tron-trx-native-staking",
    "transactions": [
        {
            "id": "e3ea6342-44fd-423f-97b5-aed43cfa1399",
            "unsignedTransaction": "{...}"
        }
    ]
}
```

--------------------------------

### Yield Entry and Exit Mechanics

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Details the schema for entering and exiting staking positions, including required fields and options.

```APIDOC
## POST /api/v2/yields/{yieldId}/enter

### Description
Enters a staking position for a given yield.

### Method
POST

### Endpoint
/api/v2/yields/{yieldId}/enter

### Parameters
#### Request Body
- **amount** (string) - Required - The amount to stake.
- **validatorAddress** (address) - Required - The validator address to interact with.
- **inputToken** (enum) - Optional - Which token to use for this operation. Options: POL, MATIC.

### Request Example
```json
{
  "amount": "100",
  "validatorAddress": "0x123...",
  "inputToken": "POL"
}
```

### Response
#### Success Response (200)
- **transactionHash** (string) - The hash of the transaction.

#### Response Example
```json
{
  "transactionHash": "0xabc..."
}
```

## POST /api/v2/yields/{yieldId}/exit

### Description
Exits a staking position for a given yield.

### Method
POST

### Endpoint
/api/v2/yields/{yieldId}/exit

### Parameters
#### Request Body
- **amount** (string) - Required - Amount for the transaction. Minimum: "1".
- **validatorAddress** (address) - Required - The validator address to interact with.

### Request Example
```json
{
  "amount": "50",
  "validatorAddress": "0x123..."
}
```

### Response
#### Success Response (200)
- **transactionHash** (string) - The hash of the transaction.

#### Response Example
```json
{
  "transactionHash": "0xdef..."
}
```
```

--------------------------------

### API 1.0 Request for enter-stake

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Initial request structure for the enter-stake flow in API 1.0.

```json
{"addresses":{"address":"TJZKF6Mn5twU1KQfsZLEMoJieGp4g8oFLx"},"integrationId":"tron-trx-native-staking","args":{"tronResource":"ENERGY","amount":"1","validatorAddresses":["TGyrSc9ZmTdbYziuk1SKEmdtCdETafewJ9"]}}
```

--------------------------------

### Vault Configuration Structure

Source: https://docs.yield.xyz/docs/allocator-vaults-and-oavs

Defines the configuration parameters for an Allocator Vault, including various fees and operational settings. Use this structure when setting up or updating vault configurations.

```Solidity
struct AllocatorVaultConfig {
uint256 depositFee;
uint256 performanceFee;
uint256 managementFee;
address feeRecipient;
bool hasCooldown;
}
```

--------------------------------

### Fetch Cosmos Staking Validators using v1 API

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Retrieve validator information for Cosmos staking using the legacy v1 endpoint.

```json
GET /v1/yields/cosmos-atom-native-staking
```

--------------------------------

### Fetch Validators for Cosmos Staking

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

Endpoint to fetch validators for Cosmos native staking.

```APIDOC
## GET /v1/yields/cosmos-atom-native-staking/validators

### Description
Fetches validators for Cosmos native staking.

### Method
GET

### Endpoint
/v1/yields/cosmos-atom-native-staking/validators

### Response
#### Success Response (200)
- **validators** (array of objects) - List of validator objects.

#### Response Example
```json
{
  "validators": [
    {
      "address": "cosmos_validator_address",
      "name": "Validator Name"
    }
  ]
}
```
```

--------------------------------

### Claim Rewards using v2 API

Source: https://docs.yield.xyz/docs/api-20-migration-guide-workflow-and-schema-changes

The new v2 API uses a unified /actions/manage endpoint for claiming rewards, embedding the action within the arguments object along with the passthrough blob.

```json
POST /v1/actions/manage
{
  "arguments": {
    "action": "CLAIM_REWARDS",
    "passthrough": "..."
  }
}
```
Tokens:
Raw