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
}| Field | Description |
|---|---|
| jsonrpc | Must be "2.0" |
| method | Method name with namespace prefix |
| params | Method parameters (array) |
| id | Request 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
| Namespace | Description |
|---|---|
| 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 getblockcountBatch 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
| Code | Description |
|---|---|
| -32700 | Parse error (invalid JSON) |
| -32600 | Invalid Request (invalid JSON-RPC request) |
| -32601 | Method not found (unknown method) |
| -32602 | Invalid params (invalid method parameters) |
| -32603 | Internal error (server error) |
| -32000 | Rate 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 }