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"
}