Introduction

This guide explains how to interact with ElectrumX endpoints using the @wizz-btc/api package.

We retrieve Atomicals-related information by sending a request to the ElectrumX endpoint during development and integration with the ElectrumX service.

We can send a GET or POST HTTP request to fetch data from the endpoint. However, a better option is to use the ElectrumApi class provided by the @wizz-btc/api npm package.

Installation

Prerequisites

Before installing @wizz-btc/api, ensure the following requirements are met:

  • Node.js Installed: You need to have Node.js installed on your system. We recommend using the latest LTS (Long-Term Support) version for stability. You can download it from the official Node.js website or use a version manager like nvm to install it.

  • Existing Node.js Project: You should have an existing Node.js project set up with a package.json file.

Installation

Open your terminal, navigate to your project directory, and run the following command to install @wizz-btc/api as a dependency:

npm i @wizz-btc/api

ElectrumApi

The ElectrumxApi provides methods to simplify interacting with Electrumx endpoints.

Return value

All values returned by ElectrumxApi's methods are wrapped in a ToResult<T> type.

type ToResult<T> = [Error | {
    code: number
    message: string
} | any, undefined] | [null, T]

This guide assumes all methods execute successfully without errors. And all Result in the examples are success values from ToResult<T>.

Endpoints

The atomicals-electrumx define the following atomicals related endpoints:

List Scripthash

Return the list of Atomical UTXOs for an address.

Method

atomicalsByScripthash

Parameters

{
  scripthash: string
  verbose?: boolean
}

Example

Code

const scripthash =
  'ab86b05785673cc9191f34fdaf3a31c0bcf091dbf5c784bb7f2d310d1cbef983'
const result: ToResult<AtomicalScripthashResponse> =
  await api.atomicalsByScripthash({ params: { scripthash } })

Result

Too lang.

List

Retrieve the list of Atomicals in order.

Method

atomicalsList

Parameters

{
  limit: number
  offset: number
  asc: boolean
}

Example

Code

const result: ToResult<{ global: GlobalResult, result: AtomicalStatus[] }> =
  await api.atomicalsList({ params: { limit: 2, offset: 0, asc: true } })

Result

Too long.

Get

Get atomical information for a given atomical id/number.

Method

atomicalsGet

Parameters

{
  atomicalAliasOrId: string | number
}

Example

Code

const atomicalAliasOrId =
  '7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0'
const result: ToResult<{ global: GlobalResult, result: AtomicalStatus }> =
  await api.atomicalsGet({ params: { atomicalAliasOrId } })

Result

