# List your positions and offers

`GET /forwards/positions` · Lithos client API · Difficulty Forwards · requires the `api_key` header

Source: https://lithosprotocol.org/docs/api/list-df-positions

Every position this wallet holds a side of, by window end, with its status and a mark against the strike; and every unspent offer it made, open or not, so expired ones can be cancelled.

## Responses

### 200: This wallet's positions and offers

`DFPositionList`

- `height` (integer · int32, required)
- `currentEpoch` (integer · int32, required)
- `positions` (DFPositionView[], required)
  - `boxId` (string, required)
  - `side` (string, required, one of long, short, both): This wallet's side; `both` when it holds both keys.
  - `long` (string, required): Address the long side is paid to.
  - `short` (string, required)
  - `strike` (string, required)
  - `notional` (string, required)
  - `margin` (string, required)
  - `windowStart` (integer · int32, required)
  - `windowLength` (integer · int32, required)
  - `windowEnd` (integer · int32, required)
  - `status` (string, required, one of waiting, in_window, settleable, refundable): `waiting` before the window starts, `in_window` until its last epoch is recorded, `settleable` once it is, and `refundable` once its first epoch has left the accumulator, when each side gets its margin back.
  - `epochsKnown` (integer · int32, required): Window epochs whose difficulty is known, recorded or current.
  - `markDifficulty` (string): The window's mean with every unknown epoch at the newest difficulty known. Absent when refundable.
  - `markMove` (number · double): `markDifficulty` against the strike, as a fraction.
  - `markPayout` (string): LIT base units the long side would receive on top of its margin at the mark, negative when the short side is paid; at most the margin either way. Exact once settleable.
  - `pnl` (string): `markPayout` from this wallet's side; zero when it holds both.
  - `owedLong` (string): LIT base units a settlement now pays the long side, margin included. Present once settleable or refundable.
  - `owedShort` (string)
- `offers` (DFOfferView[], required): Every unspent offer this wallet made, open, expired or unfillable.
  - `boxId` (string, required)
  - `maker` (string, required): Address the maker is paid to.
  - `makerSide` (string, required, one of long, short): `long` is paid when the window's mean difficulty is above the strike, `short` when below.
  - `strike` (string, required): Difficulty the window's mean is measured against.
  - `notional` (string, required): LIT base units.
  - `margin` (string, required): Each side's margin, a fifth of the notional, and the most either side can lose of it.
  - `windowStart` (integer · int32, required)
  - `windowLength` (integer · int32, required)
  - `windowEnd` (integer · int32, required): The window's last epoch.
  - `expiry` (integer · int32, required): The last height a fill can be mined at.
  - `lastFillHeight` (integer · int32, required): The last height a fill can actually be mined at: the expiry, or earlier when the window would start less than 2 epochs after the fill.
  - `lit` (string, required): LIT base units the offer holds.
  - `nanoErgs` (string, required)
  - `takerLit` (string, required): LIT base units a fill takes from the taker.
  - `takerNanoErgs` (string, required): nanoERG a fill takes from the taker, network fee included.
  - `impliedMove` (number · double): The strike against the current difficulty, as a fraction.
  - `impliedMoveNext` (number · double): The strike against `nextDifficulty`, when known.
  - `mine` (boolean, required): Whether this wallet made the offer.
  - `fillable` (boolean, required): Whether this wallet's fill sent now would be accepted.
  - `refusal` (string): Why not, when `fillable` is false.
- `truncated` (boolean, required): Whether a scan stopped at 2,000 boxes, so older boxes may be missing.

### 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: Node or index unavailable. Never returns a partial list.

`ApiError`

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

### default: Error

`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/forwards/positions" \
  -H "api_key: $LITHOS_API_KEY"
```

## Example response

```json
{
  "height": 0,
  "currentEpoch": 0,
  "positions": [
    {
      "boxId": "string",
      "side": "long",
      "long": "string",
      "short": "string",
      "strike": "string",
      "notional": "string",
      "margin": "string",
      "windowStart": 0,
      "windowLength": 0,
      "windowEnd": 0,
      "status": "waiting",
      "epochsKnown": 0,
      "markDifficulty": "string",
      "markMove": 0,
      "markPayout": "string",
      "pnl": "string",
      "owedLong": "string",
      "owedShort": "string"
    }
  ],
  "offers": [
    {
      "boxId": "string",
      "maker": "string",
      "makerSide": "long",
      "strike": "string",
      "notional": "string",
      "margin": "string",
      "windowStart": 0,
      "windowLength": 0,
      "windowEnd": 0,
      "expiry": 0,
      "lastFillHeight": 0,
      "lit": "string",
      "nanoErgs": "string",
      "takerLit": "string",
      "takerNanoErgs": "string",
      "impliedMove": 0,
      "impliedMoveNext": 0,
      "mine": true,
      "fillable": true,
      "refusal": "string"
    }
  ],
  "truncated": true
}
```