Subfrost API Documentation

Welcome to the Subfrost API. This service provides access to Bitcoin, Ordinals, Runes, and Alkanes data.

Data API (REST)

Base URL: https:///v4/api

All endpoints expect POST requests with a JSON body unless otherwise noted.

General

GET /health Service health check.
Response
```
"OK"
```

Bitcoin Price

POST /get-bitcoin-price Get current Bitcoin price in USD.
Response
```
{ "bitcoin": { "usd": 100000 } }
```
POST /get-bitcoin-market-chart Get historical market data.
Request
```
{ "days": "1" }
```

Alkanes

POST /get-alkanes List all alkanes with pagination.

Request

{ "limit": 10, "offset": 0 }

Response

{ "tokens": [...], "total": 100, "count": 10, "limit": 10, "offset": 0 }

POST /get-alkanes-by-address Get alkanes held by a specific address.
Request
```
{ "address": "bc1q..." }
```
Response
```
[ { "alkaneId": { "block": "100", "tx": "1" }, ... } ]
```
POST /get-alkane-details Get details for a specific alkane.
Request
```
{ "alkaneId": { "block": "100", "tx": "1" } }
```
POST /get-alkanes-utxo Get UTXOs containing alkanes for an address.
Request
```
{ "address": "bc1q..." }
```
POST /get-amm-utxos Get AMM-related UTXOs.
Request
```
{ "address": "bc1q..." }
```
Response
```
{ "utxos": [...] }
```
POST /global-alkanes-search Search for alkanes by name or symbol.
Request
```
{ "query": "DOGE", "limit": 10, "offset": 0 }
```
Response
```
{ "tokens": [...], "pools": [] }
```

Balance

POST /get-address-balances Get aggregated balances for an address.

Request

{ "address": "bc1q...", "include_outpoints": true }

Response

{ "ok": true, "address": "...", "balances": { "100:1": "500" }, "outpoints": [...] }

POST /get-outpoint-balances Get balances for a specific outpoint.
Request
```
{ "outpoint": "txid:vout" }
```

AMM

POST /get-trades Get trade history for a pool.

Request

{ "pool": "block:tx", "start_time": 1234567890, "limit": 100 }

Response

{ "ok": true, "trades": [...] }

POST /get-candles Get OHLCV candles for a pool.

Request

{ "pool": "block:tx", "interval": "1h", "limit": 500 }

Response

{ "ok": true, "candles": [...] }

POST /get-reserves Get current reserves for a pool.

Request

{ "pool": "block:tx" }

Response

{ "ok": true, "reserve0": "...", "reserve1": "..." }

Pools

POST /get-pools Get pools created by a factory.

Request

{ "factoryId": { "block": "...", "tx": "..." } }

Response

{ "pools": [...] }

POST /get-pool-details Get details for a specific pool.
Request
```
{ "poolId": { "block": "...", "tx": "..." } }
```
POST /get-token-pairs Get pairs for a specific alkane token.
Request
```
{ "factoryId": { ... }, "alkaneId": { ... } }
```
POST /address-positions Get LP positions for an address.
Request
```
{ "address": "bc1q..." }
```
Response
```
{ "positions": [...] }
```

Storage

POST /get-keys Get storage keys for an alkane.

Request

{ "alkane": "block:tx", "prefix": "optional_prefix", "limit": 100 }

Response

{ "ok": true, "keys": { "key_hex": { "value": "hex", ... } } }

JSON-RPC Endpoint

URL: https:///v4/jsonrpc

To execute these methods remotely, send a POST request to the endpoint with a standard JSON-RPC 2.0 payload:

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

Method Naming Convention:

Namespace: All methods start with a namespace (e.g., esplora_, ord_).
Literal Paths: Use : to separate path segments (e.g., esplora_mempool:recent maps to /mempool/recent).
Dynamic Parameters: Use :: to indicate where a parameter from params should be inserted (e.g., esplora_address::txs with param [addr] maps to /address/addr/txs).
Trailing Parameters: Any remaining parameters are appended to the end of the path.

Lua Scripting Context

When executing Lua scripts via sandshrew_evalscript or sandshrew_evalsaved, a global table _RPC is available.

Naming Convention for `_RPC` Methods:

The method name on _RPC is derived from the JSON-RPC method name by removing all colons (:) and hyphens (-).
The namespace prefix (e.g., esplora_) is preserved.
Arguments are passed as normal Lua function arguments.

Examples:

esplora_address::utxo → _RPC.esplora_addressutxo(address)
esplora_block::txs → _RPC.esplora_blocktxs(hash)
esplora_fee-estimates → _RPC.esplora_feeestimates()
btc_getblockcount → _RPC.btc_getblockcount()

Esplora (Electrs) Methods

Address Methods

esplora_address(address) GET /address/{address}
esplora_address::txs(address) GET /address/{address}/txs
esplora_address::txs:chain(address) GET /address/{address}/txs/chain
esplora_address::txs:mempool(address) GET /address/{address}/txs/mempool
esplora_address::utxo(address) GET /address/{address}/utxo

Transaction Methods

esplora_tx(txid) GET /tx/{txid}
esplora_tx::status(txid) GET /tx/{txid}/status
esplora_tx::hex(txid) GET /tx/{txid}/hex
esplora_tx::raw(txid) GET /tx/{txid}/raw
esplora_tx::merkleblock-proof(txid) GET /tx/{txid}/merkleblock-proof
esplora_tx::merkle-proof(txid) GET /tx/{txid}/merkle-proof
esplora_tx::outspend(txid, vout) GET /tx/{txid}/outspend/{vout}
esplora_tx::outspends(txid) GET /tx/{txid}/outspends

