Yield Farming

The yield system allows you to earn interest on your tokens by depositing them into yield protocols like Aave. You can deposit tokens to start earning yield and withdraw them at any time. This guide covers how to view available yield opportunities and manage your yield positions.

Overview

The yield system provides:

  • Yield Opportunities - View available yield protocols and their APY rates
  • Deposit Tokens - Deposit tokens to start earning yield
  • Withdraw Tokens - Withdraw your tokens and accrued yield
  • APY Information - See current and historical APY rates

Prerequisites

Before using yield features, ensure you have:

  • Completed authentication and have a valid access token
  • Created a wallet
  • Have tokens to deposit (supported tokens only)

Get Available Yields

Retrieve a list of all available yield opportunities with their current APY rates.

Get available yields

curl -X GET https://api.example.com/api/yield \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Yield retrieved successfully",
  "data": {
    "yields": [
      {
        "id": "polygon-aave-USDC",
        "protocol": "Aave",
        "description": "Earn yield on USDC",
        "tokenName": "USD Coin",
        "tokenSymbol": "USDC",
        "tokenAddress": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
        "aTokenName": "Aave USDC",
        "aTokenSymbol": "aPolUSDC",
        "aTokenAddress": "0x625e7708f30ca75bfd92586e17077590c60eb4cd",
        "logo": "https://...",
        "chain": {
          "id": 137,
          "name": "Polygon",
          "logo": "https://...",
          "explorerUrl": "https://polygonscan.com"
        },
        "apy": 5.25,
        "apy24h": 5.2,
        "apy1m": 5.15
      }
    ]
  }
}

Response Fields:

  • yields - Array of yield opportunities
    • id - Unique yield identifier
    • protocol - Protocol name (e.g., "Aave")
    • description - Description of the yield opportunity
    • tokenName - Underlying token name
    • tokenSymbol - Underlying token symbol
    • tokenAddress - Underlying token contract address
    • aTokenName - Yield token name (aToken)
    • aTokenSymbol - Yield token symbol
    • aTokenAddress - Yield token contract address
    • logo - Token logo URL
    • chain - Blockchain information
    • apy - Current APY (Annual Percentage Yield)
    • apy24h - APY 24 hours ago (if available)
    • apy1m - APY 1 month ago (if available)

Note: Results are cached for 10 minutes to improve performance.

Deposit Tokens

Deposit tokens into a yield protocol to start earning interest.

Deposit tokens for yield

curl -X POST https://api.example.com/api/yield/deposit \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "id": "polygon-aave-USDC",
    "amount": "1000.0"
  }'

Required Fields:

  • id - Yield opportunity ID (from the get yields endpoint)
  • amount - Amount to deposit (humanized format, e.g., "1000.0" for 1000 tokens)

Response:

{
  "status": 200,
  "message": "Yield deposited successfully",
  "data": {
    "signature": "0x...",
    "message": "..."
  }
}

Response Fields:

  • signature - Transaction signature data
  • message - Signed message

Note: The deposit transaction is signed automatically. Use the signature data to execute the transaction on-chain.

Withdraw Tokens

Withdraw your tokens and accrued yield from a yield protocol.

Withdraw tokens from yield

curl -X POST https://api.example.com/api/yield/withdraw \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "id": "polygon-aave-USDC",
    "amount": "1000.0"
  }'

Required Fields:

  • id - Yield opportunity ID
  • amount - Amount to withdraw (humanized format, e.g., "1000.0" for 1000 aTokens)

Response:

{
  "status": 200,
  "message": "Yield withdrawn successfully",
  "data": {
    "signature": "0x...",
    "message": "..."
  }
}

Response Fields:

  • signature - Transaction signature data
  • message - Signed message

Note: The withdrawal transaction is signed automatically. Use the signature data to execute the transaction on-chain.

How Yield Works

  1. Deposit Tokens - Deposit your tokens into a yield protocol
  2. Receive aTokens - You receive yield tokens (aTokens) representing your deposit
  3. Earn Interest - Your aTokens accrue interest over time
  4. Withdraw - Withdraw your aTokens to receive your original tokens plus accrued interest

Amount Format

Amounts should be provided in humanized format (decimal number as string). The API automatically converts the humanized amount to the token's smallest unit based on the token's decimals:

  • Deposit: Amount in humanized format for the underlying token
  • Withdraw: Amount in humanized format for the aToken

