# This wallet's lending earnings

`GET /stats/collateral/earnings` · Lithos client API · Statistics · requires the `api_key` header

Source: https://lithosprotocol.org/docs/api/get-lending-earnings

Every collateral box of this wallet's that a Lithos block spent in retained history, newest
first, with what the lender posted and what came back.

A lender posts the box's whole value: the fixed principal plus any priority fee bid on top. The
block that spends it pays the lender twice, both locked to the lender's key for
`rewardLockBlocks` blocks: the **coinbase**, the block reward, and the block's **fees**, every
transaction fee in it. On mainnet the coinbase is reported less its re-emission tokens, which
a spend of it must pay. `netNanoErg` is what came back less what was posted. The network fee
each join paid is not in it, and neither is the LIT permit, which comes back in full.

`joinedHeight` is the block that included the queue box, so `height - joinedHeight` is how
long the principal waited before it was used, and the reward stays locked
`rewardLockBlocks` after that.

History is kept for `stats.mining.historyDays`; positions spent before `retainedFromHeight`
have been pruned and are in neither the list nor `totals`.

## Parameters

| Name | In | Type | Required | Description |

|---|---|---|---|---|

| `offset` | query | integer · int32 | no | Positions to skip, counting from the newest. |

| `limit` | query | integer · int32 | no | Positions per page. |

## Responses

### 200: One page of spent positions, with totals over all of retained history.

`LendingPage`

- `status` (string, required, one of disabled, loading, ready, stale, unavailable, catching-up, recovering): How far collection has got. `ready` means it reached the last checked chain tip. `catching-up` and `recovering` mean replay or reorg work is still running, `stale` means the last successful check is too old, and `unavailable` means collection failed. On `disabled` or `loading` the numbers are not evidence that the period was quiet.
- `source` (MiningCursor, required): The processed chain point a statistics result was read from.
  - `height` (integer, required)
  - `blockId` (string, required)
  - `parentId` (string, required)
  - `timestamp` (integer · int64, required): The block's own timestamp in Unix milliseconds, not the time the client read it.
- `retainedFromHeight` (integer, required): First retained height. Nothing spent before it is listed or totalled.
- `retainedFromTimestamp` (integer · int64): Timestamp of the first retained block, in milliseconds. Absent while nothing is retained.
- `offset` (integer, required): The offset this page starts at.
- `total` (integer, required): Every spent position in retained history. Pages end at `offset + limit >= total`.
- `positions` (LendingPosition[], required): Newest first.
  - `blockId` (string, required): The Lithos block that spent the box.
  - `height` (integer, required)
  - `timestamp` (integer · int64, required): The block's timestamp, in milliseconds.
  - `collateralBoxId` (string, required)
  - `lenderAddress` (string, required): The wallet key the box named as its lender, which the block paid.
  - `postedNanoErg` (string, required): The box's whole value, principal and priority fee together.
  - `priorityFeeNanoErg` (string, required): The bid on top of the principal, which went to the miners.
  - `coinbaseNanoErg` (string, required): The block reward paid to the lender, less its re-emission tokens on mainnet.
  - `feesNanoErg` (string, required): The block's transaction fees, paid to the lender.
  - `receivedNanoErg` (string, required): `coinbaseNanoErg + feesNanoErg`.
  - `netNanoErg` (string, required): `receivedNanoErg - postedNanoErg`, before the join's network fee.
  - `joinedHeight` (integer): The block that included the queue box. Absent when the node's index does not show it.
- `totals` (LendingTotals, required)
  - `positions` (integer, required)
  - `postedNanoErg` (string, required)
  - `priorityFeesNanoErg` (string, required)
  - `coinbaseNanoErg` (string, required)
  - `feesNanoErg` (string, required)
  - `netNanoErg` (string, required): Received less posted, over every retained position.
- `rewardLockBlocks` (integer, required): Blocks a coinbase or fee reward stays locked to the lender's key after its block.

### 400: `limit` is outside 1–500 or `offset` is negative.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 403: Missing or wrong `api_key`.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 503: History is loading, disabled, busy, or unreadable. Check `mining.status` in /stats before retrying.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

## Example request

```bash
curl -X GET "http://localhost:9000/stats/collateral/earnings" \
  -H "api_key: $LITHOS_API_KEY"
```

## Example response

```json
{
  "status": "disabled",
  "source": {
    "height": 0,
    "blockId": "string",
    "parentId": "string",
    "timestamp": 0
  },
  "retainedFromHeight": 0,
  "retainedFromTimestamp": 0,
  "offset": 0,
  "total": 0,
  "positions": [
    {
      "blockId": "string",
      "height": 0,
      "timestamp": 0,
      "collateralBoxId": "string",
      "lenderAddress": "string",
      "postedNanoErg": "string",
      "priorityFeeNanoErg": "string",
      "coinbaseNanoErg": "string",
      "feesNanoErg": "string",
      "receivedNanoErg": "string",
      "netNanoErg": "string",
      "joinedHeight": 0
    }
  ],
  "totals": {
    "positions": 0,
    "postedNanoErg": "string",
    "priorityFeesNanoErg": "string",
    "coinbaseNanoErg": "string",
    "feesNanoErg": "string",
    "netNanoErg": "string"
  },
  "rewardLockBlocks": 0
}
```