TSB-P Token Scanner Documentation

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:

TypeCode	Meaning
0	Fungible Token (FT)
1	Non-Fungible Token (NFT)
2	Proof-of-Existence Token (PoE)
3	Smart Contract Trigger Token
4	Oracle-Verified Token
5	Compliance-Bound Token (KYC/AML)
6	Vesting Token (timelocked tokens)
7	Multi-Sig Restricted Token
8	DAO Governance Token
9	Fee Payment Token (for protocol usage)
10	Wrapped Asset Token (cross-chain)
11	Cross-Chain Bridge Token
12	Royalty Token (revenue shares)
13	Subscription Access Token
14	Identity Token (KYC / verifiable claims)
15	Treasury Reserve Token (DAO reserve)

Note: If a token's typeCode is not assigned (outside 0-15), it will be displayed as "Unknown Type (XX)".

API Endpoints

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: /api/tokens

GET /api/token/:txid

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

Parameters:

• txid: Transaction ID containing the token witness

Example: /api/token/4fef74...ccc59

GET /api/status

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

Example: /api/status