Positions

Endpoint

POST /info

Request Body

Parameter	Type	Description
`type`*	string	Must be `"positions"`
`user`*	string	User’s wallet address (case-insensitive), e.g., `"0x1234567890abcdef..."`

Response

[
  {
    "type": "oneWay",
    "position": {
      "coin": "BTC",
      "cumFunding": {
        "allTime": "0",
        "sinceChange": "0",
        "sinceOpen": "0"
      },
      "entryPx": "50000.00",
      "leverage": {
        "type": "cross",
        "value": 5
      },
      "liquidationPx": "45000.00",
      "marginUsed": "1000.00",
      "maxLeverage": 10,
      "positionValue": "5000.00",
      "returnOnEquity": "0.05",
      "szi": "0.1",
      "unrealizedPnl": "50.00",
      "hasTpsl": false
    }
  }
]

Response Fields

Field	Type	Description
`type`	string	Position type (always “oneWay” for Notional)
`position.coin`	string	Asset symbol (BTC, ETH, SOL, etc.)
`position.cumFunding`	object	Cumulative funding payments
`position.entryPx`	string	Average entry price
`position.leverage`	object	Leverage configuration
`position.liquidationPx`	string \| null	Estimated liquidation price
`position.marginUsed`	string	Margin allocated to position
`position.maxLeverage`	number	Maximum allowed leverage
`position.positionValue`	string	Notional value (size × mark price)
`position.returnOnEquity`	string	ROE as decimal (e.g., “0.05” = 5%)
`position.szi`	string	Signed position size (+ long, - short)
`position.unrealizedPnl`	string	Current unrealized profit/loss
`position.hasTpsl`	boolean	Whether the position currently has TP/SL protection attached

Example Request

curl -X POST https://api.notional.xyz/info \
  -H "Content-Type: application/json" \
  -d '{
    "type": "positions",
    "user": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }'

Error Responses

{
  "error": "Missing 'user' parameter for positions"
}

HTTP Status: 400 Bad Request

Notes

Only positions with non-zero size are returned - Liquidation prices may be null if not calculable - Position sizes are signed (positive = long, negative = short) - All prices and values are in USDC

API OVERVIEW

READ ENDPOINTS

EXCHANGE ENDPOINTS

WEBSOCKET API

Endpoint

Request Body

Response

Response Fields

Example Request

Error Responses

Notes

​Endpoint

​Request Body

​Response

​Response Fields

​Example Request

​Error Responses

​Notes

Endpoint

Request Body

Response

Response Fields

Example Request

Error Responses

Notes