Examples:

  • 1000 USDC = "1000.0"
  • 1 ETH = "1.0"

APY Rates

APY (Annual Percentage Yield) rates are:

  • Dynamic - Rates change based on market conditions
  • Real-time - Updated regularly from the protocol
  • Historical - Some tokens show 24h and 1m historical APY

APY rates are calculated based on:

  • Current liquidity rate from the protocol
  • Market conditions
  • Token supply and demand

Fees

Yield operations may include:

  • Transaction Fees - Percentage fee on deposits (same as swap fees)
  • Gas Fees - Network gas fees for executing transactions
  • Protocol Fees - Fees charged by the yield protocol (included in APY)

Fees are deducted from the deposit amount. The final amount deposited may be slightly less than requested.

Supported Protocols

Currently supported protocols:

  • Aave - Decentralized lending and borrowing protocol
  • Avenia - Custom yield protocol for BRLA token

More protocols may be added in the future.

Error Handling

Yield Not Found

{
  "status": 404,
  "message": "Yield not found"
}

This error occurs when the yield ID doesn't exist.

Wallet Not Found

{
  "status": 404,
  "message": "Wallet not found"
}

This error occurs when you haven't created a wallet yet.

Error Getting Quote

{
  "status": 404,
  "message": "Error getting quote"
}

This error occurs when there's an issue getting a swap quote for the deposit.

Error Executing Deposit

{
  "status": 404,
  "message": "Error executing deposit"
}

This error occurs when there's an issue executing the deposit transaction.

Error Executing Withdraw

{
  "status": 404,
  "message": "Error executing withdraw"
}

This error occurs when there's an issue executing the withdrawal transaction.

Error Signing Transaction

{
  "status": 500,
  "message": "Error signing transaction"
}

This error occurs when there's an issue signing the transaction.

Error Generating User Operation

{
  "status": 404,
  "message": "Error generating custom user operation"
}

This error occurs when there's an issue creating the user operation for custom protocols.

Complete Flow Example

Here's a complete example of using yield:

# 1. Get available yields
curl -X GET https://api.example.com/api/yield \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 2. Deposit tokens (using id from step 1)
curl -X POST https://api.example.com/api/yield/deposit \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "id": "polygon-aave-USDC",
    "amount": "1000.0"
  }'

# 3. Withdraw tokens later
curl -X POST https://api.example.com/api/yield/withdraw \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "id": "polygon-aave-USDC",
    "amount": "1050.0"
  }'

Important Notes

  1. Yield Accrual: Interest accrues continuously on your deposited tokens. The longer you hold, the more interest you earn.

  2. aTokens: When you deposit, you receive aTokens (yield tokens) that represent your position. These tokens increase in value as interest accrues.

  3. Withdrawal Amount: When withdrawing, specify the amount of aTokens you want to withdraw, not the underlying token amount.

  4. APY Variability: APY rates change based on market conditions. The rate you see is current and may change.

  5. Supported Tokens: Only certain tokens are supported for yield. Check the yields list for available opportunities.

  6. Chain Support: Currently, yields are primarily available on Polygon (chain ID 137).

  7. Automatic Signing: Deposit and withdrawal transactions are automatically signed. You receive signature data to execute on-chain.

  8. Fees: Transaction fees are deducted from deposits. Consider fees when calculating expected returns.

  9. Minimum Amounts: Some protocols may have minimum deposit amounts. Check protocol documentation.

  10. Liquidity: Ensure the protocol has sufficient liquidity for your deposit/withdrawal amount.

  11. Caching: Yield data is cached for 10 minutes. APY rates may be slightly delayed.

  12. Special Protocols: Some yield opportunities (like Avenia BRLA) use custom operations instead of standard swaps.

Security Considerations

  1. Protocol Risk: Understand the risks associated with yield protocols before depositing.

  2. APY Changes: APY rates can change. Don't assume rates will remain constant.

  3. Smart Contract Risk: Yield protocols use smart contracts. Review protocol security before large deposits.

  4. Liquidity Risk: Ensure sufficient liquidity exists for withdrawals, especially for large amounts.

  5. Monitor Positions: Regularly check your yield positions and accrued interest.

  6. Withdrawal Timing: Consider market conditions when withdrawing, as rates may change.

Was this page helpful?