SKILL

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.

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

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:

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

{
  "yieldId": "ethereum-eth-lido-staking",
  "address": "0xYourWalletAddress",
  "arguments": {
    "amount": "1000000000000000000"
  }
}

Example with validator (Cosmos staking):

{
  "yieldId": "cosmos-atom-native-staking",
  "address": "cosmos1youraddress...",
  "arguments": {
    "amount": "1000000",
    "validatorAddress": "cosmosvaloper1..."
  }
}

Example with provider (Ethereum native staking):

{
  "yieldId": "ethereum-eth-everstake-staking",
  "address": "0xYourWalletAddress",
  "arguments": {
    "amount": "32000000000000000000",
    "providerId": "everstake"
  }
}

cURL Example:

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

{
  "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

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}

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.