alkanes_* Methods

Prefer metashrew_view. The alkanes_* JSON-RPC methods are convenience wrappers and may diverge from canonical metashrew_view semantics over time. New integrations should call metashrew_view directly with the appropriate view function name. The convenience methods below remain available for ergonomic reasons; the mapping is documented per-method.

The alkanes_* namespace provides access to the Alkanes protocol, an L1 metaprotocol smart contract system built on Bitcoin. Alkanes is a variant of protorunes, and therefore a subprotocol of the runes protocol on Bitcoin L1.

Overview

Alkanes are smart contracts that run on Bitcoin, indexed via Metashrew. Each alkanes_* method is a thin convenience wrapper that:

1. Encodes the input arguments into a MessageContextParcel protobuf,
2. Calls metashrew_view with the matching view function name,
3. Decodes the result.

The first two columns of the table below are the canonical metashrew_view mapping — call them directly for stable behavior and broader feature coverage. See Reading Alkane Metadata for a worked example of the meta view function.

| Convenience method | metashrew_view function | Notes | |----------------------------------|---------------------------|-------| | alkanes_protorunesbyaddress | protorunesbyaddress | DEPRECATED in alkanes v3.0 — drop and use the esplora UTXO API + protorunesbyoutpoint on each utxo. | | alkanes_getbytecode | getbytecode | | | alkanes_simulate | simulate | Lower-level than the convenience method — use this for any read-only contract evaluation. | | alkanes_meta | meta | The metashrew_view "meta" form returns the full ABI from the contract's __meta wasm export. The convenience alkanes_meta returns a narrower token-shape and SHOULD NOT be used for non-token alkanes (AMM pools, factories, etc.). | | alkanes_trace | trace | | | alkanes_traceblock | traceblock | |

Methods

alkanes_protorunesbyaddress

Get all alkane tokens held by an address.

Parameters:

• 0 (object): Request object with address and protocolTag
• 1 (string): Block tag (optional, default: "latest")

Request Object:

{
  "address": "bc1q...",
  "protocolTag": "1"
}

Request:

{
  "jsonrpc": "2.0",
  "method": "alkanes_protorunesbyaddress",
  "params": [
    {
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "protocolTag": "1"
    }
  ],
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "outpoints": [
      {
        "outpoint": {
          "txid": "abc123def456...",
          "vout": 0
        },
        "runes": [
          {
            "id": { "block": 840000, "tx": 1 },
            "amount": "1000000000"
          }
        ]
      }
    ]
  },
  "id": 1
}

Lua Example:

local address = args[1]
local result = _RPC.alkanes_protorunesbyaddress({
  address = address,
  protocolTag = "1"
})
return { result_type = type(result) }

---

alkanes_getbytecode

Get the bytecode of an alkane contract.

Parameters:

• 0 (object): Alkane ID with block and tx
• 1 (string): Block tag (optional)

Request:

{
  "jsonrpc": "2.0",
  "method": "alkanes_getbytecode",
  "params": [
    { "block": 840000, "tx": 1 }
  ],
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "bytecode": "0061736d01000000..."
  },
  "id": 1
}

Note: This method is available via JSON-RPC. Lua support may vary.

---

alkanes_simulate

Simulate an alkane transaction.

Parameters:

• 0 (object): Simulation request
• 1 (string): Block tag (optional)

Request:

{
  "jsonrpc": "2.0",
  "method": "alkanes_simulate",
  "params": [
    {
      "alkaneId": { "block": 840000, "tx": 1 },
      "inputs": ["0x..."],
      "target": { "block": 840000, "tx": 2 },
      "pointer": 0,
      "refundPointer": 0,
      "vout": 0,
      "data": "0x..."
    }
  ],
  "id": 1
}

---

alkanes_meta

Get token-shaped metadata about an alkane contract.

Use metashrew_view "meta" instead for any non-token alkane (AMM pool, factory, DAO module). The alkanes_meta convenience method returns a narrower {name, symbol, decimals, totalSupply} shape that assumes token semantics; the canonical meta view function returns the contract's full __meta ABI export — names, opcodes, parameter shapes, return types. See Reading Alkane Metadata.

Parameters:

• 0 (object): Alkane ID with block and tx
• 1 (string): Block tag (optional)

Request:

{
  "jsonrpc": "2.0",
  "method": "alkanes_meta",
  "params": [
    { "block": 840000, "tx": 1 }
  ],
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "name": "Example Token",
    "symbol": "EXT",
    "decimals": 8,
    "totalSupply": "21000000000000000"
  },
  "id": 1
}

Note: This method is available via JSON-RPC. Lua support may vary.

---

Alkane Identifiers

Alkanes are identified by their etching location:

{ "block": 840000, "tx": 1 }

This represents:

• block: The block height where the alkane was created
• tx: The transaction index within that block

String format: 840000:1

---

Protocol Tag

For Alkanes, the protocol tag is always "1":

{ "protocolTag": "1" }