API Overview

The Notional API exposes a unified REST surface plus a WebSocket stream for real-time updates.

Base URLs

REST:      https://api.notional.xyz
WebSocket: wss://ws.notional.xyz

Info Requests

Read-only queries are sent to:

POST /info

Example:

{
  "type": "account",
  "user": "0x1234..."
}

Dedicated read replica endpoints use separate paths:

POST /portfolio
POST /leaderboard

Exchange Requests

State-changing actions are sent to:

POST /exchange

Example:

{
  "action": {
    "type": "order",
    "orders": [],
    "grouping": "na"
  },
  "nonce": 1701234567890,
  "signature": {
    "r": "0x...",
    "s": "0x...",
    "v": 27
  }
}

reportDeposit is the only exchange action that does not require a signature.

Errors

{
  "error": "Missing 'action.type' field",
  "code": "MISSING_FIELD",
  "field": "action.type",
  "timestamp": 1701234567890
}

Some errors return only the error field. 503 responses may also include retryAfter.

Authentication

READ ENDPOINTS

EXCHANGE ENDPOINTS

WEBSOCKET API

API Overview

Base URLs

Info Requests

Exchange Requests

Errors

​Base URLs

​Info Requests

​Exchange Requests

​Errors

Base URLs

Info Requests

Exchange Requests

Errors