Public docs
WebsiteTAAL PlatformWhatsOnChain
  • Welcome
  • Introduction
    • Get an API Key
  • Core Products
    • WhatsOnChain
      • Health
      • Chain Info
      • Block
      • Transaction
      • Mempool
      • (Un)Spent Transaction Outputs
      • Address
      • Script
      • Exchange Rate
      • Search
      • WoC Widgets
      • WoC Plugins
      • On-Chain Data
      • Output Tags
      • Stats
      • WebSockets
        • WoC Sockets V1 (Deprecated)
        • WoC Sockets V2 (Beta)
      • Tokens
        • 1Sat Ordinals (Beta)
        • BSV-21 (Beta)
        • STAS Tokens (Beta)
      • Change Log
      • Community Libraries
    • Transaction Processing
      • ARC Endpoints
      • Transaction format and fee rate
    • TAAL Wallet
      • Introduction
      • Architecture
      • Terminology
      • UI Elements
      • Tutorial
    • 1Sat Ordinals tokens API
      • Introduction
      • Terminology
      • Flow Diagram
      • Basic Tutorial - Node
      • Basic Tutorial - Postman
      • API
  • Resources
    • FAQ
    • Support
    • Glossary
    • Acronyms and Abbreviations
Powered by GitBook
On this page
  • Get Address Balance
  • Get a Depth
  • Get a Token
  • Get a Transfer
  • Get History by Address
  • Get Spent Outputs
  • Get Tokens by Transaction ID
  • Get Unspent Tokens by Address
  • Get Token Owners
  • Need an additional API endpoint?

Was this helpful?

Export as PDF
  1. Core Products
  2. WhatsOnChain
  3. Tokens

BSV-21 (Beta)

Previous1Sat Ordinals (Beta)NextSTAS Tokens (Beta)

Last updated 1 month ago

Was this helpful?

BSV-21 protocol was originally called BSV-20 v2 but was renamed for clarity.

Here is a brief intro from the :

"This iteration of the BSV-20 protocol introduces a new tickerless mode functionality. Tickerless mode forgoes the first is first nature of BRC20-BTC, and allows the capabilities to have a smart contract, or an administrator, control distribution. Additionally, every transaction of a tickerless mode token forms part of a single on-chain DAG (Directed Acyclic Graph), such that the transaction can easily be tracked back to that token's genesis mint. "

Get Address Balance

This endpoint retrieves the amount of tokens that were not spent.

HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/<address>/balance
cURL
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/1MMRcQnACaByFV6gYPoSzd9VPjemLeT57q/balance"
Response JSON example
{
   "tokens":[
      {
         "outpoint":"7ea4f03a1e3b9e2c0509a3bc523814e911d0306048ee73c435ba05b50d0d18a8_0",
         "amount":"200",
         "decimals":2,
         "symbol":"YWT33"
      },
      {
         "outpoint":"c5bea9ef8bd1bd9de47cef5179bee557c8e7ae5ed303338b925088c6cae3f4e2_1",
         "amount":"10",
         "decimals":1,
         "symbol":"smtfg1",
         "icon":"c5bea9ef8bd1bd9de47cef5179bee557c8e7ae5ed303338b925088c6cae3f4e2_0"
      }
   ],
   "total_count":2
}

URL Parameters

Parameter
Description

network

The selected network: main or test.

id

Token identifier - <txid>_<vout>.

Get a Depth

This endpoint retrieves transfers inscribed by the provided address and where they are spent.

HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/<address>/id/<id>/depth
cURL
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/1s2YXTRJce8k8VybXz4EmUnxC6jLyWPes/id/e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0/depth"
Response JSON example
{
   "branches":[
      {
         "txid":"02c7c1a574766b6755217df1d51219797ad9e68986669c761fe00210b3075898",
         "txIndex":405,
         "blockHeight":857818,
         "spent":{
            "outpoint":"a652c3d01b73d417d785c299cb397540de0474146c6e978fd20db31941157fcf_1",
            "txIndex":388,
            "blockHeight":861969
         }
      },
      {
         "txid":"22d79dd02b1b1c85b1119f800b5626b7f12645599098e2557b79ecb551e02b2a",
         "txIndex":444,
         "blockHeight":861969,
         "spent":{
            "outpoint":"f9ec4e4aee1bec1255108424a1c5b595151a35b1302be00ddb2d1c1503e010e7_1",
            "txIndex":422,
            "blockHeight":863272
         }
      }
   ],
   "total_count":2
}