{
  "global": {
    "atomical_count": 226639,
    "atomicals_block_hashes": {
      "890669": "ed5db17ffabe2c150b90eecccaf9f92ccb7bf6dd5c5eb66c8554dad76faf066e",
      "890670": "a637ec2bf84ca5a30b3b638b16f6850372c0bc323f8909fcc640b851efb69f40",
      "890671": "677202da3457401b3c24f958200a1e48e0faf1436cecee6e8ec76b58a59ef7b2",
      "890672": "60cf87b2eee70acdc7894a9d7a3eefb4aee3395e9b98a7586295d585513dbc15",
      "890673": "a140cc9af059edc21187c2eddde10f8fbf3dcee1b7c7485bf8c4571cd753290a",
      "890674": "ab6ba302a1d4266f6147e282e0abaa45e9ff9c3b5fd2dbf1c940e4163785293c",
      "890675": "27f563f71f3273edd8eeffe24551fd35c9c7c21cf9359e3e52a06d1737ad0c33",
      "890676": "03661c9325fff3ac9c8e740b26ee4c7cf5177314b0e36a0ee8f9ef0d7d89d253",
      "890677": "38efc5dcaf9e6b53c9e8ec7812249cb3688c09fb6ca25a1bc530bf120f3f629f",
      "890678": "76723a5a59c360c76949dcd37df4fa5eb1157aca175d2a9529905659601045f6"
    },
    "atomicals_block_tip": "76723a5a59c360c76949dcd37df4fa5eb1157aca175d2a9529905659601045f6",
    "block_tip": "00000000000000000000f6991578409662439ed3358a3698520156197e8abeaa",
    "coin": "Bitcoin",
    "height": 890678,
    "network": "mainnet",
    "server_time": "2025-04-03T08:59:24.477001"
  },
  "result": {
    "$bitwork": {
      "bitworkc": "5557",
      "bitworkr": null
    },
    "$full_realm_name": "techtoshi",
    "$realm": "techtoshi",
    "$realm_candidates": [
      {
        "atomical_id": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0",
        "commit_height": 880018,
        "reveal_location_height": 880018,
        "tx_num": 1145635051,
        "txid": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203ae"
      }
    ],
    "$request_realm": "techtoshi",
    "$request_realm_status": {
      "note": "Successfully verified and claimed realm for current Atomical.",
      "status": "verified",
      "verified_atomical_id": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0"
    },
    "atomical_id": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0",
    "atomical_number": 226048,
    "atomical_ref": "anbgbqv29vmaqw24wr0bbjq1xg53rw3y5yt1cxrj8kw8dak20eq0i0",
    "confirmed": true,
    "mint_data": {
      "fields": {
        "args": {
          "bitworkc": "5557",
          "nonce": 8087572,
          "request_realm": "techtoshi",
          "time": 1737347293
        }
      }
    },
    "mint_info": {
      "$bitwork": {
        "bitworkc": "5557",
        "bitworkr": null
      },
      "$immutable": false,
      "$request_realm": "techtoshi",
      "args": {
        "bitworkc": "5557",
        "nonce": 8087572,
        "request_realm": "techtoshi",
        "time": 1737347293
      },
      "commit_height": 880018,
      "commit_index": 0,
      "commit_location": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0",
      "commit_tx_num": 1145635051,
      "commit_txid": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203ae",
      "ctx": {},
      "meta": {},
      "reveal_location": "30fa8c81bb2e80fabe03251a8a44b301e0f3c18be0ea5eb2971e9ec01cf9e7c1i0",
      "reveal_location_blockhash": "d919a5da3cf934b32bdad0beadd036a49d184f7039bb00000000000000000000",
      "reveal_location_header": "00e0c0251c98569aa0ae284c47575bb6f6d164abd163bf0be9d000000000000000000000b5d92abc7cfa4282c276464cbd6193277db0abe18ea3da4d966720ed5f937f33a4d18d67618c0217ddd4bb56",
      "reveal_location_height": 880018,
      "reveal_location_index": 0,
      "reveal_location_script": "5120d3353ee13e2121b314f797afa5cb7b95143ce570afbd307f4767b285ffb1947e",
      "reveal_location_scripthash": "ae2bb1dbcbdac9161b782dcbc81ec3319e81f5d8b0c2946a6650382a1a0e070a",
      "reveal_location_tx_num": 1145635151,
      "reveal_location_txid": "30fa8c81bb2e80fabe03251a8a44b301e0f3c18be0ea5eb2971e9ec01cf9e7c1",
      "reveal_location_value": 546
    },
    "subtype": "realm",
    "type": "NFT"
  }
}

Get State

Get the latest state of an atomical.

Method

atomicalsGetState

Parameters

{
  atomicalAliasOrId: string | number
}

Example

Code

const atomicalAliasOrId =
  '555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0'
const result: ToResult<{ global: GlobalResult, result: AtomicalStatus }> =
  await api.atomicalsGetState({ params: { atomicalAliasOrId } })

Result

