Skip to main content
NEXUS exposes a JSON-RPC 2.0 API over HTTP for interacting with the protocol.

Endpoint

POST http://localhost:8545

Request Format

{
  "jsonrpc": "2.0",
  "method": "nexus_blockNumber",
  "params": [],
  "id": 1
}

Response Format

{
  "jsonrpc": "2.0",
  "result": "0x1a4",
  "id": 1
}

Error Response

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  },
  "id": 1
}

Quick Example

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"nexus_blockNumber","params":[],"id":1}'

API Categories

Error Codes

CodeMessageDescription
-32600Invalid RequestMalformed JSON-RPC
-32601Method not foundUnknown method
-32602Invalid paramsInvalid parameters
-32603Internal errorServer error
-32000Execution errorTransaction failed
-32001Insufficient balanceNot enough funds
-32002Invalid nonceNonce mismatch
-32003Gas limit exceededOut of gas

Rate Limiting

The RPC server implements rate limiting to prevent abuse:
  • Default: 100 requests per second per IP
  • Configurable via node configuration

Authentication

Currently, the RPC API does not require authentication. For production deployments, use a reverse proxy with authentication.

WebSocket Support

WebSocket subscriptions are available on port 8546 (configurable):
const ws = new WebSocket('ws://localhost:8546');
ws.send(JSON.stringify({
  jsonrpc: '2.0',
  method: 'nexus_subscribe',
  params: ['newBlocks'],
  id: 1
}));