Get Positions

Retrieve detailed information about positions for the authenticated subaccount with time range filtering and pagination. This unified endpoint supports both current and historical position data.

Endpoint

POST https://papi.synthetix.io/v1/trade

Request

Request Format

{
  "params": {
    "action": "getPositions",
    "subAccountId": "1867542890123456789",
    "fromTime": 1704067200000,
    "toTime": 1704153600000,
    "limit": 50,
    "offset": 0
  },
  "expiresAfter": 1735689900,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Request Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Request parameters wrapper
`params.action`	string	Yes	Must be `"getPositions"`
`params.subAccountId`	string	Yes	SubAccount ID to retrieve positions for
`params.fromTime`	integer	No	Start time in Unix milliseconds for time-based filtering
`params.toTime`	integer	No	End time in Unix milliseconds for time-based filtering
`params.limit`	integer	No	Maximum number of positions to return (default: 50, max: 100)
`params.offset`	integer	No	Number of positions to skip for pagination (default: 0)

Parameter	Type	Required	Description
`nonce`	uint64	Yes*	Unix milliseconds timestamp (must be monotonically increasing)
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	uint64	No	Unix seconds expiration timestamp (5x rate limit on stale cancels)

:::info Common Parameters These are top-level request parameters. The subAccountId parameter is specified within the params object (see each endpoint's parameter table). :::

:::info SubAccountAction Endpoints Endpoints using SubAccountAction signing (getPositions, getOpenOrders, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getDelegatedSigners, getBalanceUpdates) do not require the nonce parameter. Only signature and optional expiresAfter are needed. :::

Response

Response Structure

Field	Type	Description
`status`	string	Always `"ok"` for successful requests or `"error"` for failures
`response`	array	Array of position objects matching filter criteria (omitted when `status` is `"error"`)
`error`	object	Error details (only present when `status` is `"error"`)
`request_id`	string	Request tracking identifier

Success Response Examples

Multiple Positions (Open and Closed)

{
  "status": "ok",
  "response": [
    {
      "positionId": "pos_12345",
      "subAccountId": "1867542890123456789",
      "symbol": "ETH-USDT",
      "side": "long",
      "entryPrice": "3000.00",
      "quantity": "0.5000",
      "realizedPnl": "150.00",
      "unrealizedPnl": "0.00",
      "usedMargin": "0.00",
      "maintenanceMargin": "0.00",
      "liquidationPrice": "0.00",
      "status": "close",
      "netFunding": "8.50",
      "takeProfitOrderIds": [],
      "stopLossOrderIds": [],
      "updatedAt": 1735689600000,
      "createdAt": 1735686000000
    },
    {
      "positionId": "pos_12346",
      "subAccountId": "1867542890123456789",
      "symbol": "BTC-USDT",
      "side": "short",
      "entryPrice": "42000.00",
      "quantity": "0.1000",
      "realizedPnl": "0.00",
      "unrealizedPnl": "-12.50",
      "usedMargin": "840.00",
      "maintenanceMargin": "420.00",
      "liquidationPrice": "45000.00",
      "status": "open",
      "netFunding": "8.50",
      "takeProfitOrderIds": [],
      "stopLossOrderIds": ["sl_002"],
      "updatedAt": 1735689600000,
      "createdAt": 1735680000000
    }
  ],
  "request_id": "5ccf215d37e3ae6d"
}

Open Positions Only

{
  "status": "ok",
  "response": [
    {
      "positionId": "pos_12347",
      "subAccountId": "1867542890123456789",
      "symbol": "BTC-USDT",
      "side": "long",
      "entryPrice": "43500.00",
      "quantity": "0.2000",
      "realizedPnl": "0.00",
      "unrealizedPnl": "200.00",
      "usedMargin": "1740.00",
      "maintenanceMargin": "870.00",
      "liquidationPrice": "41000.00",
      "status": "open",
      "netFunding": "8.50",
      "takeProfitOrderIds": ["tp_001"],
      "stopLossOrderIds": ["sl_003"],
      "updatedAt": 1735689700000,
      "createdAt": 1735689000000
    }
  ],
  "request_id": "5ccf215d37e3ae6e"
}

Empty Result Set

{
  "status": "ok",
  "response": [],
  "request_id": "5ccf215d37e3ae6f"
}

Position Object

Field	Type	Description
`positionId`	string	Position identifier
`subAccountId`	string	Subaccount identifier
`symbol`	string	Trading symbol (e.g., "BTC-USDT")
`side`	string	Position side: "long" or "short"
`entryPrice`	string	Average entry price
`quantity`	string	Position size/quantity
`realizedPnl`	string	Realized profit/loss
`unrealizedPnl`	string	Unrealized profit/loss
`usedMargin`	string	Margin used for this position
`maintenanceMargin`	string	Maintenance margin required
`liquidationPrice`	string	Position liquidation price
`status`	string	Position status: "open", "close", "update"
`netFunding`	string	Net funding payments (positive = received)
`takeProfitOrderIds`	array[string]	Array of take profit order IDs
`stopLossOrderIds`	array[string]	Array of stop loss order IDs
`updatedAt`	integer	Last update timestamp (Unix milliseconds, not seconds!)
`createdAt`	integer	Creation timestamp (Unix milliseconds, not seconds!)

Position Status Types

Status	Description	Characteristics
`open`	Active position	Has unrealized PnL, margin requirements, liquidation price
`close`	Closed position	Only realized PnL, no margin requirements
`update`	Position being updated	Transitional state during modifications

Position Calculations

realizedPnl: Profit/loss from closed portions of the position
unrealizedPnl: Current profit/loss based on mark price (open positions only)
usedMargin: Margin currently allocated to this position
maintenanceMargin: Minimum margin for position maintenance
liquidationPrice: Price at which position would be liquidated (open positions only)
entryPrice: Volume-weighted average price of all fills that opened the position
netFunding: Net funding payments received/paid for this position

Error Response

{
  "status": "error",
  "error": {
    "message": "Failed to get positions",
    "code": "INTERNAL_ERROR"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Code Examples

Get All Positions

{
  "params": {
    "action": "getPositions",
    "subAccountId": "1867542890123456789",
    "limit": 100
  },
  "expiresAfter": 1735689900,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Position Information

Real-time Data: Open position data is updated in real-time with current mark prices and PnL
Risk Metrics: Includes liquidation prices, margin requirements, and position-level risk assessment
Order Links: References to associated take profit and stop loss orders
Detailed Margins: Both used margin and maintenance margin requirements
USDT Denomination: All monetary values are denominated in USDT for consistency
Performance Tracking: Comprehensive PnL, volume, and fee tracking per position

Code Example

EIP-712 Signature

const domain = {
  name: "Synthetix",
  version: "1",
  chainId: 1,
  verifyingContract: "0x0000000000000000000000000000000000000000"
};
 
const types = {
  SubAccountAction: [
    { name: "subAccountId", type: "uint256" },
    { name: "action", type: "string" },
    { name: "expiresAfter", type: "uint256" }
  ]
};
 
const message = {
  subAccountId: "1867542890123456789",
  action: "getPositions",
  expiresAfter: Math.floor(Date.now() / 1000) + 60 // 1 min from now
};
 
const signature = await signer._signTypedData(domain, types, message);

Implementation Notes

Authentication requires signature by account owner or authorized delegate
Subaccount ID must be valid and accessible to requesting wallet
Pagination: Use limit and offset parameters for result pagination
Returns all positions for the subaccount in current implementation

Signing

All trading methods are signed using EIP-712. Each successful trading request will contain:

A piece of structured data that includes the sender address
A signature of the hash of that structured data, signed by the sender

For detailed information on EIP-712 signing, see EIP-712 Signing.

Nonce Management

The nonce system prevents replay attacks and ensures order uniqueness:

Use current timestamp in milliseconds as nonce
Each nonce must be greater than the previous one
Recommended: Use Date.now() or equivalent
If nonce conflicts occur, increment by 1 and retry

:::note SubAccountAction Exception SubAccountAction endpoints (getPositions, getOpenOrders, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getDelegatedSigners, getBalanceUpdates) do not require a nonce. Only the signature and optional expiresAfter parameters are needed. :::

Error Handling

Common error scenarios:

Error	Description
Invalid signature	EIP-712 signature validation failed
Invalid market symbol	Market symbol not recognized
Nonce already used	Nonce must be greater than previous value
Rate limit exceeded	Too many requests in time window
Request expired	`expiresAfter` timestamp has passed