👁️‍🗨️Positions Viewer

GET /positions/v3

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

Query Parameters

Parameter
Required
Type
Description

status

No

string

Filters by status of the position: open, closed, liquidated or all. It's All by default.

userPubKey

No

string

Wallet address of the trader.

includeInactionable

No

boolean

Include positions that cannot be acted upon. It's False by default.

createdAfter

No

string

Shows positions created after a specific datetime. For detailed information, refer to the Time-based Filtering section.

createdBefore

No

string

Shows positions created before a specific datetime. For detailed information, refer to the Time-based Filtering section.

Headers

Header
Required
Type
Description

x-api-key

Yes

string

API key

Example Request

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

Response Fields

Field
Type
Description

onChainStatus

string

Current on-chain status of the position transaction. For detailed information, refer to the Position Lifecycle section.

isActionable

boolean

Boolean indicating whether the position can be acted upon.

status

string

Current status of the position: active, sold, sold by take profit, repaid, liquidated or failed.

openTimestamp

string

ISO datetime when the position was opened.

closeTimestamp

string

ISO datetime when the position was closed. For open positions, this shows "1970-01-01T00:00:00.000Z".

quoteToken

object

Metadata of the token being borrowed. Contains:

  • address

  • name

  • symbol

  • decimals

collateralToken

object

Metadata for the collateral token.

Contains:

  • address

  • name

  • symbol

  • decimals

initialBorrowQuote

string

Amount borrowed when the position was opened in quote token.

initialMarginQuote

string

Initial margin provided by the user when opening the position in quote token.

apr

number

Annual interest rate for this offer in percentage form, e.g. 169.

lastInterestCollectTimestamp

string

ISO datetime of the last interest collection. Only present when auto-collect occurred, otherwise not included in the response.

initialPositionBase

string

The size of the position in collateral tokens when it was opened.

closePositionQuote

string

The size of the position in quote token when it was closed. Only present for closed & liquidated positions. Shows "0" for active and failed positions.

currentPrice

string

When position = active, this shows the current price of the collateral token in quote token terms. When position = closed or liquidated, this shows the price at the time of closing.

positionLtv

number

Current Loan-to-Value ratio as decimal (e.g., 0.75 = 75%).

positionAddress

string

Address of the position.

offerAddress

string

Address of the loan offer.

traderAddress

string

Wallet address of the trader.

entryPrice

number

Price at which the position was opened.

interestAccrued

number

Total interest accrued on this position.

liquidationPrice

number

Price at which the lender may liquidate the position.

offerCreatedAt

string

ISO datetime when the original loan offer was created.

updatedAt

number

UNIX timestamp of the last update to this position record.

takeProfitPrice

string

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.

positionValue

(Beta)

object

Calculated position value object containing current valuation and PnL. This field is in beta testing and may change in future releases.

Response Example

{
  "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

Status
Description

NEW

Position created in API, but transaction not yet submitted (auto-fails after 90 seconds)

SUBMITTED

Transaction submitted to blockchain, but not confirmed (auto-fails after 90 seconds)

ONCHAIN

Transaction confirmed on blockchain, but position details not fully synchronized

EXECUTED

Position fully synchronized and active

CLOSED

User initiated closing, transaction in progress (transitional state)

CLOSED_EXECUTED

Position successfully closed and synchronized

FAILED

Position creation failed

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

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
PreviousOffers MatchNextPosition Actions

Last updated