Espo JSON-RPC API
The Espo indexer provides a JSON-RPC API for querying alkanes data and AMM analytics. The API is organized into two modules: Essentials for core data and AMM Data for trading analytics.
Endpoint
Espo runs on a separate endpoint. When using Subfrost, the @alkanes/ts-sdk automatically appends /espo to your base RPC URL:
# Subfrost endpoint (recommended)
# Base: https://{network}.subfrost.io/v4/{api_key}
# Espo: https://{network}.subfrost.io/v4/{api_key}/espo
# Local development
espo_rpc_url: http://localhost:8080URL Routing with @alkanes/ts-sdk
When you configure the AlkanesProvider with a base RPC URL, all espo method calls are automatically routed to the /espo path:
import { AlkanesProvider } from '@alkanes/ts-sdk';
const provider = new AlkanesProvider({
network: 'mainnet',
rpcUrl: 'https://mainnet.subfrost.io/v4/your_api_key'
});
await provider.initialize();
// Espo methods are automatically routed to /espo
const balances = await provider.espo.getAddressBalances('bc1q...');
// ^ This POSTs to: https://mainnet.subfrost.io/v4/your_api_key/espoFor example, if your rpcUrl is https://mainnet.subfrost.io/v4/your_api_key, espo methods will POST to https://mainnet.subfrost.io/v4/your_api_key/espo
Essentials Module
Core alkanes data including balances, holders, and storage keys.
ping—Ping the Espo serverget_espo_height—Get current indexer heightget_address_balances—Get alkanes balances for an addressget_address_outpoints—Get outpoints with alkanes for an addressget_outpoint_balances—Get alkanes at a specific outpointget_holders—Get holders of an alkane (paginated)get_holders_count—Get holder count for an alkaneget_keys—Get storage keys for an alkane (paginated)AMM Data Module
Trading and liquidity analytics for AMM pools.
ammdata.ping—Ping the AMM Data moduleammdata.get_candles—Get OHLCV candlestick dataammdata.get_trades—Get trade historyammdata.get_pools—Get all poolsammdata.find_best_swap_path—Find optimal swap routeammdata.get_best_mev_swap—Find MEV opportunitiesExample Requests
ping
Ping the Espo server to verify connectivity.
// Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "ping",
"params": {}
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "pong"
}get_address_balances
Get alkanes balances for a Bitcoin address with optional outpoint details.
// Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "get_address_balances",
"params": {
"address": "bc1q...",
"include_outpoints": true
}
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"ok": true,
"address": "bc1q...",
"balances": {
"840000:1": "1000000",
"840000:2": "500000"
},
"outpoints": [
{
"outpoint": "txid:0",
"entries": [...]
}
]
}
}get_holders
Get paginated list of holders for an alkane token.
// Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "get_holders",
"params": {
"alkane": "840000:1",
"page": 0,
"limit": 100
}
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"ok": true,
"alkane": "840000:1",
"page": 0,
"limit": 100,
"total": 1523,
"has_more": true,
"items": [
{
"address": "bc1q...",
"amount": "1000000"
},
...
]
}
}ammdata.get_candles
Get OHLCV (Open, High, Low, Close, Volume) candlestick data for a liquidity pool.
// Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "ammdata.get_candles",
"params": {
"pool": "840100:5",
"timeframe": "1h",
"side": "base",
"limit": 100,
"page": 0
}
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"ok": true,
"pool": "840100:5",
"timeframe": "1h",
"side": "base",
"page": 0,
"limit": 100,
"total": 2400,
"has_more": true,
"candles": [
{
"open_time": "1234567890",
"close_time": "1234571490",
"open": "1000000",
"high": "1050000",
"low": "990000",
"close": "1020000",
"volume": "5000000",
"trades": 45
},
...
]
}
}ammdata.find_best_swap_path
Find the optimal multi-hop swap path between two tokens with configurable routing parameters.
// Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "ammdata.find_best_swap_path",
"params": {
"token_in": "840000:1",
"token_out": "840000:2",
"mode": "exact_in",
"amount_in": "1000000",
"amount_out_min": "900000",
"fee_bps": 30,
"max_hops": 3
}
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"ok": true,
"mode": "exact_in",
"token_in": "840000:1",
"token_out": "840000:2",
"amount_in": "1000000",
"amount_out": "950000",
"fee_bps": 30,
"max_hops": 3,
"hops": [
{
"pool": "840100:5",
"token_in": "840000:1",
"token_out": "840000:3",
"amount_in": "1000000",
"amount_out": "1500000"
},
{
"pool": "840100:6",
"token_in": "840000:3",
"token_out": "840000:2",
"amount_in": "1500000",
"amount_out": "950000"
}
]
}
}ammdata.get_best_mev_swap
Find the best MEV (Maximal Extractable Value) arbitrage opportunity for a token across all available pools.
// Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "ammdata.get_best_mev_swap",
"params": {
"token": "840000:1",
"fee_bps": 30,
"max_hops": 3
}
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"ok": true,
"token": "840000:1",
"fee_bps": 30,
"max_hops": 3,
"amount_in": "1000000",
"amount_out": "1050000",
"profit": "50000",
"hops": [
{
"pool": "840100:5",
"token_in": "840000:1",
"token_out": "840000:2",
"amount_in": "1000000",
"amount_out": "2000000"
},
{
"pool": "840100:6",
"token_in": "840000:2",
"token_out": "840000:1",
"amount_in": "2000000",
"amount_out": "1050000"
}
]
}
}Implementation Notes
- All methods use JSON-RPC 2.0 protocol
- AMM Data methods use dot notation (e.g., 'ammdata.get_candles')
- Alkane IDs are in format 'block:tx' (e.g., '840000:1')
- Outpoints are in format 'txid:vout'
- Pagination is 0-indexed
- All numeric amounts are returned as strings to preserve precision
- BigInt values are converted to strings in responses