URL Parameters

Parameter
Description

network

The selected network: main or test.

address

Address.

Query Parameters

Parameter
Description

skip

Skip items. For pagination.

limit

Limit number of items. For pagination.

Get a Token

This endpoint retrieves the token details given the token's identifier.

HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/id/<id>
cURL
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/id/942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba_0"
Response JSON example
{
    "token": {
        "outpoint": "942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba_0",
        "scriptHash": "96e31317c9059acb339ee65be792de959b4aee32ee79d9bddfd4f7689091ae73",
        "funderAddress": "1MxwReRMY53Y1G4rQN53w8DFZRYHTpHfYm",
        "data": {
            "bsv20": {
                "amt": 21000000,
                "icon": "ecb483eda58f26da1b1f8f15b782b1186abdf9c6399a1c3e63e0d429d5092a41_0",
                "id": "942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba_0",
                "op": "deploy+mint",
                "protocol": "bsv-20",
                "symbol": "27ff2993c1e873e286a8a6fcfd5639ccaed466467f5907d737f5f051eb11b520"
            },
            "insc": {
                "file": {
                    "hash": "ZczVOfCd+PT0n7DbU2zSPH3gW31gkM4p8iN1bWUH7hU=",
                    "size": 199,
                    "type": "application/bsv-20"
                },
                "json": {
                    "amt": "21000000",
                    "icon": "ecb483eda58f26da1b1f8f15b782b1186abdf9c6399a1c3e63e0d429d5092a41_0",
                    "op": "deploy+mint",
                    "p": "bsv-20",
                    "sym": "27ff2993c1e873e286a8a6fcfd5639ccaed466467f5907d737f5f051eb11b520"
                }
            },
            "types": [
                "json"
            ]
        },
        "current": {
            "txid": "942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba",
            "txIndex": 69616,
            "blockHeight": 880067,
            "blockTime": 1737168515
        }
    }
}

URL Parameters

Parameter
Description

network

The selected network: main or test.

address

Address.

id

Token identifier - <txid>_<vout>.

Query Parameters

Parameter
Description

skip

Skip items. For pagination.

limit

Limit number of items. For pagination.

Get a Transfer

This endpoint retrieves the token's transfer details given the inscription's outpoint.

HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/outpoint/<outpoint>
cURL
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/outpoint/6dc1a50dd6f18f5c55d60fa8532043e19cd91e9d2d9fbceee8166868e0263e65_1"
Response JSON example
{
   "inscription":{
      "vout":1,
      "scriptHash":"7df2cabb01151773b2484da0752ead2e86f0b0604b67d562b3cbec780af6b179",
      "ownerAddress":"1Pp4sGru37gAfpbyLME6rVjamyJ9nd2ym",
      "data":{
         "bsv20":{
            "amt":1000,
            "id":"459f0e8bb038d55e3f732f11cc80af75c86b8f48dd17eac2bf92ebe9ac3a040c_0",
            "op":"transfer",
            "protocol":"bsv-20"
         },
         "insc":{
            "file":{
               "hash":"c6cYm2ltooXmDRSL6HOBF7gfuvgs5QEG5MXu4H4smbE=",
               "size":117,
               "type":"application/bsv-20"
            },
            "json":{
               "amt":"1000",
               "id":"459f0e8bb038d55e3f732f11cc80af75c86b8f48dd17eac2bf92ebe9ac3a040c_0",
               "op":"transfer",
               "p":"bsv-20"
            }
         },
         "types":[
            "json"
         ]
      },
      "current":{
         "txid":"6dc1a50dd6f18f5c55d60fa8532043e19cd91e9d2d9fbceee8166868e0263e65",
         "txIndex":40,
         "blockHeight":841255,
         "blockTime":1713795871
      }
   }
}

URL Parameters

Parameter
Description

network

The selected network: main or test.

outpoint

Outpoint - <txid>_<vout>.

Get History by Address

This endpoint retrieves transfers history given the address and token's identifier.

HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/<address>/id/<id>
cURL
curl --location --request GET "1s2YXTRJce8k8VybXz4EmUnxC6jLyWPes/id/e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0/history?skip=3&limit=2"
Response JSON example