{
  "global": {
    "atomical_count": 226639,
    "atomicals_block_hashes": {
      "890684": "0b6876bf0a54d1b091a605f11fee65aeb67f86a550301008fe3ec37477878aad",
      "890685": "6256246a7349a2fb0a8412378ef311ac50400893e999c25aab8fd273cfb4f241",
      "890686": "66a720d1a9b99241197ed92803b12556613af4ce6f375061574507077101a1fb",
      "890687": "984989f83d48ece5e9b6224ade3130e14fbe93e04ecdc4d7d3ee46bd4d75b229",
      "890688": "b947db5073b0e38458fcf2d643067601b29f9795e4005ed473f3bd3e513fa3e7",
      "890689": "184cbb8edf7d65c011b1d0efeebea75ed7916d9f12836f720114608f5d62b755",
      "890690": "16f9dd7e02d48d0865544bad3ba6d2c0f8fd494cf86d2a20070fe9bd68521a35",
      "890691": "ad0def284725ba261a6908973468ce0883366f7c777ea4a2e3d419434a5f6bf4",
      "890692": "514b1ea930100ca88107a1342d747028f544e604467520c7d93317480716792f",
      "890693": "bb96a72e10e7b2eaa7701a4525eaa69dd125c4560e01a233bbc4e4c9854f0156"
    },
    "atomicals_block_tip": "bb96a72e10e7b2eaa7701a4525eaa69dd125c4560e01a233bbc4e4c9854f0156",
    "block_tip": "000000000000000000003d7949f5b58c24e98f48ba2bbd024d9c6de5b27fb635",
    "coin": "Bitcoin",
    "height": 890693,
    "network": "mainnet",
    "server_time": "2025-04-03T10:38:56.113539"
  },
  "result": {
    "$bitwork": {
      "bitworkc": "5557",
      "bitworkr": null
    },
    "$full_realm_name": "techtoshi",
    "$realm": "techtoshi",
    "$realm_candidates": [
      {
        "atomical_id": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0",
        "commit_height": 880018,
        "reveal_location_height": 880018,
        "tx_num": 1145635051,
        "txid": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203ae"
      }
    ],
    "$request_realm": "techtoshi",
    "$request_realm_status": {
      "note": "Successfully verified and claimed realm for current Atomical.",
      "status": "verified",
      "verified_atomical_id": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0"
    },
    "atomical_id": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0",
    "atomical_number": 226048,
    "atomical_ref": "anbgbqv29vmaqw24wr0bbjq1xg53rw3y5yt1cxrj8kw8dak20eq0i0",
    "confirmed": true,
    "location_counts": 1,
    "location_info": [
      {
        "atomicals_at_location": [
          "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0"
        ],
        "index": 0,
        "location": "30fa8c81bb2e80fabe03251a8a44b301e0f3c18be0ea5eb2971e9ec01cf9e7c1i0",
        "script": "5120d3353ee13e2121b314f797afa5cb7b95143ce570afbd307f4767b285ffb1947e",
        "scripthash": "ae2bb1dbcbdac9161b782dcbc81ec3319e81f5d8b0c2946a6650382a1a0e070a",
        "tx_num": 1145635151,
        "txid": "30fa8c81bb2e80fabe03251a8a44b301e0f3c18be0ea5eb2971e9ec01cf9e7c1",
        "value": 546
      }
    ],
    "location_info_obj": {
      "locations": [
        {
          "atomicals_at_location": [
            "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0"
          ],
          "index": 0,
          "location": "30fa8c81bb2e80fabe03251a8a44b301e0f3c18be0ea5eb2971e9ec01cf9e7c1i0",
          "script": "5120d3353ee13e2121b314f797afa5cb7b95143ce570afbd307f4767b285ffb1947e",
          "scripthash": "ae2bb1dbcbdac9161b782dcbc81ec3319e81f5d8b0c2946a6650382a1a0e070a",
          "tx_num": 1145635151,
          "txid": "30fa8c81bb2e80fabe03251a8a44b301e0f3c18be0ea5eb2971e9ec01cf9e7c1",
          "value": 546
        }
      ]
    },
    "mint_data": {
      "fields": {
        "args": {
          "bitworkc": "5557",
          "nonce": 8087572,
          "request_realm": "techtoshi",
          "time": 1737347293
        }
      }
    },
    "mint_info": {
      "$bitwork": {
        "bitworkc": "5557",
        "bitworkr": null
      },
      "$immutable": false,
      "$request_realm": "techtoshi",
      "args": {
        "bitworkc": "5557",
        "nonce": 8087572,
        "request_realm": "techtoshi",
        "time": 1737347293
      },
      "commit_height": 880018,
      "commit_index": 0,
      "commit_location": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0",
      "commit_tx_num": 1145635051,
      "commit_txid": "555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203ae",
      "ctx": {},
      "meta": {},
      "reveal_location": "30fa8c81bb2e80fabe03251a8a44b301e0f3c18be0ea5eb2971e9ec01cf9e7c1i0",
      "reveal_location_blockhash": "d919a5da3cf934b32bdad0beadd036a49d184f7039bb00000000000000000000",
      "reveal_location_header": "00e0c0251c98569aa0ae284c47575bb6f6d164abd163bf0be9d000000000000000000000b5d92abc7cfa4282c276464cbd6193277db0abe18ea3da4d966720ed5f937f33a4d18d67618c0217ddd4bb56",
      "reveal_location_height": 880018,
      "reveal_location_index": 0,
      "reveal_location_script": "5120d3353ee13e2121b314f797afa5cb7b95143ce570afbd307f4767b285ffb1947e",
      "reveal_location_scripthash": "ae2bb1dbcbdac9161b782dcbc81ec3319e81f5d8b0c2946a6650382a1a0e070a",
      "reveal_location_tx_num": 1145635151,
      "reveal_location_txid": "30fa8c81bb2e80fabe03251a8a44b301e0f3c18be0ea5eb2971e9ec01cf9e7c1",
      "reveal_location_value": 546
    },
    "state": {
      "latest": {}
    },
    "subtype": "realm",
    "type": "NFT"
  }
}

