JSON-RPC API Overview

The Subfrost API uses JSON-RPC 2.0 as its primary protocol. All methods are accessible through a unified endpoint with namespace prefixes.

Endpoint

POST https://mainnet.subfrost.io/v4/jsonrpc

# With API key in path:
POST https://mainnet.subfrost.io/v4/<your-api-key>

Request Format

{
  "jsonrpc": "2.0",
  "method": "namespace_methodname",
  "params": [...],
  "id": 1
}
FieldDescription
jsonrpcMust be "2.0"
methodMethod name with namespace prefix
paramsMethod parameters (array)
idRequest identifier (number/string)

Response Format

// Success
{
  "jsonrpc": "2.0",
  "result": { /* method result */ },
  "id": 1
}

// Error
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": 1
}

Namespaces

NamespaceDescription
esplora_*Electrs block explorer API (e.g., esplora_address::utxo)
ord_*Ordinals protocol (e.g., ord_inscription)
metashrew_*Metashrew indexer (e.g., metashrew_view)
alkanes_*Alkanes protocol (e.g., alkanes_protorunesbyaddress)
btc_*Bitcoin Core RPC (e.g., btc_getblockcount)
lua_*Lua script execution (e.g., lua_evalscript)

Method Naming Convention

Methods use underscores and double colons to represent REST paths:

  • _ (underscore) - Namespace separator
  • :: (double colon) - Path parameter placeholder
# Examples:
esplora_address::utxo     → GET /address/{address}/utxo
ord_inscription           → GET /inscription/{id}
btc_getblockcount         → bitcoind getblockcount

Batch Requests

Send multiple requests in a single HTTP call:

// Request
[
  { "jsonrpc": "2.0", "method": "btc_getblockcount", "params": [], "id": 1 },
  { "jsonrpc": "2.0", "method": "btc_getbestblockhash", "params": [], "id": 2 },
  { "jsonrpc": "2.0", "method": "esplora_fee-estimates", "params": [], "id": 3 }
]

// Response
[
  { "jsonrpc": "2.0", "result": 850000, "id": 1 },
  { "jsonrpc": "2.0", "result": "000000000000000000...", "id": 2 },
  { "jsonrpc": "2.0", "result": { "1": 25.5, "6": 15.2 }, "id": 3 }
]

Error Codes

CodeDescription
-32700Parse error (invalid JSON)
-32600Invalid Request (invalid JSON-RPC request)
-32601Method not found (unknown method)
-32602Invalid params (invalid method parameters)
-32603Internal error (server error)
-32000Rate limit exceeded

Using in Lua Scripts

All RPC methods are available in Lua scripts via the _RPC global table:

-- From within a lua_evalscript
local height = _RPC.btc_getblockcount()
local utxos = _RPC.esplora_addressutxo("bc1q...")
local inscription = _RPC.ord_inscription("abc123i0")

return { height = height, utxo_count = #utxos }