Espo Commands
The espo namespace provides access to the Espo indexer for alkanes data and AMM analytics. Espo offers two modules: Essentials for core alkanes data and AMM Data for trading analytics.
Configuration
Configure the Espo RPC endpoint. When using Subfrost, the SDK automatically appends /espo to your base RPC URL:
# Using Subfrost (recommended)
# Base URL format: https://{network}.subfrost.io/v4/{api_key}
# The SDK automatically appends /espo for espo methods
export ALKANES_RPC_URL=https://mainnet.subfrost.io/v4/your_api_key
# Or for local development
export ESPO_RPC_URL=http://localhost:8080
# Or use in command
alkanes-cli --espo-rpc-url http://localhost:8080 espo pingURL Routing
The @alkanes/ts-sdk automatically routes espo requests to the /espo path. When you configure:
const provider = new AlkanesProvider({
network: 'mainnet',
rpcUrl: 'https://mainnet.subfrost.io/v4/your_api_key'
});All provider.espo.* method calls will be routed to: https://{network}.subfrost.io/v4/{api_key}/espo
Essentials Module
Core alkanes data queries including balances, holders, and storage.
ping—Ping the Espo serverget-height—Get current Espo indexer heightget-address-balances—Get alkanes balances for an addressget-address-outpoints—Get outpoints containing alkanes for an addressget-outpoint-balances—Get alkanes balances at a specific outpointget-holders—Get holders of an alkane token (paginated)get-holders-count—Get total holder count for an alkaneget-keys—Get storage keys for an alkane contract (paginated)AMM Data Module
Trading and liquidity analytics for AMM pools.
ammdata-ping—Ping the AMM Data moduleget-candles—Get OHLCV candlestick data for a poolget-trades—Get trade history for a poolget-pools—Get all pools with paginationfind-best-swap-path—Find optimal multi-hop swap routeget-best-mev-swap—Find best MEV arbitrage opportunityExamples
espo ping
Ping the Espo server to check connectivity.
alkanes-cli espo pingespo get-address-balances
Get alkanes balances for a Bitcoin address. Optionally include detailed outpoint information.
# Get balances for an address
alkanes-cli espo get-address-balances bc1q...
# Include outpoint details
alkanes-cli espo get-address-balances bc1q... --include-outpointsespo get-holders
Get paginated list of holders for an alkane token.
# Get first page of holders (100 per page)
alkanes-cli espo get-holders 840000:1
# Get specific page
alkanes-cli espo get-holders 840000:1 --page 2 --limit 50espo get-candles
Get OHLCV candlestick data for a liquidity pool.
# Get 1-hour candles for base token
alkanes-cli espo get-candles 840100:5 --timeframe 1h --side base --limit 100
# Get daily candles for quote token
alkanes-cli espo get-candles 840100:5 --timeframe 1d --side quote --limit 30espo find-best-swap-path
Find the optimal multi-hop swap path between two tokens.
# Find best path with exact input
alkanes-cli espo find-best-swap-path \
--token-in 840000:1 \
--token-out 840000:2 \
--mode exact_in \
--amount-in 1000000 \
--amount-out-min 900000 \
--max-hops 3RPC Method Mapping
Each espo subcommand maps to a JSON-RPC method:
Essentials Module
| CLI Command | JSON-RPC Method |
|---|---|
espo ping | ping |
espo get-height | get_espo_height |
espo get-address-balances | get_address_balances |
espo get-address-outpoints | get_address_outpoints |
espo get-outpoint-balances | get_outpoint_balances |
espo get-holders | get_holders |
espo get-holders-count | get_holders_count |
espo get-keys | get_keys |
AMM Data Module
| CLI Command | JSON-RPC Method |
|---|---|
espo ammdata-ping | ammdata.ping |
espo get-candles | ammdata.get_candles |
espo get-trades | ammdata.get_trades |
espo get-pools | ammdata.get_pools |
espo find-best-swap-path | ammdata.find_best_swap_path |
espo get-best-mev-swap | ammdata.get_best_mev_swap |
Notes
- Espo indexer must be configured and running
- All pagination uses 0-based page numbers
- Alkane IDs are in format 'block:tx' (e.g., '840000:1')
- Outpoints are in format 'txid:vout'
- AMM Data methods require AMM pools to be indexed