Block Methods

esplora_block(hash) GET /block/{hash}
esplora_block::status(hash) GET /block/{hash}/status
esplora_block::txs(hash) GET /block/{hash}/txs
esplora_block::txs(hash, index) GET /block/{hash}/txs/{index}
esplora_block::txids(hash) GET /block/{hash}/txids
esplora_block::txid(hash, index) GET /block/{hash}/txid/{index}
esplora_block::raw(hash) GET /block/{hash}/raw
esplora_block-height(height) GET /block-height/{height}

Mempool Methods

esplora_mempool() GET /mempool
esplora_mempool:txids() GET /mempool/txids
esplora_mempool:recent() GET /mempool/recent

Fee Methods

esplora_fee-estimates() GET /fee-estimates

Ord Methods

Block Methods

ord_block(hash_or_height) GET /block/{hash_or_height}
ord_blockcount() GET /blockcount
ord_blockhash() GET /blockhash
ord_blockhash(height) GET /blockhash/{height}
ord_blockheight() GET /blockheight
ord_blocks() GET /blocks
ord_blocktime() GET /blocktime

Inscription Methods

ord_inscription(id) GET /inscription/{id}
ord_inscriptions() GET /inscriptions
ord_inscriptions(page) GET /inscriptions/{page}
ord_inscriptions:block(height) GET /inscriptions/block/{height}
ord_inscriptions:block(height, page) GET /inscriptions/block/{height}/{page}
ord_content(inscription_id) GET /content/{inscription_id}
ord_decode(txid) GET /decode/{txid}

Output Methods

ord_output(outpoint) GET /output/{outpoint}
ord_outputs(address) GET /outputs/{address}

Rune Methods

ord_rune(rune) GET /rune/{rune}
ord_runes() GET /runes
ord_runes(page) GET /runes/{page}

Sat Methods

ord_sat(sat) GET /sat/{sat}
ord_sat::at(sat, index) GET /sat/{sat}/at/{index}
ord_sat::inscriptions(sat) GET /sat/{sat}/inscriptions
ord_sat::inscriptions(sat, page) GET /sat/{sat}/inscriptions/{page}

Child/Parent Methods

ord_children(id) GET /children/{id}
ord_children(id, page) GET /children/{id}/{page}
ord_children::inscriptions(id) GET /children/{id}/inscriptions
ord_children::inscriptions(id, page) GET /children/{id}/inscriptions/{page}
ord_parents(id) GET /parents/{id}
ord_parents(id, page) GET /parents/{id}/{page}

Collection Methods

ord_collections() GET /collections
ord_collections(page) GET /collections/{page}

Bitcoin Core RPC Methods

Blockchain

btc_getbestblockhash() getbestblockhash
btc_getblock(blockhash, verbosity) getblock
btc_getblockchaininfo() getblockchaininfo
btc_getblockcount() getblockcount
btc_getblockhash(height) getblockhash
btc_getblockheader(blockhash, verbose) getblockheader
btc_getblockstats(hash_or_height, stats) getblockstats
btc_getchaintips() getchaintips
btc_getchaintxstats(nblocks, blockhash) getchaintxstats
btc_getdifficulty() getdifficulty
btc_getmempoolancestors(txid, verbose) getmempoolancestors
btc_getmempooldescendants(txid, verbose) getmempooldescendants
btc_getmempoolentry(txid) getmempoolentry
btc_getmempoolinfo() getmempoolinfo
btc_getrawmempool(verbose) getrawmempool
btc_gettxout(txid, n, include_mempool) gettxout
btc_gettxoutproof(txids, blockhash) gettxoutproof
btc_gettxoutsetinfo() gettxoutsetinfo
btc_verifytxoutproof(proof) verifytxoutproof

Mining

btc_getmininginfo() getmininginfo
btc_getnetworkhashps(nblocks, height) getnetworkhashps

Network

btc_getnetworkinfo() getnetworkinfo
btc_getnettotals() getnettotals
btc_getpeerinfo() getpeerinfo
btc_ping() ping

Raw Transactions

btc_getrawtransaction(txid, verbose, blockhash) getrawtransaction
btc_sendrawtransaction(hexstring, maxfeerate) sendrawtransaction
btc_testmempoolaccept(rawtxs, maxfeerate) testmempoolaccept
btc_decoderawtransaction(hexstring, iswitness) decoderawtransaction
btc_decodescript(hexstring) decodescript

Metashrew Methods

View Methods

metashrew_view(method, input, block_tag) metashrew_view
metashrew_height() metashrew_height

Alkanes Methods (via metashrew_view)

All alkanes methods are forwarded to metashrew_view internally:

alkanes_getbytecode({block, tx}, block_tag) Get contract bytecode
alkanes_protorunesbyaddress({address, protocolTag}, block_tag) Get protorunes by address
alkanes_<custom_method>(input, block_tag) Any custom alkanes contract method

Sandshrew Methods

Utility Methods

sandshrew_multicall(calls) Execute multiple RPC calls
sandshrew_balances(request) Get comprehensive address balance info

Scripting Methods

sandshrew_evalscript(script, args...) Execute a raw Lua script.
sandshrew_savescript(script) Save a Lua script to server storage. Returns script hash.
sandshrew_evalsaved(hash, args...) Execute a previously saved Lua script by its hash.