All pages
Powered by GitBook
1 of 1

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
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 WoC Telegram channel. Please provide as much detail on what you're trying to achieve as possible.