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

# List Positions

> List every borrowing position recorded for a market

Returns all positions for a market, newest first, each with its five most recent transactions.

The endpoint reconciles against the chain before reading. Loan state is pulled from the market contract and written back to the position records, so `healthFactor`, `collateralAmount`, `borrowedAmount`, and `status` reflect current chain state rather than the last value the backend happened to write. If the RPC is unavailable the reconciliation is skipped and stored values are returned unchanged.

## Path Parameters

<ParamField path="marketId" type="string" required>Market ID.</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="positions" type="array">
      Position records ordered by `openedAt` descending.

      <Expandable>
        <ResponseField name="id" type="string">Position ID.</ResponseField>
        <ResponseField name="marketId" type="string">Market ID.</ResponseField>
        <ResponseField name="onChainLoanId" type="string">Numeric loan ID on the market contract. Null when the position was recorded without a linked chain loan.</ResponseField>
        <ResponseField name="userAddress" type="string">Borrower address, lowercased.</ResponseField>
        <ResponseField name="collateralAmount" type="string">Collateral posted, in collateral token units.</ResponseField>
        <ResponseField name="borrowedAmount" type="string">Outstanding principal, in borrow asset units.</ResponseField>
        <ResponseField name="interestAccrued" type="string">Interest accrued and unpaid, in borrow asset units.</ResponseField>
        <ResponseField name="healthFactor" type="string">Health factor as a decimal string. At or above `1.0` the loan is healthy. Below `1.0` it is liquidatable.</ResponseField>
        <ResponseField name="priceAtBorrow" type="string">Collateral price recorded when the loan was opened.</ResponseField>
        <ResponseField name="status" type="string">One of `ACTIVE`, `REPAID`, `LIQUIDATED`.</ResponseField>
        <ResponseField name="liquidated" type="boolean">Whether the position was liquidated.</ResponseField>
        <ResponseField name="liquidatedAt" type="string">ISO 8601 timestamp of liquidation, or null.</ResponseField>
        <ResponseField name="closedAt" type="string">ISO 8601 timestamp of closure, or null.</ResponseField>
        <ResponseField name="openedAt" type="string">ISO 8601 timestamp the position was recorded.</ResponseField>
        <ResponseField name="lastUpdated" type="string">ISO 8601 timestamp of the last write.</ResponseField>
        <ResponseField name="transactions" type="array">The five most recent transactions on this position, newest first.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Positions are recorded when a loan is opened through this API on confirm, and are backfilled from chain events during reconciliation. A loan opened by a wallet signing calldata directly is picked up on the next reconciliation pass rather than at broadcast time.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.trusset.org/lending-external-securities/api/positions/{marketId}/positions" \
    -H "X-API-Key: trusset_your_key_here"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.trusset.org/lending-external-securities/api/positions/${marketId}/positions`,
    { headers: { 'X-API-Key': 'trusset_your_key_here' } }
  );
  const { data } = await res.json();
  const atRisk = data.positions.filter(p => parseFloat(p.healthFactor) < 1.1);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "positions": [
        {
          "id": "secpos_014",
          "marketId": "clx_secmarket_001",
          "onChainLoanId": "5",
          "userAddress": "0xabc...def",
          "collateralAmount": "1000.000000000000000000",
          "borrowedAmount": "50000.000000",
          "interestAccrued": "128.750000",
          "healthFactor": "1.842000000000000000",
          "priceAtBorrow": "104.820000",
          "status": "ACTIVE",
          "liquidated": false,
          "liquidatedAt": null,
          "closedAt": null,
          "openedAt": "2025-06-10T08:00:00.000Z",
          "lastUpdated": "2025-06-15T11:58:00.000Z",
          "transactions": [
            {
              "id": "sectx_002",
              "txType": "BORROW",
              "amount": "50000",
              "txHash": "0x123...789",
              "timestamp": "2025-06-10T08:00:00.000Z"
            }
          ]
        }
      ]
    }
  }
  ```
</ResponseExample>