GET
/
api
/
v1
/
positions
curl -X GET "https://api.roxom.com/api/v1/positions?instType=perpetual&symbol=US500-BTC&unit=sats" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

{
  "data": [
    {
      "positionId": "01234567-89ab-7def-8123-456789abcdef",
      "instrument": "01234567-89ab-7def-8123-456789abcdea",
      "symbol": "OIL-BTC", 
      "isBuy": true,
      "entryAmount": 500000000000,
      "exitAmount": 0,
      "size": 100000,
      "avgEntry": 50000000,
      "avgExit": null,
      "openDate": 1685432112000,
      "closeDate": null,
      "unrealizedPnl": 12500000,
      "markPrice": 50125000,
      "liquidationPrice": 42500000,
      "createdAt": 1685432112000,
      "updatedAt": 1685432512000
    }
  ]
}

​
List Positions

Retrieve all current positions in your account.

​
Endpoint

GET /api/v1/positions

​
Parameters

​
X-API-Key
string
required
API key for authentication
​
instType
string
required
Instrument type (e.g., “perpetual”)
​
symbol
string
required
Trading symbol symbol (e.g., “US500-BTC”, “GOLD-BTC”, “OIL-BTC”)
​
unit
string
default:"sats"
Unit format for values: “sats” or “btc”

​
Example Request

curl -X GET "https://api.roxom.com/api/v1/positions?instType=perpetual&symbol=US500-BTC&unit=sats" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

​
Response

{
  "data": [
    {
      "positionId": "01234567-89ab-7def-8123-456789abcdef",
      "instrument": "01234567-89ab-7def-8123-456789abcdea",
      "symbol": "OIL-BTC", 
      "isBuy": true,
      "entryAmount": 500000000000,
      "exitAmount": 0,
      "size": 100000,
      "avgEntry": 50000000,
      "avgExit": null,
      "openDate": 1685432112000,
      "closeDate": null,
      "unrealizedPnl": 12500000,
      "markPrice": 50125000,
      "liquidationPrice": 42500000,
      "createdAt": 1685432112000,
      "updatedAt": 1685432512000
    }
  ]
}
​
data
array
Array of current position objects

​
Position Types

​
Understanding Values

​
Risk Management

Monitor your positions for:
  • Unrealized P&L: Track profit/loss changes
  • Liquidation Distance: How close current price is to liquidation
  • Position Size: Ensure appropriate risk per position
  • Mark Price Movement: Real-time position valuation

​
Real-time Updates

For real-time position updates, use the WebSocket API: 
// Subscribe to position updates
ws.send(JSON.stringify({
  method: 'subscribe',
  params: {
    channel: 'positions'
  },
  id: 1
}));

// Handle position updates
ws.onmessage = function(event) {
  const data = JSON.parse(event.data);
  if (data.type === 'position') {
    console.log('Position update:', data.data);
  }
};

​
Error Handling

​
No Positions

{
  "data": []
}

​
Authentication Error

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid API key",
  "details": "API key not found or invalid"
}

Account Balance

Check account balance

List Orders

View current orders