跳到主要内容

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>

BRC20-PROG Endpoint​

For BRC20 Programmable Module (ETH-compatible JSON-RPC):

POST https://mainnet.subfrost.io/v4/jsonrpc/brc20-prog

Or with API key:

POST https://mainnet.subfrost.io/v4/<your-api-key>/brc20-prog

Request Format​

{
  "jsonrpc": "2.0",
  "method": "namespace_methodname",
  "params": [...],
  "id": 1
}
  • jsonrpc (string): Must be "2.0"
  • method (string): Method name with namespace prefix
  • params (array): Method parameters
  • id (number/string): Request identifier

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​

  • 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)
  • brc20_*: BRC20 Programmable Module (e.g., brc20_balanceOf), via the /brc20-prog endpoint
  • subfrost_*: FROST threshold signature wallet, regtest development only (e.g., subfrost_getpublic, subfrost_reset, subfrost_thieve)
  • lua_*: Lua script execution (e.g., lua_evalscript)
  • sandshrew_*: Alias for lua_* (e.g., sandshrew_evalscript)
  • forex_*: Fiat exchange rates (e.g., forex_rates), via the /forex endpoint. See Foreign Exchange.
  • mempool_*: Live Bitcoin and Ethereum mempool (e.g., mempool_info), via the /mempool and /ethereum/mempool endpoints. See Mempool JSON-RPC.

Dedicated endpoints​

These are JSON-RPC 2.0 too, but each is served from its own path and indexer:

  • BTC/USD Pool (/v4/YOUR_API_KEY/btcusd): protobuf views over metashrew_view. See BTC/USD Pool.
  • frUSD Deposits (/v4/YOUR_API_KEY/ethereum/frusd): protobuf views over metashrew_view, indexed by BTC recipient. See frUSD Deposits (Ethereum).
  • Espo (/v4/YOUR_API_KEY/espo): alkanes and AMM analytics (e.g., get_holders, ammdata.get_candles). See Espo.

Method Naming Convention​

Methods use underscores and double colons to represent REST paths:

  • _: Namespace separator (e.g., esplora_address)
  • ::: Path parameter placeholder (e.g., esplora_address::utxo maps to /address/{param}/utxo)

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:

[
  { "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​

  • -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 }

See Lua Scripting for more details.

Next Steps​