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:
| Network | Endpoint |
|---|---|
| Mainnet | https://mainnet.sandshrew.io/v4 |
| Testnet | https://testnet.sandshrew.io/v4 |
| Signet | https://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 queryprotocolTag: Protocol identifier (1n for Alkanes)
Returns:
outpoints: Array of UTXOs containing protorunesbalanceSheet: 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 mainnetError Handling
All methods may return errors with this structure:
interface RPCError {
code: number;
message: string;
data?: any;
}| Code | Meaning |
|---|---|
| -32700 | Parse error |
| -32600 | Invalid request |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal 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.