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:8080

URL 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/espo

For 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 server
get_espo_height—Get current indexer height
get_address_balances—Get alkanes balances for an address
get_address_outpoints—Get outpoints with alkanes for an address
get_outpoint_balances—Get alkanes at a specific outpoint
get_holders—Get holders of an alkane (paginated)
get_holders_count—Get holder count for an alkane
get_keys—Get storage keys for an alkane (paginated)

AMM Data Module

Trading and liquidity analytics for AMM pools.

ammdata.ping—Ping the AMM Data module
ammdata.get_candles—Get OHLCV candlestick data
ammdata.get_trades—Get trade history
ammdata.get_pools—Get all pools
ammdata.find_best_swap_path—Find optimal swap route
ammdata.get_best_mev_swap—Find MEV opportunities

Example 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