Skip to main content

​
Introduction

The Notional Protocol API provides a complete trading interface compatible with HyperLiquid’s API format. All endpoints support the same request/response structure for seamless integration.

​
Base URL

https://api.notional.xyz
For WebSocket connections: 
wss://ws.notional.xyz

​
API Architecture

Notional uses an event-sourced architecture with three main endpoint categories:

​
Info Endpoints (POST /info)

Query endpoints for retrieving account data, positions, orders, and protocol information. These are read-only operations that return current state. Request Format: 
{
  "type": "account",
  "user": "0x1234..."
}

​
Exchange Endpoints (POST /exchange)

Action endpoints for placing orders, canceling, withdrawing, and other state-changing operations. These require signature verification. Request Format: 
{
  "action": {
    "type": "order",
    "orders": [...]
  },
  "nonce": 1234567890,
  "signature": {
    "r": "0x...",
    "s": "0x...",
    "v": 27
  }
}

​
WebSocket API

Real-time streaming updates for fills, account changes, and order rejections. Connect once and subscribe to multiple channels.

​
Operational Endpoints

Operational endpoints are used for monitoring and internal tooling.
  • GET /health - service health and reconciliation stats (public)
  • GET /venue-scanner - venue scanner status (public when enabled)
  • POST /admin/points/distribute - points distribution (admin-only, requires admin key)

​
Request/Response Format

All endpoints accept JSON payloads and return JSON responses: Success Response: 
{
  // Response data varies by endpoint
}
Error Response: 
{
  "error": "Error message here"
}

​
HTTP Status Codes

CodeDescription
200Success
400Bad request - invalid parameters
401Unauthorized - invalid signature
422Unprocessable entity - invariant violation
500Internal server error
503Service unavailable

​
Rate Limiting

Currently, there are no rate limits enforced. However, excessive usage may result in throttling in future versions.

​
CORS

CORS is enabled for all origins. The API can be called directly from browser-based applications.

​
Health Check

Monitor API availability using the health endpoint: 
GET /health
Response: 
{
  "status": "healthy",
  "timestamp": 1234567890,
  "checks": {
    "lmdb": true,
    "venueReconciliationPoller": true,
    "stateReconciliation": true
  },
  "backpressureEngaged": false,
  "venueReconciliationPoller": {
    "lastPollTime": 1234567890,
    "lastFillTime": 1234567890,
    "totalFillsFetched": 123,
    "totalSelfTradesDetected": 0,
    "pollErrors": 0,
    "pollSuccesses": 42,
    "averagePollLatencyMs": 250,
    "isPolling": true,
    "pollLag": 1200
  },
  "stateReconciliation": {
    "lastReconciliationTime": 1234567890,
    "isReconciliationHealthy": true,
    "divergenceCount": 0,
    "totalReconciliations": 10,
    "successfulReconciliations": 10,
    "failedReconciliations": 0,
    "isReconciling": false,
    "trend": "stable",
    "reconciliationLag": 120000
  },
  "data": {
    "hasCheckpoint": true,
    "checkpoint": {
      "blockNumber": 12345,
      "root_hash": "0x...",
      "timestamp": 1234567890
    }
  }
}

​
Next Steps

Authentication

Learn about signature verification and agent approval

Info Endpoints

Query account data and positions

Exchange Endpoints

Place orders and manage positions

WebSocket API

Stream real-time updates