Skip to main content

​
Introduction

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

​
Base URL

https://api.notional.xyz
WebSocket base URL: 
wss://ws.notional.xyz

​
REST Surface

​
Info Requests

Read-only queries are sent to: 
POST /info
Example: 
{
  "type": "account",
  "user": "0x1234..."
}

​
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 documented exchange action that does not require a signature.

​
WebSocket API

The WebSocket API streams fills, account changes, order updates, block events, and transaction envelopes.

​
Operational Endpoints

  • GET /health
  • GET /reconciliation
  • POST /reconciliation
  • GET /venue-scanner
  • POST /admin/points/distribute
GET /venue-scanner returns the effective unresolved scanner items after applied withdrawal_scanner_override corrections, along with raw and overridden counts.

​
Response Format

Successful responses vary by endpoint. Simple errors use: 
{
  "error": "Error message here"
}
Many request validation failures and handler errors return machine-readable fields as well: 
{
  "error": "Missing 'action.type' field",
  "code": "MISSING_FIELD",
  "field": "action.type",
  "timestamp": 1701234567890
}
503 responses may also include retryAfter.

​
HTTP Status Codes

CodeDescription
200Success
400Invalid request syntax or parameters
401Unauthorized
422Semantically invalid request or invariant failure
500Internal server error
503Service degraded, unavailable, or backpressured

​
CORS

CORS is enabled for all origins.

​
Health Check

GET /health returns runtime status for LMDB access, reconciliation, oracle readiness, and backpressure state.