Alkanes API Reference

The Alkanes API provides methods for interacting with the Alkanes protocol on Bitcoin. It enables querying balances, simulating transactions, and managing protorunes/alkanes assets.

Base URL

All API methods are available via HTTP POST requests to the Sandshrew endpoints:

NetworkEndpoint
Mainnethttps://mainnet.sandshrew.io/v4
Testnethttps://testnet.sandshrew.io/v4
Signethttps://signet.sandshrew.io/v4

RPC Methods

protorunesbyaddress

Query protorunes balances for a specific address.

async protorunesbyaddress({
  address: string,
  protocolTag: bigint
}, blockTag?: string): Promise<{
  outpoints: OutPoint[],
  balanceSheet: RuneOutput[]
}>

Parameters:

  • address: Bitcoin address to query
  • protocolTag: Protocol identifier (1n for Alkanes)

Returns:

  • outpoints: Array of UTXOs containing protorunes
  • balanceSheet: Array of protorune balances

protorunesbyheight

Query protorunes state at a specific block height.

async protorunesbyheight({
  height: number,
  protocolTag: bigint
}, blockTag?: string): Promise<RunesResponse>

protorunesbyoutpoint

Query protorunes at a specific UTXO.

async protorunesbyoutpoint({
  txid: string,
  vout: number,
  protocolTag: bigint
}, blockTag?: string): Promise<OutpointResponse>

simulate

Simulate execution of an Alkanes transaction without broadcasting.

async simulate({
  alkanes: AlkaneTransfer[],
  transaction: string,
  height: bigint,
  block: string,
  txindex: number,
  target: { block: bigint, tx: bigint },
  inputs: bigint[],
  vout: number,
  pointer: number,
  refundPointer: number
}, blockTag?: string): Promise<SimulateResponse>

Usage Examples

Query Balance

import { AlkanesRpc } from '@alkanes/sdk';

const alkanes = new AlkanesRpc('https://mainnet.sandshrew.io/v4');

const balance = await alkanes.protorunesbyaddress({
  address: 'bc1p...',
  protocolTag: 1n,
});

console.log(balance.balanceSheet);

Simulate Transaction

const simulation = await alkanes.simulate({
  alkanes: [],
  transaction: '<raw_tx_hex>',
  height: 880000n,
  txindex: 0,
  target: { block: 2n, tx: 0n },
  inputs: [101n],
  pointer: 0,
  refundPointer: 0,
  vout: 0,
});

Get Alkanes List

const alkanes = await provider.alkanes({
  method: 'getAlkanes',
  params: { limit: 20 }
});

Get Alkanes by Address

const holdings = await provider.alkanes({
  method: 'getAlkanesByAddress',
  params: { address: 'bc1p...' }
});

CLI Integration

The API methods are also accessible via the CLI:

# Query alkanes
oyl provider alkanes -method getAlkanes -params '{"limit": 20}' -p mainnet

# Get balances
oyl provider alkanes -method getAlkanesByAddress \
  -params '{"address":"bc1p..."}' -p mainnet

Error Handling

All methods may return errors with this structure:

interface RPCError {
  code: number;
  message: string;
  data?: any;
}
CodeMeaning
-32700Parse error
-32600Invalid request
-32601Method not found
-32602Invalid params
-32603Internal error

Rate Limits

The public Sandshrew endpoints have rate limits. For production use, consider running your own Metashrew indexer or contacting Sandshrew for API keys.