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 ping

URL 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 server
get-height—Get current Espo indexer height
get-address-balances—Get alkanes balances for an address
get-address-outpoints—Get outpoints containing alkanes for an address
get-outpoint-balances—Get alkanes balances at a specific outpoint
get-holders—Get holders of an alkane token (paginated)
get-holders-count—Get total holder count for an alkane
get-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 module
get-candles—Get OHLCV candlestick data for a pool
get-trades—Get trade history for a pool
get-pools—Get all pools with pagination
find-best-swap-path—Find optimal multi-hop swap route
get-best-mev-swap—Find best MEV arbitrage opportunity

Examples

espo ping

Ping the Espo server to check connectivity.

alkanes-cli espo ping

espo 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-outpoints

espo 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 50

espo 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 30

espo 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 3

RPC Method Mapping

Each espo subcommand maps to a JSON-RPC method:

Essentials Module

CLI CommandJSON-RPC Method
espo pingping
espo get-heightget_espo_height
espo get-address-balancesget_address_balances
espo get-address-outpointsget_address_outpoints
espo get-outpoint-balancesget_outpoint_balances
espo get-holdersget_holders
espo get-holders-countget_holders_count
espo get-keysget_keys

AMM Data Module

CLI CommandJSON-RPC Method
espo ammdata-pingammdata.ping
espo get-candlesammdata.get_candles
espo get-tradesammdata.get_trades
espo get-poolsammdata.get_pools
espo find-best-swap-pathammdata.find_best_swap_path
espo get-best-mev-swapammdata.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