Get Ft Info

Get information of ARC-20 for the given atomical id.

Method

atomicalsGetFtInfo

Parameters

{
  atomicalAliasOrId: string | number
}

Example

Code

const atomicalAliasOrId =
  '56a8702bab3d2405eb9a356fd0725ca112a93a8efd1ecca06c6085e7278f0341i0'
const result: ToResult<{ global: GlobalResult, result: AtomicalStatus }> =
  await api.atomicalsGetFtInfo({ params: { atomicalAliasOrId } })

Result

Too long.

Get Realm Info

Get information of realm or subrealm.

Method

atomicalsGetRealmInfo

Parameters

{
  realmOrSubRealm: string
  verbose?: boolean
}

Example

Realm

Code

const realm = 'realmapp'
const result: ToResult<{ result: RealmInfo }> = await api.atomicalsGetRealmInfo(
  {
    params: { realmOrSubRealm: realm },
  }
)

Result

{
  "result": {
    "atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
    "candidates": [
      {
        "atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
        "commit_height": 874371,
        "reveal_location_height": 874371,
        "tx_num": 1130581592,
        "txid": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cc"
      }
    ],
    "found_full_realm_name": "realmapp",
    "missing_name_parts": null,
    "nearest_parent_realm_atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
    "nearest_parent_realm_name": "realmapp",
    "nearest_parent_realm_subrealm_mint_allowed": true,
    "nearest_parent_realm_subrealm_mint_rules": {
      "current_height": 890678,
      "current_height_rules": [
        {
          "bitworkc": "8888",
          "o": {
            "5120ac36f64dd51647bb55551dc379c4b18a65ecc71669639fdc46926c02c5a637d7": {
              "v": 50000
            }
          },
          "p": "^[a-z]{7,32}$"
        }
      ],
      "nearest_parent_realm_atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0"
    },
    "request_full_realm_name": "realmapp",
    "top_level_realm_atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
    "top_level_realm_name": "realmapp"
  }
}

SubRealm

Code

const subrealm = 'realmapp.techtoshi'
const result: ToResult<{ result: RealmInfo }> = await api.atomicalsGetRealmInfo(
  {
    params: { realmOrSubRealm: subrealm },
  }
)

Result

{
  "result": {
    "atomical_id": "7502826301679118cef4f3bab45bac1ea525e4867fda9375d202a22d31e36e14i0",
    "candidates": [
      {
        "atomical_id": "7502826301679118cef4f3bab45bac1ea525e4867fda9375d202a22d31e36e14i0",
        "commit_height": 881204,
        "reveal_location_height": 881204,
        "tx_num": 1148536603,
        "txid": "7502826301679118cef4f3bab45bac1ea525e4867fda9375d202a22d31e36e14"
      }
    ],
    "found_full_realm_name": "realmapp.techtoshi",
    "missing_name_parts": null,
    "nearest_parent_realm_atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
    "nearest_parent_realm_name": "realmapp",
    "nearest_parent_realm_subrealm_mint_allowed": true,
    "nearest_parent_realm_subrealm_mint_rules": {
      "current_height": 890678,
      "current_height_rules": [
        {
          "bitworkc": "8888",
          "o": {
            "5120ac36f64dd51647bb55551dc379c4b18a65ecc71669639fdc46926c02c5a637d7": {
              "v": 50000
            }
          },
          "p": "^[a-z]{7,32}$"
        }
      ],
      "nearest_parent_realm_atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0"
    },
    "request_full_realm_name": "realmapp.techtoshi",
    "top_level_realm_atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
    "top_level_realm_name": "realmapp"
  }
}

Get by Realm

Get atomical information for a given realm.

Method

atomicalsGetByRealm

Parameters

{
  realm: string
}

Example

Code

const realm = 'realmapp'
const result: ToResult<{ result: GetResult }> = await api.atomicalsGetByRealm({
  params: { realm },
})

Result

{
  "result": {
    "atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
    "candidate_atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
    "candidates": [
      {
        "atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
        "commit_height": 874371,
        "reveal_location_height": 874371,
        "tx_num": 1130581592,
        "txid": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cc"
      }
    ],
    "status": "verified",
    "type": "realm"
  }
}

Get by Ticker

