BSV-21 (Beta)

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

Here is a brief intro from the official documentation:

"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

Example Request

curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/1MMRcQnACaByFV6gYPoSzd9VPjemLeT57q/balance"

Example Response

{
   "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>.

Query Parameters

Parameter	Description
filterMempool (optional)	Options: both, mempool, mined (default).

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

Example Request

curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/1s2YXTRJce8k8VybXz4EmUnxC6jLyWPes/id/e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0/depth"

Example Response

{
   "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 (optional)	Skip items. For pagination.
limit (optional)	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>

Example Request

curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/id/942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba_0"

Example Response

{
    "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 (optional)	Skip items. For pagination.
limit (optional)	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>

Example Request

curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/outpoint/6dc1a50dd6f18f5c55d60fa8532043e19cd91e9d2d9fbceee8166868e0263e65_1"

Example Response

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

Example Request

curl --location --request GET "1s2YXTRJce8k8VybXz4EmUnxC6jLyWPes/id/e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0/history?skip=3&limit=2"

Example Response

{
   "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 (optional)	Skip items. For pagination.
limit (optional)	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

Example Request

curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/txid/22d79dd02b1b1c85b1119f800b5626b7f12645599098e2557b79ecb551e02b2a/spent"

Example Response

{
   "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 ID.

Query Parameters

Parameter	Description
skip (optional)	Skip items. For pagination.
limit (optional)	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>

Example Request

curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/txid/942fa8659a65cbcfaf979c4abef28a8f9c1454836cc3a9b42662f2bf784d92ba"

Example Response

{
    "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 (optional)	Skip items. For pagination.
limit (optional)	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

Example Request

curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/14h6iBhUj2SBDtMkSiGxed9SyaWpFwCw4j/unspent"

Example Response

{
    "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 (optional)	Skip items. For pagination.
limit (optional)	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

Example Request

curl --location --request GET "https://api.whatsonchain.com/v1/bsv/main/token/bsv21/id/cc7a38cfd087b9411b8533e6c5d30590a9e50ea9adc5ca3e3d947bb201a15ebd_0/owners"

Example Response

{
    "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 (optional)	Skip items. For pagination.
limit (optional)	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 WoC Telegram channel. Please provide as much detail on what you're trying to achieve as possible.