> For the complete documentation index, see [llms.txt](https://docs.taal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taal.com/core-products/whatsonchain/tokens/bsv-21-beta.md).

# BSV-21 (Beta)

{% hint style="info" %}
BSV-21 protocol was originally called BSV-20 v2 but was renamed for clarity.
{% endhint %}

Here is a brief intro from the [official documentation](https://docs.1satordinals.com/fungible-tokens/bsv-21):

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

{% code title="HTTP Request" %}

```
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/<address>/balance
```

{% endcode %}

{% code title="Example Request" %}

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

{% endcode %}

{% code title="Example Response" %}

```json
{
   "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
}
```

{% endcode %}

**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.

{% code title="HTTP Request" %}

```
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/<address>/id/<id>/depth
```

{% endcode %}

{% code title="Example Request" %}

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

{% endcode %}

{% code title="Example Response" %}

```json
{
   "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
}
```

{% endcode %}

**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.

{% code title="HTTP Request" %}

```
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/id/<id>
```

{% endcode %}

{% code title="Example Request" %}

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

{% endcode %}

{% code title="Example Response" %}

```json
{
    "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
        }
    }
}
```

{% endcode %}

**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.

{% code title="HTTP Request" %}

```
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/outpoint/<outpoint>
```

{% endcode %}

{% code title="Example Request" %}

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

{% endcode %}

{% code title="Example Response" %}

```json
{
   "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
      }
   }
}
```

{% endcode %}

**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.

{% code title="HTTP Request" %}

```
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/<address>/id/<id>
```

{% endcode %}

{% code title="Example Request" %}

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

{% endcode %}

{% code title="Example Response" %}

```json
{
   "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
}
```

{% endcode %}

**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.

{% code title="HTTP Request" %}

```
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/txid/<txid>/spent
```

{% endcode %}

{% code title="Example Request" %}

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

{% endcode %}

{% code title="Example Response" %}

```json
{
   "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
}
```

{% endcode %}

**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.

{% code title="HTTP Request" %}

```
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/txid/<txid>
```

{% endcode %}

{% code title="Example Request" %}

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

{% endcode %}

{% code title="Example Response" %}

```json
{
    "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
}
```

{% endcode %}

**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.

{% code title="HTTP Request" %}

```
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/<address>/unspent
```

{% endcode %}

{% code title="Example Request" %}

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

{% endcode %}

{% code title="Example Response" %}

```json
{
    "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
}
```

{% endcode %}

**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.

{% code title="HTTP Request" %}

```
GET https://api.whatsonchain.com/v1/bsv/<network>/token/bsv21/id/<id>/owners
```

{% endcode %}

{% code title="Example Request" %}

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

{% endcode %}

{% code title="Example Response" %}

```json
{
    "owners": [
        {
            "address": "1JwtQdKJM9GrARS5X9cNaGadqbNSfzSKwF"
        },
        {
            "address": "1Gi1ahKC1Ybbi85RTMsyuifxHS754nd6Ni"
        },
        {
            "address": "1G6CB3Ch4zFkPmuhZzEyChQmrQPfi86qk3"
        }
    ],
    "total_count": 3
}
```

{% endcode %}

**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](http://t.me/+SNmGhFqKVB9kf%E2%80%A6). Please provide as much detail on what you're trying to achieve as possible.