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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.taal.com/core-products/whatsonchain/tokens/bsv-21-beta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.