JSON-RPC API

Standard JSON-RPC 2.0 endpoint for programmatic access to Shroud tools.

When to Use Which API

Use Case	Endpoint	Format
AI agents with tool discovery	MCP API `POST /mcp`	MCP protocol (streamable HTTP)
Programmatic tool access	JSON-RPC `POST /rpc`	JSON-RPC 2.0 via `tools.call`
OpenAI-compatible AI inference	OpenAI API `POST /v1/chat/completions`	OpenAI chat format
Direct Substrate RPC calls	RPC Proxy `POST /v1/midnight/rpc`	Raw Substrate JSON-RPC
E2E encrypted inference	Cocoon SDK `wss://.../v1/cocoon/stream`	WebSocket + AES-256-GCM

Endpoint

POST /rpc

Authentication

Authorization: Bearer shroud_prod_...
Content-Type: application/json

Methods

tools.list

List all available tools:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools.list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "midnight_getBlock",
        "description": "Get a Midnight block by height or hash",
        "inputSchema": { ... },
        "estimatedCUMilli": 1000,
        "estimatedCUVaries": false
      }
    ]
  }
}

tools.call

Invoke a specific tool:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools.call",
  "params": {
    "tool": "midnight_getBlock",
    "params": {
      "height": 100
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": { "block": { "header": { ... }, "extrinsics": [...] } },
    "usedCUMilli": 1000
  }
}

Available Tools

The same tools available via MCP are accessible through JSON-RPC. See MCP API — Available Tools for the complete list.

Error Codes

Errors follow the JSON-RPC 2.0 spec: a top-level error object with code, message, and an optional data field. Tool-level failures additionally carry a SHROUD code in error.data.errorCode:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "tool not found: midnight_nonExistent",
    "data": {
      "errorCode": "SHROUD_TOOL_NOT_FOUND"
    }
  }
}

Always read the SHROUD code from error.data.errorCode rather than the numeric code — the numeric mapping may evolve, the SHROUD codes are stable.

Standard JSON-RPC Errors

Code	Name	Description
-32700	Parse Error	Invalid JSON
-32600	Invalid Request	Malformed JSON-RPC request
-32601	Method Not Found	Unknown method or unknown tool name
-32602	Invalid Params	Invalid method/tool parameters
-32603	Internal Error	Server-side error or tool execution failure

See Error Reference — SHROUD Error Codes for the full list of error.data.errorCode values and their meanings.

HTTP-Level Errors

Authentication and rate limiting errors are returned at the HTTP level (before JSON-RPC parsing):

HTTP Status	Description
401 Unauthorized	Invalid or missing API key
429 Too Many Requests	Rate limit or CU limit exceeded

Examples

Get chain statistics

curl -X POST https://shroud.us/rpc \
  -H "Authorization: Bearer shroud_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools.call",
    "params": {
      "tool": "midnight_getChainStats",
      "params": {}
    }
  }'

Get account info

curl -X POST https://shroud.us/rpc \
  -H "Authorization: Bearer shroud_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools.call",
    "params": {
      "tool": "midnight_getAccount",
      "params": {
        "address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
      }
    }
  }'

Generic RPC call

curl -X POST https://shroud.us/rpc \
  -H "Authorization: Bearer shroud_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools.call",
    "params": {
      "tool": "midnight_rpc",
      "params": {
        "method": "chain_getFinalizedHead",
        "params": []
      }
    }
  }'

Last modified: 08 May 2026