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

> Enter (deposit into) a yield position on Yield.xyz by generating unsigned transactions via the Actions API. Use when the user wants to stake, deposit, lend, or enter any yield opportunity. Covers transaction generation, signing workflow, and hash submission.

# SKILL

# Enter Position

Generate the transactions needed to enter (deposit into) a yield position using the Yield.xyz Actions API. This skill covers the complete workflow: validating the yield, constructing the enter action, iterating through unsigned transactions, and submitting transaction hashes.

## When to Use

Activate this skill when the user asks to:

* Stake tokens (e.g., "Stake 1 ETH with Lido")
* Deposit into a lending protocol (e.g., "Deposit 1000 USDC into Aave on Ethereum")
* Enter a vault (e.g., "Deposit into Morpho vault")
* Provide liquidity
* Start earning yield on any token

## Authentication

```
x-api-key: YOUR_API_KEY
```

## Base URL

```
https://api.yield.xyz/v1
```

## Step-by-Step Instructions

### Step 1: Verify the Yield Exists and Accepts Deposits

```bash theme={null}
curl "https://api.yield.xyz/v1/yields/{yieldId}" \
  -H "x-api-key: $YIELD_API_KEY"
```

Confirm `status.enter` is `true`. If `false`, the yield is not accepting new deposits.

### Step 2: Check Argument Requirements

From the yield metadata response, inspect the `args.enter` field to determine required arguments:

| Argument             | Type      | When Required                                                                              |
| -------------------- | --------- | ------------------------------------------------------------------------------------------ |
| `amount`             | string    | Always required. Amount in the token's smallest unit (wei for ETH, lamports for SOL, etc.) |
| `validatorAddress`   | string    | Required for native staking yields that require validator selection                        |
| `validatorAddresses` | string\[] | Required for multi-validator staking (e.g., Polkadot)                                      |
| `providerId`         | string    | Required for Ethereum native staking (e.g., `kiln`, `figment`, `p2p`)                      |
| `duration`           | number    | Required for Avalanche staking (in seconds)                                                |
| `inputToken`         | string    | Required when multiple input tokens are accepted (token address or `0x` for native)        |
| `subnetId`           | number    | Required for Bittensor staking                                                             |
| `tronResource`       | string    | Required for Tron staking (`BANDWIDTH` or `ENERGY`)                                        |
| `feeConfigurationId` | string    | Optional. Custom fee configuration ID                                                      |

### Step 3: Select a Validator (if Required)

For staking yields that require a validator:

```bash theme={null}
curl "https://api.yield.xyz/v1/yields/{yieldId}/validators?preferred=true&limit=10" \
  -H "x-api-key: $YIELD_API_KEY"
```

Choose a validator from the response. Prefer validators with `preferred: true`.

### Step 4: Create the Enter Action

**Endpoint:** `POST /v1/actions/enter`

**Request Body (CreateActionDto):**

```json theme={null}
{
  "yieldId": "ethereum-eth-lido-staking",
  "address": "0xYourWalletAddress",
  "arguments": {
    "amount": "1000000000000000000"
  }
}
```

**Example with validator (Cosmos staking):**

```json theme={null}
{
  "yieldId": "cosmos-atom-native-staking",
  "address": "cosmos1youraddress...",
  "arguments": {
    "amount": "1000000",
    "validatorAddress": "cosmosvaloper1..."
  }
}
```

**Example with provider (Ethereum native staking):**

```json theme={null}
{
  "yieldId": "ethereum-eth-everstake-staking",
  "address": "0xYourWalletAddress",
  "arguments": {
    "amount": "32000000000000000000",
    "providerId": "everstake"
  }
}
```

**cURL Example:**

```bash theme={null}
curl -X POST "https://api.yield.xyz/v1/actions/enter" \
  -H "x-api-key: $YIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "yieldId": "ethereum-eth-lido-staking",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "arguments": {
      "amount": "1000000000000000000"
    }
  }'
```

**Response (ActionDto):**

```json theme={null}
{
  "id": "action_abc123",
  "intent": "enter",
  "type": "STAKE",
  "status": "CREATED",
  "transactions": [
    {
      "id": "tx_001",
      "type": "APPROVAL",
      "status": "CREATED",
      "unsignedTransaction": "0x..."
    },
    {
      "id": "tx_002",
      "type": "STAKE",
      "status": "CREATED",
      "unsignedTransaction": "0x..."
    }
  ]
}
```

### Step 5: Sign and Submit Each Transaction

For each transaction in the `transactions` array, in order:

1. **Sign** the `unsignedTransaction` using the user's wallet or signing mechanism
2. **Broadcast** the signed transaction to the blockchain
3. **Submit the hash** to Yield.xyz for tracking:

**Endpoint:** `PUT /v1/transactions/{transactionId}/submit-hash`

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

Alternatively, submit the signed transaction for Yield.xyz to broadcast:

**Endpoint:** `POST /v1/transactions/{transactionId}/submit`

### Step 6: Verify Action Completion

**Endpoint:** `GET /v1/actions/{actionId}`

```bash theme={null}
curl "https://api.yield.xyz/v1/actions/action_abc123" \
  -H "x-api-key: $YIELD_API_KEY"
```

Poll until `status` is `SUCCESS` or `FAILED`.

## Amount Formatting

Amounts must be in the token's smallest unit (base units):

| Token | Decimals | 1 token in base units |
| ----- | -------- | --------------------- |
| ETH   | 18       | `1000000000000000000` |
| USDC  | 6        | `1000000`             |
| SOL   | 9        | `1000000000`          |
| ATOM  | 6        | `1000000`             |
| BTC   | 8        | `100000000`           |
| DOT   | 10       | `10000000000`         |

Formula: `baseUnits = amount * 10^decimals`

## Transaction Types

An enter action may produce multiple transactions that must be executed in order:

| Type       | Description                            |
| ---------- | -------------------------------------- |
| `APPROVAL` | ERC-20 token approval (EVM only)       |
| `STAKE`    | The actual staking/deposit transaction |
| `DELEGATE` | Delegation transaction (staking)       |
| `VOTE`     | Vote transaction (some networks)       |

## Error Handling

| Status Code | Meaning            | Action                                                        |
| ----------- | ------------------ | ------------------------------------------------------------- |
| 400         | Invalid parameters | Check yieldId, address format, amount, and required arguments |
| 401         | Unauthorized       | Verify API key                                                |
| 403         | Geoblocked         | User is in a restricted region; cannot proceed                |
| 404         | Yield not found    | Verify yield ID                                               |
| 429         | Rate limited       | Wait and retry                                                |
| 500         | Server error       | Retry with backoff                                            |

## Edge Cases

* **Approval transactions:** EVM DeFi yields (lending, vaults) often require a token approval transaction before the deposit. Always execute transactions in the order returned.
* **Minimum amounts:** Some yields have minimum deposit amounts. If the amount is too low, you'll receive a 400 error.
* **Geoblocking:** Enter actions enforce geolocation restrictions. A 403 error means the user's region is blocked.
* **Transaction ordering:** Transactions MUST be executed sequentially in the order they appear in the response. Do not parallelize.
* **Gas estimation:** The unsigned transaction includes gas parameters, but the signer may need to re-estimate gas on some networks.
* **ETH native staking minimum:** Ethereum native staking requires exactly 32 ETH per validator.
* **skipPrechecks:** Pass `"skipPrechecks": true` in arguments to bypass pre-execution balance checks if you know the balance is sufficient.