Documentation

Learn about the TSB-P protocol and how to use the Token Scanner API

Overview

The TSB-P Token Scanner is a tool for discovering and exploring programmable Bitcoin tokens embedded directly within Taproot script paths. These tokens follow the TSB-P protocol, enabling fully Bitcoin-native tokens with metadata, timestamps, and programmable attributes.

Token Format

TSB-P tokens are encoded inside the witness data of Bitcoin transactions via a Taproot script path. The encoding follows this programmable format: 

OP_TRUE
OP_IF
  03 "TSB"                      # TSB marker (3 bytes)
  10 [token ID]                 # Token ID (16 bytes)
  08 [amount]                   # Amount (8 bytes, big endian)
  01 [typeCode]                 # Type Code (1 byte)
  OP_DROP
  OP_DROP
  OP_DROP
  OP_DROP
  [metadata]                    # Metadata (variable length)
  08 [timestamp]                # Timestamp (8 bytes, big endian)
  OP_DROP
  OP_DROP
  OP_TRUE
OP_ENDIF

Field Descriptions

  • TSB: Marker to identify token scripts
  • Token ID: Unique 16-byte identifier (padded with zeros if shorter)
  • Amount: 8-byte unsigned integer representing the token supply
  • TypeCode: 1-byte integer specifying the token type (see below)
  • Metadata: Arbitrary user-defined metadata (string)
  • Timestamp: 8-byte UNIX timestamp (creation time)

Token Type Codes

Each token has a typeCode indicating its purpose:

Code Type Description
0Fungible Token (FT)Standard fungible tokens like currencies
1Non-Fungible Token (NFT)Unique digital assets
2Proof-of-Existence (PoE)Document/data timestamping
3Smart Contract TriggerTriggers off-chain smart contracts
4Oracle-VerifiedTokens with oracle attestation
5Compliance-BoundKYC/AML compliant tokens
6Vesting TokenTime-locked token releases
7Multi-Sig RestrictedRequires multi-signature approval
8DAO GovernanceVoting and governance rights
9Fee PaymentProtocol fee payment tokens
10Wrapped AssetCross-chain wrapped assets
11Cross-Chain BridgeBridge transfer tokens
12Royalty TokenRevenue share tokens
13Subscription AccessAccess control tokens
14Identity TokenKYC/verifiable claims
15Treasury ReserveDAO treasury tokens

Note: If a token's typeCode is outside the 0-15 range, it will be displayed as "Unknown Type".

API Reference

GET /api/tokens

Returns a list of all TSB-P tokens found in the blockchain.

Query Parameters:

  • refresh=true - Force a full re-scan of the blockchain (ignores cache)

Example:

GET /api/tokens
GET /api/tokens?refresh=true

Try it

GET /api/token/:txid

Returns detailed information about a specific token by its transaction ID.

Parameters:

  • txid - Transaction ID containing the token witness

Example:

GET /api/token/4fef74...ccc59

GET /api/status

Returns status and connection information about the Bitcoin node used by the scanner.

Example:

GET /api/status

Try it