> For the complete documentation index, see [llms.txt](https://lavarage.gitbook.io/lavarage/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lavarage.gitbook.io/lavarage/platform/lavarage-api/lavaos-documentation/positions-viewer.md).

# Positions Viewer

### <mark style="color:green;">GET</mark> /positions/v3

Provides real-time position monitoring. Supports filtering by status and includes transitional states.

#### Query Parameters

<table><thead><tr><th width="192">Parameter</th><th width="111">Required</th><th width="109">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td>No</td><td>string</td><td>Filters by status of the position: <code>open</code>, <code>closed</code>, <code>liquidated</code> or <code>all</code>. It's All by default.</td></tr><tr><td><code>userPubKey</code></td><td>No</td><td>string</td><td>Wallet address of the trader.</td></tr><tr><td><code>includeInactionable</code></td><td>No</td><td>boolean</td><td>Include positions that cannot be acted upon. It's False by default.</td></tr><tr><td><code>createdAfter</code></td><td>No</td><td>string</td><td>Shows positions created after a specific datetime.<br><br>For detailed information, refer to the <a href="#time-based">Time-based Filtering</a> section.</td></tr><tr><td><code>createdBefore</code></td><td>No</td><td>string</td><td>Shows positions created before a specific datetime.<br><br>For detailed information, refer to the <a href="#time-based">Time-based Filtering</a> section.</td></tr></tbody></table>

#### Headers

<table><thead><tr><th width="187">Header</th><th width="110">Required</th><th width="111">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>x-api-key</code></td><td>Yes</td><td>string</td><td>API key</td></tr></tbody></table>

#### Example Request

```http
GET https://lavarave.wtf/api/sdk/v1.0/positions/v3?status=all&userPubKey=3qE9X2RwUsauS39gjD7Ago7q5y1iwkHBDwMyihaGzxyy&includeInactionable=true
```

#### Response Fields

<table><thead><tr><th width="182">Field</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>onChainStatus</code></td><td>string</td><td>Current on-chain status of the position transaction. For detailed information, refer to the <a href="#position-lifecycle">Position Lifecycle</a> section.</td></tr><tr><td><code>isActionable</code></td><td>boolean</td><td>Boolean indicating whether the position can be acted upon.</td></tr><tr><td><code>status</code></td><td>string</td><td>Current status of the position: <code>active</code>, <code>sold</code>, <code>sold by take profit</code>, <code>repaid</code>, <code>liquidated</code> or <code>failed</code>.</td></tr><tr><td><code>openTimestamp</code></td><td>string</td><td>ISO datetime when the position was opened.</td></tr><tr><td><code>closeTimestamp</code></td><td>string</td><td>ISO datetime when the position was closed. For open positions, this shows "1970-01-01T00:00:00.000Z".</td></tr><tr><td><code>quoteToken</code></td><td>object</td><td><p>Metadata of the token being borrowed.<br><br>Contains:</p><ul><li><code>address</code></li><li><code>name</code></li><li><code>symbol</code></li><li><code>decimals</code></li></ul></td></tr><tr><td><code>collateralToken</code></td><td>object</td><td><p>Metadata for the collateral token.<br></p><p>Contains:</p><ul><li><code>address</code></li><li><code>name</code></li><li><code>symbol</code></li><li><code>decimals</code></li></ul></td></tr><tr><td><code>initialBorrowQuote</code></td><td>string</td><td>Amount borrowed when the position was opened in quote token.</td></tr><tr><td><code>initialMarginQuote</code></td><td>string</td><td>Initial margin provided by the user when opening the position in quote token.</td></tr><tr><td><code>apr</code></td><td>number</td><td>Annual interest rate for this offer in percentage form, e.g. 169.</td></tr><tr><td><code>lastInterestCollectTimestamp</code></td><td>string</td><td>ISO datetime of the last interest collection.<br><br>Only present when auto-collect occurred, otherwise not included in the response.</td></tr><tr><td><code>initialPositionBase</code></td><td>string</td><td>The size of the position in collateral tokens when it was opened.</td></tr><tr><td><code>closePositionQuote</code></td><td>string</td><td>The size of the position in quote token when it was closed. <br><br>Only present for closed &#x26; liquidated positions. Shows "0" for <code>active</code> and <code>failed</code> positions.</td></tr><tr><td><code>currentPrice</code></td><td>string</td><td>When position = <code>active</code>, this shows the current price of the collateral token in quote token terms.<br><br>When position = <code>closed</code> or <code>liquidated</code>, this shows the price at the time of closing.</td></tr><tr><td><code>positionLtv</code></td><td>number</td><td>Current Loan-to-Value ratio as decimal (e.g., 0.75 = 75%).</td></tr><tr><td><code>positionAddress</code></td><td>string</td><td>Address of the position.</td></tr><tr><td><code>offerAddress</code></td><td>string</td><td>Address of the loan offer.</td></tr><tr><td><code>traderAddress</code></td><td>string</td><td>Wallet address of the trader.</td></tr><tr><td><code>entryPrice</code></td><td>number</td><td>Price at which the position was opened.</td></tr><tr><td><code>interestAccrued</code></td><td>number</td><td>Total interest accrued on this position.</td></tr><tr><td><code>liquidationPrice</code></td><td>number</td><td>Price at which the lender may liquidate the position.</td></tr><tr><td><code>offerCreatedAt</code></td><td>string</td><td>ISO datetime when the original loan offer was created.</td></tr><tr><td><code>updatedAt</code></td><td>number</td><td>UNIX timestamp of the last update to this position record.</td></tr><tr><td><code>takeProfitPrice</code></td><td>string</td><td>Price at which the take profit order will attempt to sell the position. Only present when a take profit price is set for this position.</td></tr><tr><td><p><mark style="color:purple;"><code>positionValue</code></mark></p><p>(Beta)</p></td><td>object</td><td>Calculated position value object containing current valuation and PnL.<br><br>This field is in beta testing and may change in future releases.</td></tr></tbody></table>

#### Response Example

```json
{
  "onChainStatus": "EXECUTED",
  "isActionable": true,
  "status": "active",
  "openTimestamp": "2025-06-21T20:09:46.000Z",
  "closeTimestamp": "1970-01-01T00:00:00.000Z",
  "quoteToken": {
    "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "name": "USD Coin",
    "symbol": "USDC",
    "decimals": 6
  },
  "collateralToken": {
    "address": "5UUH9RTDiSpq6HKS6bp4NdU9PNJpXRXuiw6ShBTBhgH2",
    "name": "TROLL",
    "symbol": "TROLL",
    "decimals": 6
  },
  "initialBorrowQuote": "1983.75",
  "initialMarginQuote": "1250",
  "apr": 169,
  "lastInterestCollectTimestamp": "2025-07-21T02:49:47.000Z",
  "initialPositionBase": "216548.227914",
  "closePositionQuote": "0",
  "currentPrice": "0.0211537163",
  "positionLtv": 0.4350626813191232,
  "positionAddress": "Aq8fpvRW2qBURRcxyyJ99VUmDmJNxNhnbMuQMJFbBSMa",
  "offerAddress": "EbvPQqzarjTUV5cTXuUz9MjQEHb8MMfpTsoRFH6YQREg",
  "traderAddress": "5zX5TajSP6qM36FTgsxapYJKniGi19cV3ztPEG4zSUSJ",
  "entryPrice": 0.014933163070188006,
  "interestAccrued": 9.185034246575343,
  "liquidationPrice": 0.010225769481491157,
  "offerCreatedAt": "2025-04-21T03:55:52.248Z",
  "updatedAt": "2025-06-21T20:09:46.000Z",
  "positionValue": {
    "valueInQuoteToken": 4580.799778560497,
    "pnlInQuoteToken": 1337.8647443139216
  }
}
```

***

### Position Lifecycle

The `onChainStatus` field tracks the lifecycle of a position. This field provides critical information about the current state of positions to understand and respond appropriately to position transitions.

#### Status Types

<table><thead><tr><th width="175">Status</th><th>Description</th></tr></thead><tbody><tr><td><code>NEW</code></td><td>Position created in API, but transaction not yet submitted (auto-fails after 90 seconds)</td></tr><tr><td><code>SUBMITTED</code></td><td>Transaction submitted to blockchain, but not confirmed (auto-fails after 90 seconds)</td></tr><tr><td><code>ONCHAIN</code></td><td>Transaction confirmed on blockchain, but position details not fully synchronized</td></tr><tr><td><code>EXECUTED</code></td><td>Position fully synchronized and active</td></tr><tr><td><code>CLOSED</code></td><td>User initiated closing, transaction in progress (transitional state)</td></tr><tr><td><code>CLOSED_EXECUTED</code></td><td>Position successfully closed and synchronized</td></tr><tr><td><code>FAILED</code></td><td>Position creation failed</td></tr></tbody></table>

#### Error Flow

* `NEW` → `FAILED` (if not submitted within 90 seconds)
* `SUBMITTED` → `FAILED` (if not confirmed within 90 seconds)

#### Actionable Positions

A position is considered "actionable" if it is in one of the following states:

* `ONCHAIN`
* `EXECUTED`

Actionable positions are those that:

* Are confirmed on the blockchain
* Can have operations performed on them (sell, repay, etc.)

***

### Time-based Filtering <a href="#time-based" id="time-based"></a>

You can filter your position queries by creation date (i.e. `openTimestamp`) to retrieve positions from specific time periods.

**Supported formats for these parameters:**

1. ISO date, e.g. `2025-07-31` OR
2. ISO datetime, e.g. `2025-07-31T12:01:05.000Z` OR
3. Relative period labels: `1d`, `1w`, `1m`, `3m`, `6m`, `1y` where `d` = day, `w` = week, `m` = month, `y` = year
   * These labels will be converted into datetime on the server side, e.g. `1w` would be the datetime equal to the time now minus 1 week

**Examples:**

* Get all positions created on a specific date, July 30th, 2025:

  ```
  createdAfter=2025-07-30&createdBefore=2025-07-31
  ```
* Get all positions created within 1 day from now:

  ```
  createdAfter=1d
  ```
* Get all positions created more than 1 month ago:

  ```
  createdBefore=1m
  ```