{
   "inscriptions":[
      {
         "vout":0,
         "scriptHash":"1629429acdd3c8cd72738b292caa616830ef82546fc9a0f8ad742e8c32caddfb",
         "ownerAddress":"1s2YXTRJce8k8VybXz4EmUnxC6jLyWPes",
         "data":{
            "bsv20":{
               "amt":22222200000000,
               "id":"e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0",
               "op":"transfer",
               "protocol":"bsv-20"
            },
            "insc":{
               "file":{
                  "hash":"xM/dPLDlGFvpp/7113yjkqI/HkaaJjG8Cv3QznokKEo=",
                  "size":127,
                  "type":"application/bsv-20"
               },
               "json":{
                  "amt":"22222200000000",
                  "id":"e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0",
                  "op":"transfer",
                  "p":"bsv-20"
               }
            },
            "types":[
               "json"
            ]
         },
         "current":{
            "txid":"22d79dd02b1b1c85b1119f800b5626b7f12645599098e2557b79ecb551e02b2a",
            "txIndex":444,
            "blockHeight":861969,
            "blockTime":1726254528
         }
      },
      {
         "vout":1,
         "scriptHash":"d931f30431274374fb8a0ee69cb0cfdb59555404089bf6a2d4627bc73adba192",
         "ownerAddress":"1s2YXTRJce8k8VybXz4EmUnxC6jLyWPes",
         "data":{
            "bsv20":{
               "amt":46666700000000,
               "id":"e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0",
               "op":"transfer",
               "protocol":"bsv-20"
            },
            "insc":{
               "file":{
                  "hash":"XK86+/JWmnz2rU3IdgYUMg519oFtWA5pk3T2BkNP1rY=",
                  "size":127,
                  "type":"application/bsv-20"
               },
               "json":{
                  "amt":"46666700000000",
                  "id":"e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0",
                  "op":"transfer",
                  "p":"bsv-20"
               }
            },
            "types":[
               "json"
            ]
         },
         "current":{
            "txid":"22d79dd02b1b1c85b1119f800b5626b7f12645599098e2557b79ecb551e02b2a",
            "txIndex":444,
            "blockHeight":861969,
            "blockTime":1726254528
         }
      }
   ],
   "total_count":2
}

URL Parameters

Parameter
Description

network

The selected network: main or test.

address

Address.

id

Token identifier - <txid>_<vout>.

Query Parameters

Parameter
Description

skip

Skip items. For pagination.

limit

Limit number of items. For pagination.

Get Spent Outputs

This endpoint retrieves spent inscriptions given the transaction's identifier.

HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/txid/<txid>/spent
cURL
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/txid/22d79dd02b1b1c85b1119f800b5626b7f12645599098e2557b79ecb551e02b2a/spent"
Response JSON example
{
   "inscriptions":[
      {
         "vout":0,
         "scriptHash":"7bc83b8837be332181e7d8f098c3f9bcbf34a1fd8acb3a4e0114f261f014b955",
         "ownerAddress":"1s2YXTRJce8k8VybXz4EmUnxC6jLyWPes",
         "spentTxid":"22d79dd02b1b1c85b1119f800b5626b7f12645599098e2557b79ecb551e02b2a",
         "data":{
            "bsv20":{
               "amt":10000000000000,
               "id":"e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0",
               "op":"transfer",
               "protocol":"bsv-20"
            },
            "insc":{
               "file":{
                  "hash":"YtnAMmnJcV0qk50dbdAUxGWz/QUkM+zl51OpLPWhoK0=",
                  "size":127,
                  "type":"application/bsv-20"
               },
               "json":{
                  "amt":"10000000000000",
                  "id":"e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0",
                  "op":"transfer",
                  "p":"bsv-20"
               }
            },
            "types":[
               "json"
            ]
         },
         "current":{
            "txid":"38f8a1e8d2953323cd3cace35341aaaffb46b0366c2d5eb1881ca0ec565a3867",
            "txIndex":403,
            "blockHeight":861969,
            "blockTime":1726254528
         }
      }
   ],
   "total_count":1
}

URL Parameters

Parameter
Description

network

The selected network: main or test.

txid

Transaction identifier.

Query Parameters

Parameter
Description

skip

Skip items. For pagination.

limit

Limit number of items. For pagination.

Get Tokens by Transaction ID

This endpoint retrieves tokens that a given transaction contains.

HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/txid/<txid>
cURL
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/txid/942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba"
Response JSON example
{
    "tokens": [
        {
            "outpoint": "942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba_0",
            "scriptHash": "96e31317c9059acb339ee65be792de959b4aee32ee79d9bddfd4f7689091ae73",
            "funderAddress": "1MxwReRMY53Y1G4rQN53w8DFZRYHTpHfYm",
            "data": {
                "bsv20": {
                    "amt": 21000000,
                    "icon": "ecb483eda58f26da1b1f8f15b782b1186abdf9c6399a1c3e63e0d429d5092a41_0",
                    "id": "942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba_0",
                    "op": "deploy+mint",
                    "protocol": "bsv-20",
                    "symbol": "27ff2993c1e873e286a8a6fcfd5639ccaed466467f5907d737f5f051eb11b520"
                },
                "insc": {
                    "file": {
                        "hash": "ZczVOfCd+PT0n7DbU2zSPH3gW31gkM4p8iN1bWUH7hU=",
                        "size": 199,
                        "type": "application/bsv-20"
                    },
                    "json": {
                        "amt": "21000000",
                        "icon": "ecb483eda58f26da1b1f8f15b782b1186abdf9c6399a1c3e63e0d429d5092a41_0",
                        "op": "deploy+mint",
                        "p": "bsv-20",
                        "sym": "27ff2993c1e873e286a8a6fcfd5639ccaed466467f5907d737f5f051eb11b520"
                    }
                },
                "types": [
                    "json"
                ]
            },
            "current": {
                "txid": "942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba",
                "txIndex": 69616,
                "blockHeight": 880067,
                "blockTime": 1737168515
            }
        }
    ],
    "total_count": 1
}

URL Parameters

Parameter
Description

network

The selected network: main or test.

txid

Transaction ID.

Query Parameters

Parameter
Description

skip

Skip items. For pagination.

limit

Limit number of items. For pagination.

Get Unspent Tokens by Address

This endpoint retrieves unspent BSV-21 inscriptions given an address.

HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/<address>/unspent
cURL
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/14h6iBhUj2SBDtMkSiGxed9SyaWpFwCw4j/unspent"
Response JSON structure
{
    "tokens": [
        {
            "scriptHash": "d5b8124a3cec0843ced890272b64c745fc1a311a9d9dc1453ba6d77c4a519305",
            "data": {
                "bsv20": {
                    "amt": 999000,
                    "id": "459f0e8bb038d55e3f732f11cc80af75c86b8f48dd17eac2bf92ebe9ac3a040c_0",
                    "op": "transfer",
                    "protocol": "bsv-20"
                },
                "insc": {
                    "file": {
                        "hash": "eXPedD7bUNMRNMu7a5zFX9GSMn1nyOwbI/5+Sa8CA4Y=",
                        "size": 119,
                        "type": "application/bsv-20"
                    },
                    "json": {
                        "amt": "999000",
                        "id": "459f0e8bb038d55e3f732f11cc80af75c86b8f48dd17eac2bf92ebe9ac3a040c_0",
                        "op": "transfer",
                        "p": "bsv-20"
                    }
                },
                "types": [
                    "json"
                ]
            },
            "current": {
                "txid": "6dc1a50dd6f18f5c55d60fa8532043e19cd91e9d2d9fbceee8166868e0263e65",
                "txIndex": 40,
                "blockHeight": 841255,
                "blockTime": 1713795871
            }
        }
    ],
    "total_count": 1
}

URL Parameters

Parameter
Description

network

The selected network: main or test.

address

Address.

Query Parameters

Parameter
Description

skip

Skip items. For pagination.

limit

Limit number of items. For pagination.

Get Token Owners

This endpoint retrieves addresses that own a token or transfer(s) of the inscription.

HTTP Request
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/id/<id>/owners
cURL
curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/id/cc7a38cfd087b9411b8533e6c5d30590a9e50ea9adc5ca3e3d947bb201a15ebd_0/owners"
Response JSON structure
{
    "owners": [
        {
            "address": "1JwtQdKJM9GrARS5X9cNaGadqbNSfzSKwF"
        },
        {
            "address": "1Gi1ahKC1Ybbi85RTMsyuifxHS754nd6Ni"
        },
        {
            "address": "1G6CB3Ch4zFkPmuhZzEyChQmrQPfi86qk3"
        }
    ],
    "total_count": 3
}

URL Parameters

Parameter
Description

network

The selected network: main or test.

id

Token identifier - <txid>_<vout>.

Query Parameters

Parameter
Description

skip

Skip items. For pagination.

limit

Limit number of items. For pagination.

Need an additional API endpoint?

If you want to make a request for an additional API endpoint that would help with your use case, please reach out to us using our . Please provide as much detail on what you're trying to achieve as possible.

official documentation
WoC Telegram channel