Get atomical information for a given ticker.

Method

atomicalsGetByTicker

Parameters

{
  ticker: string
}

Example

Code

const result: ToResult<{ result: GetResult }> = await api.atomicalsGetByTicker({
  params: { ticker: 'atom' },
})

Result

{
  "result": {
    "atomical_id": "56a8702bab3d2405eb9a356fd0725ca112a93a8efd1ecca06c6085e7278f0341i0",
    "candidate_atomical_id": "56a8702bab3d2405eb9a356fd0725ca112a93a8efd1ecca06c6085e7278f0341i0",
    "candidates": [
      {
        "atomical_id": "56a8702bab3d2405eb9a356fd0725ca112a93a8efd1ecca06c6085e7278f0341i0",
        "commit_height": 808081,
        "reveal_location_height": 808081,
        "tx_num": 895769685,
        "txid": "56a8702bab3d2405eb9a356fd0725ca112a93a8efd1ecca06c6085e7278f0341"
      }
    ],
    "status": "verified",
    "type": "ticker"
  }
}

Find Realms

Find realms with the specified prefix.

Method

atomicalsFindRealms

Parameters

{
  realmPrefix?: string
  asc?: boolean
}

Example

Code

const realmPrefix = 'realmapp'
const asc = true
const result: ToResult<{ result: FindRealmItem[] }> =
  await api.atomicalsFindRealms({ params: { realmPrefix, asc } })

Result

{
  "result": [
    {
      "atomical_id": "7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0",
      "realm": "realmapp",
      "realm_hex": "7265616c6d617070",
      "status": "verified",
      "tx_num": 1130581592
    }
  ]
}

Find SubRealms

Find realms by parentRealmId and the specified subrealm prefix.

Method

atomicalsFindSubRealms

Parameters

{
  parentRealmId: string
  subrealmPrefix?: string
  asc?: boolean
}

Example

Code

const parentRealmId =
  '7788b52fb3da9d01d11918c0816aa7c62dafa2aca2f0c219d356ba71c29a31cci0'
const subrealmPrefix = 'tech'
const result: ToResult<{ result: FindSubrealmItem[] }> =
  await api.atomicalsFindSubRealms({
    params: { parentRealmId, subrealmPrefix },
  })

Result

// TODO: This method doesn't work properly

Get Holders

Return the holder for a given atomical id.

Method

atomicalsGetHolders

Parameters

{
  atomicalAliasOrId: string | number
}

Example

Code

const atomicalAliasOrId =
  '555705df624ee8abf044e600b5cae1ec0a3c707e2fb416771244f886aa6203aei0'
const result: ToResult<HolderItem[]> = await api.atomicalsGetHolders({
  params: { atomicalAliasOrId },
})

Result

[
  {
    "address": "bc1p6v6nacf7yysmx98hj7h6tjmmj52reets477nql68v7egtla3j3lqg9pf4z",
    "holding": 546
  }
]

Transaction

Get transaction detail.

Method

atomicalsTransaction

Parameters

{
  txid: string
}

Example

Code

const txid = '8a14f790e4bf959d1dc1ee638b73b89cba49b289c0f7996badd7ce5c75a0c46a'
const result: ToResult<AtomicalTxResponse> = await api.atomicalsTransaction({
  params: { txid },
})

Result

{
  "height": 881981,
  "info": {},
  "op": "transfer",
  "transfers": {
    "burned_fts": {},
    "inputs": {
      "1": [
        {
          "address": "bc1p5ejhxyjpycj4djyujk6qa0th4qymmtuputwa7qrpxrutdg6lvxyszmh5fk",
          "atomical_id": "1618c6541bdb51ba2777d2c48c0fbb8619e16b59be51f25828af74c3a05832f4i0",
          "index": 1,
          "type": "NFT",
          "value": 1000
        }
      ]
    },
    "is_burned": false,
    "is_cleanly_assigned": true,
    "outputs": {
      "0": [
        {
          "address": "bc1p6v6nacf7yysmx98hj7h6tjmmj52reets477nql68v7egtla3j3lqg9pf4z",
          "atomical_id": "1618c6541bdb51ba2777d2c48c0fbb8619e16b59be51f25828af74c3a05832f4i0",
          "index": 0,
          "type": "NFT",
          "value": 1000
        }
      ]
    }
  },
  "tx_num": 1150282162,
  "txid": "8a14f790e4bf959d1dc1ee638b73b89cba49b289c0f7996badd7ce5c75a0c46a"
}