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

# Get user earnings

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

Returns the live position value from Jupiter Lend or Kamino for the given wallet — queried directly from the protocol, without internal position IDs.

```shellscript theme={null}
GET /yield/earnings
```

<Steps>
  <Step title="Query parameters">
    All parameters are **required**:

    | Parameter    | Type   | Description                |
    | ------------ | ------ | -------------------------- |
    | `wallet`     | string | User's Solana public key   |
    | `asset`      | string | Token symbol (e.g. `USDC`) |
    | `provider`   | string | `jupiter_lend` or `kamino` |
    | `chain_name` | string | Network (e.g. `solana`)    |

    ```shellscript 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>'
    ```
  </Step>

  <Step title="Expected response">
    ```json 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
          }
        ]
      }
    }
    ```

    | Field                  | Description                                           |
    | ---------------------- | ----------------------------------------------------- |
    | `position_on_protocol` | Current balance/value on the protocol for that wallet |
    | `earnings_status`      | `ok` when the lookup succeeded                        |
    | `earnings_details`     | Error context when `earnings_status` is not `ok`      |
  </Step>
</Steps>

<Info>
  Earnings are read from the protocol directly. If the wallet has no position on the selected provider, `position_on_protocol` may be `null` and `earnings_status` reflects the failure reason.
</Info>