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

# Yield earnings

> Read on-chain protocol balance for a wallet, asset, and provider.

<ParamField header="x-api-key" type="string" required placeholder="your-api-key">
  Your StarkFi API key.
</ParamField>

<ParamField query="wallet" type="string" required>
  User wallet public key.
</ParamField>

<ParamField query="asset" type="string" required>
  Token symbol (e.g. `USDC`).
</ParamField>

<ParamField query="provider" type="enum<string>" required>
  `jupiter_lend` or `kamino`.
</ParamField>

<ParamField query="chain_name" type="string" required>
  Enabled chain, e.g. `solana`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.starkfi.io/yield/earnings?wallet=FmTGYpzX27fDqaiytXUdFVaphC5o68G61Q3uhVM2d8bm&asset=USDC&provider=jupiter_lend&chain_name=solana' \
    --header 'x-api-key: <api_key>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "statusCode": 200,
    "success": true,
    "status": "get_earnings_position",
    "message": "Get earnings wallet position",
    "data": {
      "earnings": [
        {
          "provider": "jupiter_lend",
          "asset": "USDC",
          "wallet": "FmTGYpzX27fDqaiytXUdFVaphC5o68G61Q3uhVM2d8bm",
          "chain_name": "solana",
          "position_on_protocol": 1150.75,
          "earnings_status": "ok",
          "earnings_details": null
        }
      ]
    }
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "statusCode": 400,
    "success": false,
    "status": "params_mismatch",
    "message": "Get earnings params mismatch"
  }
  ```
</ResponseExample>

### Response

<ResponseField name="data.earnings" type="array" required>
  One entry per query. Reads the live balance directly from the protocol — no internal position ID required.
</ResponseField>

<ResponseField name="data.earnings[].position_on_protocol" type="number">
  Current value reported by the provider for that wallet and asset.
</ResponseField>

<ResponseField name="data.earnings[].earnings_status" type="string">
  `ok` on success, or an error code when the protocol lookup failed.
</ResponseField>