← Back to IDE
📖 What is BTC-TKP?
BTC-TKP (Bitcoin Telephone Keypad), the FatCat Protocol, is a minimalist, stack-based
programming language designed specifically for Bitcoin transaction signing on devices with only 12 buttons—the
standard telephone keypad layout (0-9, *, #).
This language enables Bitcoin operations on extremely constrained hardware: signing devices, vending machines,
ATMs, door locks, and any embedded system with a telephone keypad. It's a complete Bitcoin transaction language
that fits on 12 buttons.
Open Source Project: BTC-TKP is open source software, designed to be freely used, studied,
modified, and distributed by anyone building Bitcoin-enabled hardware devices.
🎯 Design Philosophy
The 12-button constraint isn't a limitation—it's a feature:
- Universal Hardware Compatibility: Works with any device that has a telephone keypad
- Air-Gapped Security: Perfect for offline signing devices with minimal attack surface
- Embedded Systems: Ideal for vending machines, ATMs, and IoT devices
- Low Cost: No expensive touchscreens or complex input devices required
- Intuitive: Everyone knows how to use a telephone keypad
⌨️ The 12-Button Telephone Keypad
Standard telephone keypad layout used in BTC-TKP
🏗️ Stack-Based Execution Model
BTC-TKP uses a stack-based virtual machine similar to Bitcoin Script, Forth, and other stack languages.
All data operations work with a Last-In-First-Out (LIFO) stack.
How the Stack Works
Think of the stack like a stack of plates:
- You can only add (push) plates to the top
- You can only remove (pop) plates from the top
- The last plate added is the first one removed
Example: Stack Operations
100* → Stack: [100] (push 100)
20* → Stack: [100, 20] (push 20)
*1 → Peek: 20 (look at top, don't remove)
*2 → Stack: [20, 100] (swap top two items)
📝 Complete Command Reference
Digit Keys (0-9)
Digit keys build numbers in the input buffer. You can type multiple digits to create larger numbers.
1 → Buffer: "1"
2 → Buffer: "12"
3 → Buffer: "123"
4 → Buffer: "1234"
* → Push 1234 to stack
* (Star/Asterisk) - Push & Stack Operations
The * key handles data stack operations:
| Command |
Name |
Description |
Example |
| * |
Push |
Push input buffer to stack (if buffer has data) |
100* pushes 100 onto stack |
| *1 |
Peek |
View top item without removing it |
*1 shows what's on top |
| *2 |
Swap |
Swap the top two stack items |
*2 swaps positions |
# (Hash/Pound) - Bitcoin Commands
The # key initiates Bitcoin transaction operations:
| Command |
Name |
M-Alias |
Description |
| #0 |
Clear Stack |
M0 (Mode 0) |
Remove all items from stack |
| #1 |
Scan Address |
- |
Scan recipient Bitcoin address (QR code or input) |
| #2 |
Set Fee |
- |
Pop stack top and set as fee rate (sat/vB) |
| #3 |
Sign |
- |
Sign the transaction with private key |
| #4 |
Broadcast |
- |
Broadcast signed transaction to Bitcoin network |
| #5 |
Get Balance |
M5 (Memory 5) |
Push wallet balance to stack (in satoshis) |
M-Alias System
Some commands have dual purposes and are called "M-aliases" (Mode/Memory aliases):
- #0 = C0 (Command 0) or M0 (Mode 0) - Clear/Reset
- #5 = C5 (Command 5) or M5 (Memory 5) - Balance/Memory
This dual naming helps users remember commands: "M0 to clear Mode" or "M5 to check Memory (balance)".
💡 Complete Transaction Examples
Example 1: Simple Bitcoin Send
Send 1000 sats with 20 sat/vB fee:
#5 Check balance first (M5)
1000* Push 1000 (amount in satoshis)
20* Push 20 (fee rate in sat/vB)
#2 Set fee from stack
#1 Scan recipient address
#3 Sign transaction
#4 Broadcast transaction
Full one-liner: #51000*20*#2#1#3#4
Example 2: Using Stack Operations
Prepare amounts, swap them, then send:
5000* Push 5000
10* Push 10
*1 Peek at top (shows 10)
*2 Swap (now: 10, 5000)
#2 Set fee to 10
#1 Scan address
#3 Sign (send 5000 sats)
#4 Broadcast
Example 3: Multiple Checks
Check balance multiple times during transaction setup:
#5 Check balance
*1 Peek at balance
2000* Push amount
#5 Check balance again
*1 Peek at new balance
15* Push fee
#2 Set fee
#1 Scan address
#3 Sign
#4 Broadcast
🔄 Dual Notation Support
BTC-TKP supports both TKP notation (*/# keys) and legacy notation (P/C keys)
for backward compatibility and keyboard convenience:
| TKP Notation (Primary) |
Legacy Notation |
Function |
| * |
P |
Push / Stack operations |
| # |
C |
Command / Bitcoin operations |
You can type either notation—they work identically:
100*#5 ← Telephone keypad notation
100P#5 ← Also works (P maps to *)
100*C5 ← Also works (C maps to #)
100PC5 ← Also works (legacy notation)
🧪 TEST Mode vs LIVE Mode
TEST Mode (Default) ✅
Safe sandbox environment for learning and development:
- Mock wallet with 5,000,000 test sats
- Simulated address scanning
- Fake transaction signing
- No real Bitcoin is sent
- Perfect for practicing and debugging
- Status: Fully functional and ready to use
LIVE Mode 🔧
Framework for real Bitcoin operations:
- VM fully supports LIVE mode commands
- Complete protocol implementation ready
- Requires backend API endpoint for real Bitcoin transactions
- See INTEGRATION.md in the repository for complete API specification
- Developers can implement their own backends
- ⚠️ WARNING: When connected, real Bitcoin will be sent!
Implementation Status:
The BTC-TKP virtual machine and protocol fully support both TEST and LIVE modes. LIVE mode requires
a backend API service (such as fatcatide.com or your own implementation) to handle real Bitcoin
operations. The VM architecture is complete and ready to connect to any compatible backend that
implements the specification in INTEGRATION.md.
This enables the open source community to build their own backend implementations while using the
same BTC-TKP language and IDE frontend.
🛠️ Hardware Applications
BTC-TKP is designed for these use cases:
Hardware Signing Devices
Build air-gapped Bitcoin wallets using simple keypads. No touchscreen required—just 12 buttons
and minimal display.
Vending Machines
Accept Bitcoin payments on vending machines. Customer enters amount on telephone keypad, scans their
address, and the machine creates the transaction.
ATM-Style Terminals
Bitcoin ATMs with telephone keypad interface. Simple, familiar input method that everyone understands.
Door Locks & Access Control
Bitcoin-enabled door locks where users pay to unlock using the telephone keypad interface.
Embedded Systems
Any IoT device or embedded system with a 12-button keypad can now handle Bitcoin transactions.
📱 Hardware Implementation Example
Here's how a BTC-TKP transaction would appear on an embedded device with a small OLED display
and 12-button telephone keypad:
Device Startup
┌──────────────────┐
│ BTC-TKP v1.0 │
│ Wallet Ready │
│ │
│ Balance: │
│ 5,000,000 sats │
│ │
│ Press # for menu │
└──────────────────┘
Step 1: Check Balance (Press #5)
[User Presses: # then 5]
┌──────────────────┐
│ Fetching... │
│ ████████░░ 80% │
└──────────────────┘
[Then Updates to:]
┌──────────────────┐
│ ✓ Balance │
│ 5,000,000 sats │
│ │
│ Stack: [5000000] │
│ │
│ Ready >_ │
└──────────────────┘
Step 2: Enter Amount (1000*)
[User types: 1 0 0 0 *]
┌──────────────────┐
│ Input: 1000 │
│ Press * to push │
└──────────────────┘
[Display updates:]
┌──────────────────┐
│ ✓ Pushed 1,000 │
│ Stack: [1000] │
└──────────────────┘
Step 3: Set Fee (20* then #2)
[User types: 2 0 *]
┌──────────────────┐
│ ✓ Pushed 20 │
│ Stack: [1000,20] │
└──────────────────┘
[User presses: # 2 (set fee)]
┌──────────────────┐
│ ✓ Fee: 20 sat/vB │
│ Stack: [1000] │
└──────────────────┘
Step 4: Scan Recipient (#1)
[User presses: # 1 (scan address)]
┌──────────────────┐
│ SCAN ADDRESS │
│ │
│ Show QR code or │
│ type address via │
│ USB/companion app│
└──────────────────┘
[After scanning bc1q...]
┌──────────────────┐
│ Recipient: │
│ bc1q...vx7e │
│ │
│ Amount: 1,000 │
│ Fee: 20 sat/vB │
│ │
│ Press #3 to sign │
└──────────────────┘
Step 5: Sign Transaction (#3)
[User presses: # 3 (sign)]
┌──────────────────┐
│ ⚠ CONFIRM │
│ Send 1,000 sats? │
│ │
│ 1 = Yes │
│ 0 = Cancel │
└──────────────────┘
[User presses: 1 (confirm)]
┌──────────────────┐
│ Signing... │
│ [████████] │
└──────────────────┘
[Then shows:]
┌──────────────────┐
│ ✓ Signed! │
│ TXID: a1b2... │
│ │
│ Press #4 to │
│ broadcast │
└──────────────────┘
Step 6: Broadcast (#4)
[User presses: # 4 (broadcast)]
┌──────────────────┐
│ Broadcasting... │
│ [████████] │
└──────────────────┘
[Success!]
┌──────────────────┐
│ ✓ SENT! │
│ TXID: a1b2c3d4 │
│ │
│ New Balance: │
│ 4,998,560 sats │
└──────────────────┘
Complete Transaction: #51000*20*#2#1#3#4
This entire transaction flow demonstrates how BTC-TKP works on credit-card-sized hardware devices
with minimal displays and 12-button keypads—perfect for embedded Bitcoin applications.
📄 File Format
BTC-TKP scripts are saved with the .btctpk extension.
Files are plain text containing valid TKP commands:
# example_transaction.btctpk
# Send 1000 sats with 20 sat/vB fee
#51000*20*#2#1#3#4
Comments start with # followed by a space.
🚀 Getting Started
- Start in TEST Mode: The IDE defaults to safe TEST mode
- Try the keypad: Click buttons to enter commands
- Or use your keyboard: Type 0-9, *, # (or P, C for legacy)
- Watch the VM State: See stack, balance, and registers update live
- Run examples: Try #51000*20*#2
- Export scripts: Save your work as .btctpk files
🌐 Open Source
BTC-TKP is open source software. The language specification, reference implementation, and IDE
are freely available for anyone to use, study, modify, and distribute.
This enables:
- Community-driven development and improvements
- Independent security audits and verification
- Custom hardware implementations
- Educational use and research
- Commercial and non-commercial applications
Build your own Bitcoin-enabled devices using BTC-TKP without restrictions or licensing fees.
📚 Quick Reference Card
BTC-TKP Command Cheat Sheet
| 0-9 |
Build numbers in input buffer |
| * |
Push buffer to stack |
| *1 |
Peek top of stack |
| *2 |
Swap top two items |
| #0 |
Clear stack (M0) |
| #1 |
Scan recipient address |
| #2 |
Set fee rate |
| #3 |
Sign transaction |
| #4 |
Broadcast transaction |
| #5 |
Get balance (M5) |
← Back to IDE
