Skip to main content
GET
/
api
/
v1
/
user
/
positions
Get user positions
curl --request GET \
  --url https://api.ekiden.fi/api/v1/user/positions \
  --header 'Authorization: Bearer <token>'
[
  {
    "entry_price": 1,
    "epoch": 1,
    "funding_index": 1,
    "is_cross": true,
    "margin": 1,
    "mark_price": 1,
    "market_addr": "<string>",
    "price": 1,
    "seq": 1,
    "sid": "<string>",
    "side": "<string>",
    "size": 123,
    "timestamp": 1718000000,
    "timestamp_ms": 1718000000000,
    "unrealized_pnl": 123,
    "user_addr": "<string>",
    "initial_margin": 1,
    "initial_margin_mark": 1,
    "leverage": 1,
    "liq_price": 65000000000,
    "maintenance_margin": 1
  }
]

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
market_addr
string | null
​
page
integer
default:1
Required range: x >= 0
​
per_page
integer
default:20
Required range: x >= 0

Response

Successfully retrieved list of positions

​
entry_price
integer<int64>
required

Alias of price for clarity in PnL calculations

Required range: x >= 0
​
epoch
integer<int64>
required
Required range: x >= 0
​
funding_index
integer<int64>
required
Required range: x >= 0
​
is_cross
boolean
required

Margin mode: true for cross, false for isolated

​
margin
integer<int64>
required

Actual collateral currently assigned to this position.

Details:

  • Quote-currency units (scaled integer)
  • Used in equity and liquidation calculations
  • Effective leverage is computed as notional(entry) / margin
  • May differ from initial/maintenance requirements (due to PnL, fees, funding, manual add/remove)
  • In cross mode, reflects the portion of cross margin allocated to this position
Required range: x >= 0
​
mark_price
integer<int64>
required

Current market mark price (scaled integer)

Required range: x >= 0
​
market_addr
string
required

Market address

​
price
integer<int64>
required
Required range: x >= 0
​
seq
integer<int64>
required

Sequence number of the execution where this position was updated

Required range: x >= 0
​
sid
string
required

The address of the user vault

​
side
string
required

Side inferred from size ("buy" for long, "sell" for short)

​
size
integer<int64>
required
​
timestamp
integer<int64>
required
deprecated

Unix timestamp in seconds of the execution where this position was updated

Required range: x >= 0
Example:

1718000000

​
timestamp_ms
integer<int64>
required

Unix timestamp in milliseconds of the execution where this position was updated

Required range: x >= 0
Example:

1718000000000

​
unrealized_pnl
integer<int64>
required

Unrealized PnL at current mark (scaled integer, signed)

​
user_addr
string
required

User address

​
initial_margin
integer<int64> | null

Initial margin requirement based on ENTRY price notional.

Details:

  • Uses entry notional = |size| * entry_price / 10^base_decimals
  • Multiplied by market's initial_margin_ratio (scaled by MARGIN_RATIO_SCALE)
  • Does not fluctuate with current mark price
  • Quote-currency units (scaled integer)
Required range: x >= 0
​
initial_margin_mark
integer<int64> | null

Initial margin requirement based on current MARK price notional.

Details:

  • Uses mark notional = |size| * mark_price / 10^base_decimals
  • Multiplied by market's initial_margin_ratio (scaled by MARGIN_RATIO_SCALE)
  • Fluctuates with mark price
  • Quote-currency units (scaled integer)
Required range: x >= 0
​
leverage
integer<int64> | null

Computed leverage = notional / margin

Required range: x >= 0
​
liq_price
integer<int64> | null

Estimated liquidation price for this position (scaled integer).

Notes:

  • Considers funding indices, leverage limits, and maintenance ratios
  • Applies the correct margin mode (cross vs isolated)
  • Absent when not computable (e.g., zero size)
Required range: x >= 0
Example:

65000000000

​
maintenance_margin
integer<int64> | null

Required maintenance margin for this position at current price/size

Required range: x >= 0