Skip to main content
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 "X-API-Signature: your_rsa_signature_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
RSA public key identifier for authentication
​
X-API-Signature
string
required
Base64-encoded RSA signature of the request payload. Payload format: GET:/api/v1/positions?query_params
​
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 "X-API-Signature: your_rsa_signature_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

Long positions profit when price increases:
  • Entry: Buy at lower price
  • Profit: Current price > Entry price
  • Loss: Current price < Entry price
  • Liquidation: Price falls to liquidation level
Short positions profit when price decreases:
  • Entry: Sell at higher price
  • Profit: Current price < Entry price
  • Loss: Current price > Entry price
  • Liquidation: Price rises to liquidation level

​
Understanding Values

All prices are in satoshis (0.00000001 BTC):
  • avg_entry: 50000000 = 0.5 BTC
  • mark_price: 50125000 = 0.50125 BTC
  • liquidation_price: 42500000 = 0.425 BTC
Unrealized P&L = (Mark Price - Entry Price) × Size × Direction
  • Long: Positive when mark > entry
  • Short: Positive when mark < entry
  • Values in satoshis: 12500000 = 0.125 BTC profit
Open Position: close_date is null, avg_exit is nullClosed Position: Both close_date and avg_exit have valuesPartially Closed: exit_amount > 0 but position still has size

​
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
⌘I