{"_id":"@austinjeremiah/stackspay","_rev":"4-c867880bd8683ad5886ac6833955b0c0","name":"@austinjeremiah/stackspay","dist-tags":{"latest":"4.0.0"},"versions":{"1.0.0":{"name":"@austinjeremiah/stackspay","version":"1.0.0","keywords":["stacks","x402","bitcoin","micropayments","cli","sBTC","STX","BNS","blockchain","web3","payments","monetize","developer-tools"],"author":{"name":"Austin Jeremiah","email":"austinjeremiah@gmail.com"},"license":"MIT","_id":"@austinjeremiah/stackspay@1.0.0","maintainers":[{"name":"austinjeremiah","email":"austinjeremiah04@gmail.com"}],"homepage":"https://github.com/austinjeremiah/StackPay-CLI#readme","bugs":{"url":"https://github.com/austinjeremiah/StackPay-CLI/issues"},"bin":{"stackspay":"dist/index.js"},"dist":{"shasum":"ce72ffd5b1296202a0a90cc88bccb4becdc315bc","tarball":"https://registry.npmjs.org/@austinjeremiah/stackspay/-/stackspay-1.0.0.tgz","fileCount":15,"integrity":"sha512-ZB9v7zFUwAEEU0OBeFD7+lIAliCu5QgSP0R54crdOlmZ53MH+5saey4BhWruMBs5iUrJTVgGDuFGW8mC8q/aEQ==","signatures":[{"sig":"MEYCIQDmUOYrErZiU5aqydfg6rYjcDwj8tsx0//yiy7BIOm3OgIhAJwK3pveVPMSkGk7Y+8+G8K0rr7XqgcBDdj1DpoBJXcE","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":108445},"main":"dist/index.js","engines":{"node":">=18.0.0"},"gitHead":"87f2d395412e8e3ca124711eb607adee6993c9a0","scripts":{"dev":"ts-node src/index.ts","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"austinjeremiah","email":"austinjeremiah04@gmail.com"},"repository":{"url":"git+https://github.com/austinjeremiah/StackPay-CLI.git","type":"git"},"_npmVersion":"11.7.0","description":"Monetize any CLI script with x402-stacks in 30 seconds. Powered by Bitcoin.","directories":{},"_nodeVersion":"24.5.0","dependencies":{"ora":"^9.3.0","axios":"^1.13.5","chalk":"^5.6.2","dotenv":"^17.3.1","express":"^4.22.1","commander":"^14.0.3","x402-stacks":"^2.0.1","@stacks/network":"^6.17.0","@stacks/transactions":"^6.17.0"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.9.3","@types/node":"^25.2.3","@types/express":"^5.0.6"},"_npmOperationalInternal":{"tmp":"tmp/stackspay_1.0.0_1771061263983_0.6740840374154777","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@austinjeremiah/stackspay","version":"2.0.0","keywords":["stacks","x402","bitcoin","micropayments","cli","sBTC","STX","BNS","blockchain","web3","payments","monetize","developer-tools"],"author":{"name":"Austin Jeremiah","email":"austinjeremiah@gmail.com"},"license":"MIT","_id":"@austinjeremiah/stackspay@2.0.0","maintainers":[{"name":"austinjeremiah","email":"austinjeremiah04@gmail.com"}],"homepage":"https://github.com/austinjeremiah/StackPay-CLI#readme","bugs":{"url":"https://github.com/austinjeremiah/StackPay-CLI/issues"},"bin":{"stackspay":"dist/index.js"},"dist":{"shasum":"eeec7814e49f035d47fec5686596624be38af612","tarball":"https://registry.npmjs.org/@austinjeremiah/stackspay/-/stackspay-2.0.0.tgz","fileCount":17,"integrity":"sha512-WH/wav5qPyTUyXC8UVJ6eELc+tVBIkoJ3FpQAOZaBWh8TrvvlKlJs4qR3DLKMiMJJKBSCDHO/eN5rZJDIuC90A==","signatures":[{"sig":"MEYCIQCLff++2CE+OgdztR35y35WOxBOgFSOmIrBr+vgsJ5uLwIhAPeroUi3E+8L+Y/jiIINQuRABWQGsC6YnYa8gHcAU3Pr","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":154145},"main":"dist/index.js","engines":{"node":">=18.0.0"},"gitHead":"4d43717b2562c359a034548a31094d10bc3530c1","scripts":{"dev":"ts-node src/index.ts","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"austinjeremiah","email":"austinjeremiah04@gmail.com"},"repository":{"url":"git+https://github.com/austinjeremiah/StackPay-CLI.git","type":"git"},"_npmVersion":"11.7.0","description":"Monetize any CLI script with x402-stacks in 30 seconds. Powered by Bitcoin.","directories":{},"_nodeVersion":"24.5.0","dependencies":{"ora":"^9.3.0","axios":"^1.13.5","chalk":"^5.6.2","dotenv":"^17.3.1","express":"^4.22.1","commander":"^14.0.3","node-fetch":"^3.3.2","x402-stacks":"^2.0.1","@stacks/network":"^6.17.0","@stacks/transactions":"^6.17.0"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.9.3","@types/node":"^25.2.3","@types/express":"^5.0.6","@types/node-fetch":"^2.6.13"},"_npmOperationalInternal":{"tmp":"tmp/stackspay_2.0.0_1771064557058_0.6315565676905208","host":"s3://npm-registry-packages-npm-production"}},"3.0.0":{"name":"@austinjeremiah/stackspay","version":"3.0.0","keywords":["stacks","x402","bitcoin","micropayments","cli","sBTC","STX","BNS","blockchain","web3","payments","monetize","developer-tools"],"author":{"name":"Austin Jeremiah","email":"austinjeremiah@gmail.com"},"license":"MIT","_id":"@austinjeremiah/stackspay@3.0.0","maintainers":[{"name":"austinjeremiah","email":"austinjeremiah04@gmail.com"}],"homepage":"https://github.com/austinjeremiah/StackPay-CLI#readme","bugs":{"url":"https://github.com/austinjeremiah/StackPay-CLI/issues"},"bin":{"stackspay":"dist/index.js"},"dist":{"shasum":"6d1290852cf3d108421828a942a84b6e2b24ccae","tarball":"https://registry.npmjs.org/@austinjeremiah/stackspay/-/stackspay-3.0.0.tgz","fileCount":17,"integrity":"sha512-YrYgmWmsyNG7B2IALl4W7ctH9egfuvIODgLkbaeP+2tR/wIlQlj1sCScl1tQxVBNkt3D5OF3I/PBMtRtYDJKJA==","signatures":[{"sig":"MEUCIQCCU5P5uAe59i7hNGdjWmSNCV6CQw9Bh9J+uDjCfZEliQIgPVpFCSFPEw5iKVZsD2sfbHDSVByWVY42sD5yih4IMmM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":154179},"main":"dist/index.js","engines":{"node":">=18.0.0"},"gitHead":"1f44165b1c2fa6aa3b9b2e49faf75af3ff29e656","scripts":{"dev":"ts-node src/index.ts","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"austinjeremiah","email":"austinjeremiah04@gmail.com"},"repository":{"url":"git+https://github.com/austinjeremiah/StackPay-CLI.git","type":"git"},"_npmVersion":"11.7.0","description":"Monetize any CLI script with x402-stacks in 30 seconds. Powered by Bitcoin.","directories":{},"_nodeVersion":"24.5.0","dependencies":{"ora":"^9.3.0","axios":"^1.13.5","chalk":"^5.6.2","dotenv":"^17.3.1","express":"^4.22.1","commander":"^14.0.3","node-fetch":"^3.3.2","x402-stacks":"^2.0.1","@stacks/network":"^6.17.0","@stacks/transactions":"^6.17.0"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.9.3","@types/node":"^25.2.3","@types/express":"^5.0.6","@types/node-fetch":"^2.6.13"},"_npmOperationalInternal":{"tmp":"tmp/stackspay_3.0.0_1771147591671_0.07399764772790918","host":"s3://npm-registry-packages-npm-production"}},"4.0.0":{"name":"@austinjeremiah/stackspay","version":"4.0.0","description":"Monetize any CLI script with x402-stacks in 30 seconds. Powered by Bitcoin.","main":"dist/index.js","bin":{"stackspay":"dist/index.js"},"scripts":{"build":"tsc","dev":"ts-node src/index.ts","start":"node dist/index.js","prepublishOnly":"npm run build"},"keywords":["stacks","x402","bitcoin","micropayments","cli","sBTC","STX","BNS","blockchain","web3","payments","monetize","developer-tools"],"author":{"name":"Austin Jeremiah","email":"austinjeremiah@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/austinjeremiah/StackPay-CLI.git"},"bugs":{"url":"https://github.com/austinjeremiah/StackPay-CLI/issues"},"homepage":"https://github.com/austinjeremiah/StackPay-CLI#readme","engines":{"node":">=18.0.0"},"dependencies":{"@stacks/network":"^6.17.0","@stacks/transactions":"^6.17.0","axios":"^1.13.5","chalk":"^5.6.2","commander":"^14.0.3","dotenv":"^17.3.1","express":"^4.22.1","node-fetch":"^3.3.2","ora":"^9.3.0","x402-stacks":"^2.0.1"},"devDependencies":{"@types/express":"^5.0.6","@types/node":"^25.2.3","@types/node-fetch":"^2.6.13","ts-node":"^10.9.2","typescript":"^5.9.3"},"gitHead":"1f44165b1c2fa6aa3b9b2e49faf75af3ff29e656","_id":"@austinjeremiah/stackspay@4.0.0","_nodeVersion":"24.5.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-o4vaF8EXDOIfiJRQvRyyIleh71sNfWv0ybLlmIITGfJjYnDo5vgJE9AudUNijfS6+AZ4CZCIa8kLOYCMu3TiGA==","shasum":"4dcc56be44fbc98b0ce8bcbe5473fab486b28845","tarball":"https://registry.npmjs.org/@austinjeremiah/stackspay/-/stackspay-4.0.0.tgz","fileCount":17,"unpackedSize":154179,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCID63VhFpnav1Zy7QQoHsm/U8DPi88ZVNRS/HvD7qMHdtAiEA8BLt//8RF/NpuveIVpnf08GqTnm7fgKg4RdTTTE4Fss="}]},"_npmUser":{"name":"austinjeremiah","email":"austinjeremiah04@gmail.com"},"directories":{},"maintainers":[{"name":"austinjeremiah","email":"austinjeremiah04@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/stackspay_4.0.0_1771147844197_0.2246506610658776"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-14T09:27:43.863Z","modified":"2026-02-15T09:30:44.458Z","1.0.0":"2026-02-14T09:27:44.136Z","2.0.0":"2026-02-14T10:22:37.216Z","3.0.0":"2026-02-15T09:26:31.816Z","4.0.0":"2026-02-15T09:30:44.336Z"},"bugs":{"url":"https://github.com/austinjeremiah/StackPay-CLI/issues"},"author":{"name":"Austin Jeremiah","email":"austinjeremiah@gmail.com"},"license":"MIT","homepage":"https://github.com/austinjeremiah/StackPay-CLI#readme","keywords":["stacks","x402","bitcoin","micropayments","cli","sBTC","STX","BNS","blockchain","web3","payments","monetize","developer-tools"],"repository":{"type":"git","url":"git+https://github.com/austinjeremiah/StackPay-CLI.git"},"description":"Monetize any CLI script with x402-stacks in 30 seconds. Powered by Bitcoin.","maintainers":[{"name":"austinjeremiah","email":"austinjeremiah04@gmail.com"}],"readme":"# Stackspay\r\n\r\n<img width=\"931\" height=\"207\" alt=\"image\" src=\"https://github.com/user-attachments/assets/31ce9bf2-7e58-4216-88ff-3e294e7a0e92\" />\r\n\r\n\r\n\r\n> Monetize any CLI script with x402-stacks in 30 seconds. Powered by Bitcoin.\r\n\r\nstackspay is a terminal-native x402 payment toolkit for the Stacks blockchain. Any developer can wrap any script, command, binary, or upstream HTTP API behind an HTTP 402 paywall and start earning STX or sBTC — with zero frontend, zero database, and zero infrastructure. Revenue distribution, vault locking, BNS name resolution, multi-party splits, Autonomous Negotiation , moltbots and a live dashboard are all built in.\r\n\r\nBuilt for the [x402 Stacks Challenge](https://x402stacks.xyz) \r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n- [The Problem](#the-problem)\r\n- [The Solution](#the-solution)\r\n- [Installation](#installation)\r\n- [Quick Start](#quick-start)\r\n- [Commands Reference](#commands-reference)\r\n- [x402 Protocol Internals](#x402-protocol-internals)\r\n- [Stacks Blockchain Architecture](#stacks-blockchain-architecture)\r\n- [BNS Integration](#bns-integration)\r\n- [Vault and Lock Mechanics](#vault-and-lock-mechanics)\r\n- [Revenue Split Architecture](#revenue-split-architecture)\r\n- [Proxy Mode](#proxy-mode)\r\n- [sBTC Payments](#sbtc-payments)\r\n- [x402-stacks Integration Map](#x402-stacks-integration-map)\r\n- [File Architecture](#file-architecture)\r\n- [Demos](#demos)\r\n- [Real-World Use Cases](#real-world-use-cases)\r\n- [Development Setup](#development-setup)\r\n- [License](#license)\r\n\r\n---\r\n\r\n## The Problem\r\n\r\nEvery builder who wants to monetize a CLI tool, script, or backend service has to:\r\n\r\n- Build a web frontend with wallet integration\r\n- Set up a database (Supabase, Postgres, etc.)\r\n- Write custom x402 verification logic from scratch\r\n- Reinvent the entire payment stack every single time\r\n\r\nstackspay eliminates all of that.\r\n\r\n---\r\n\r\n## The Solution\r\n\r\n```bash\r\n# 1. Install globally\r\nnpm install -g @austinjeremiah/stackspay\r\n\r\n# 2. Create your wallet\r\nstackspay wallet create\r\n\r\n# 3. Fund it on testnet\r\nstackspay wallet fund\r\n\r\n# 4. Monetize ANY command in one line\r\nstackspay serve --cmd \"python3 summarize.py\" --price 0.001 --token STX\r\n\r\n# 5. Anyone pays and gets results instantly\r\nstackspay pay http://your-server.com/run --file document.txt\r\n```\r\n\r\nYour script is now a Bitcoin-powered paid API with no frontend, no database, and no custom server code.\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```powershell\r\nnpm install -g @austinjeremiah/stackspay\r\nstackspay --version\r\n```\r\n\r\nVerify the install worked after the registry propagates. If you see the version string, the binary is correctly linked on your PATH.\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```bash\r\n# Create and fund a wallet\r\nstackspay wallet create\r\nstackspay wallet fund\r\nstackspay wallet info\r\n\r\n# Start a paid service (Terminal 1)\r\nstackspay serve --cmd \"echo Hello from Bitcoin!\" --price 0.001 --token STX --port 3000\r\n\r\n# Pay and call it (Terminal 2)\r\nstackspay pay http://localhost:3000/run\r\n```\r\n\r\n---\r\n\r\n## Commands Reference\r\n\r\n### `stackspay wallet`\r\n\r\nManages your local Stacks keypair stored at `~/.stackspay/wallet.json`.\r\n\r\n```bash\r\nstackspay wallet create    # Generates a new secp256k1 keypair via generateKeypair()\r\nstackspay wallet balance   # Queries the Stacks node RPC for STX and sBTC balances\r\nstackspay wallet info      # Prints address, network (mainnet/testnet), and explorer link\r\nstackspay wallet fund      # POSTs to the Stacks testnet faucet for STX drip\r\n```\r\n\r\nWallet files are JSON-encoded and stored at `~/.stackspay/`. The private key is encoded as a compressed WIF hex string compatible with the Stacks secp256k1 curve. The corresponding Stacks address is a c32check-encoded address derived from the SHA256+RIPEMD160 hash of the compressed public key, prefixed with the network version byte (`0x1a` for mainnet, `0x15` for testnet).\r\n\r\n---\r\n\r\n### `stackspay serve`\r\n\r\nWraps any shell command or script behind an x402 paywall. Internally spins up an Express HTTP server with `paymentMiddleware` from `x402-stacks` guarding the `/run` endpoint.\r\n\r\n```bash\r\nstackspay serve \\\r\n  --cmd \"python3 summarize.py\" \\       # Shell command executed on successful payment\r\n  --price 0.001 \\                       # Price denominated in STX (converted to microSTX internally)\r\n  --token STX \\                         # STX or SBTC\r\n  --port 3000 \\                         # Listening port (default: 3000)\r\n  --description \"PDF Summarizer\"        # Human-readable label shown on GET /\r\n```\r\n\r\n**BNS receiver override:**\r\n\r\n```bash\r\nstackspay serve \\\r\n  --cmd \"echo Hello from Bitcoin!\" \\\r\n  --price 0.001 \\\r\n  --receiver muneeb.id \\               # BNS name; resolved to c32 address on-chain\r\n  --port 3000\r\n```\r\n\r\n**Auto-created endpoints:**\r\n\r\n| Endpoint | Description |\r\n|---|---|\r\n| `GET /` | Service info: name, price, payTo address, network, token |\r\n| `GET /health` | Server status, uptime, total payments, cumulative earnings |\r\n| `POST /run` | x402-protected; runs `--cmd` on successful payment and returns stdout |\r\n\r\n---\r\n\r\n### `stackspay pay`\r\n\r\nCalls any x402-compliant endpoint, handles the 402 challenge automatically, signs the STX transaction, and retries with the payment signature header.\r\n\r\n```bash\r\nstackspay pay http://localhost:3000/run\r\nstackspay pay http://localhost:3000/run --data '{\"text\": \"hello\"}'\r\nstackspay pay http://localhost:3000/run --file ./document.txt\r\nstackspay pay http://api.example.com/premium --raw\r\n```\r\n\r\nInternally uses `wrapAxiosWithPayment` from `x402-stacks`, which intercepts the 402 response, constructs and signs a post-condition-enforced STX transfer, and appends the base64url-encoded payment object as the `X-PAYMENT` header on the retry.\r\n\r\n---\r\n\r\n### `stackspay proxy`\r\n\r\nProxies any upstream HTTP API behind an x402 paywall. Each inbound request that clears the payment layer is forwarded to `--target` and the upstream response is returned verbatim to the caller.\r\n\r\n```bash\r\nstackspay proxy \\\r\n  --target \"https://httpbin.org/post\" \\   # Upstream URL to forward to\r\n  --price 0.001 \\                          # Price per proxied request\r\n  --token STX \\\r\n  --port 4000\r\n```\r\n\r\nUseful for wrapping third-party APIs, internal microservices, or any HTTP endpoint that does not natively support x402.\r\n\r\n---\r\n\r\n### `stackspay vault`\r\n\r\nAdvanced serve mode with on-chain reserve locking, time-locked fund release, and percentage-based revenue splits paid to BNS names or Stacks addresses.\r\n\r\n```bash\r\nstackspay vault \\\r\n  --cmd \"echo Revenue distributed!\" \\\r\n  --price 0.003 \\\r\n  --token STX \\\r\n  --port 3000 \\\r\n  --split muneeb.id:30 \\           # 30% of gross revenue routed to muneeb.id\r\n  --reserve 10 \\                   # 10% held in contract reserve\r\n  --lock 1h                        # Reserve locked for 1 hour; unlockable after TTL\r\n```\r\n\r\nSplit percentages and the reserve percentage must sum to 100 or less. The remaining percentage after splits and reserve accrues to the server wallet. Splits are executed as post-condition-enforced STX transfers on the same Stacks transaction that settles the payment, providing atomic revenue distribution.\r\n\r\n---\r\n\r\n### `stackspay split`\r\n\r\nMulti-party revenue split without vault locking. Accepts both BNS names and raw c32 Stacks addresses as recipients.\r\n\r\n```bash\r\nstackspay split \\\r\n  --cmd \"echo Collaboration paid!\" \\\r\n  --price 0.002 \\\r\n  --token STX \\\r\n  --port 3000 \\\r\n  --split muneeb.id:50 \\\r\n  --split ST2NV73HYXQFRSAYEX59BDJPRRX63YBS0YPE32MVQ:50\r\n```\r\n\r\nThe `--split` flag may be passed multiple times. Percentages must sum to exactly 100. Each split recipient receives their allocated microSTX atomically within the settlement transaction.\r\n\r\n---\r\n\r\n### `stackspay watch`\r\n\r\nOpens a live terminal dashboard rendering:\r\n\r\n- Active services and their current port bindings\r\n- Real-time payment stream (TX ID, amount, sender address, timestamp)\r\n- Per-service earnings totals\r\n- Mempool confirmation status for pending transactions\r\n\r\n```bash\r\nstackspay watch\r\n```\r\n\r\nPolls `GET /health` on all locally running stackspay server processes and renders an auto-refreshing dashboard using `blessed` or `ink`.\r\n\r\n---\r\n\r\n### `stackspay request`\r\n\r\nSpins up a browser-accessible payment request page at `http://localhost:<port>`. Renders a minimal HTML UI with the payment QR code, price, description, and wallet connect button for non-CLI users.\r\n\r\n```bash\r\nstackspay request \\\r\n  --price 0.05 \\\r\n  --token STX \\\r\n  --description \"Pay for premium access\" \\\r\n  --port 5000\r\n\r\n# Open browser: http://localhost:5000\r\n```\r\n\r\n---\r\n\r\n### `stackspay history`\r\n\r\nDisplays a paginated log of all transactions sent and received by the local wallet, fetched from the Stacks API transaction history endpoint. Includes TX ID, block height, confirmation count, amount, and counterparty address.\r\n\r\n```bash\r\nstackspay history\r\n```\r\n\r\n---\r\n\r\n## x402 Protocol Internals\r\n\r\nstackspay implements the full Coinbase x402 v2 protocol on Stacks. The flow below describes exactly what happens at the HTTP and blockchain layer for every paid request.\r\n\r\n```\r\nBuyer (stackspay pay)        stackspay serve              Stacks L1 / Facilitator\r\n        |                           |                              |\r\n        |---- POST /run ----------->|                              |\r\n        |                           |                              |\r\n        |<--- HTTP 402 -------------|                              |\r\n        |     headers:              |                              |\r\n        |       X-PAYMENT-REQUIRED  |                              |\r\n        |       X-ACCEPTS-PAYMENT   |                              |\r\n        |       CAIP-2 network ID   |                              |\r\n        |       amount (microSTX)   |                              |\r\n        |       payTo (c32 address) |                              |\r\n        |       token contract ID   |                              |\r\n        |                           |                              |\r\n        | [wrapAxiosWithPayment]     |                              |\r\n        | - Builds STX transfer tx  |                              |\r\n        | - Attaches post-condition |                              |\r\n        | - Signs with private key  |                              |\r\n        | - Base64url-encodes obj   |                              |\r\n        |                           |                              |\r\n        |---- POST /run ----------->|                              |\r\n        |     X-PAYMENT: <encoded>  |                              |\r\n        |                           |---- settle tx -------------->|\r\n        |                           |     via x402-stacks          |\r\n        |                           |     facilitator endpoint     |\r\n        |                           |<--- txid confirmed ----------|\r\n        |                           |                              |\r\n        |<--- HTTP 200 -------------|                              |\r\n        |     stdout of --cmd       |                              |\r\n```\r\n\r\n### 402 Response Headers\r\n\r\nThe `paymentMiddleware` from `x402-stacks` emits the following headers on a 402:\r\n\r\n| Header | Value |\r\n|---|---|\r\n| `X-PAYMENT-REQUIRED` | `true` |\r\n| `X-ACCEPTS-PAYMENT` | `stacks-v2` |\r\n| `X-PAYMENT-AMOUNT` | Amount in microSTX (1 STX = 1,000,000 microSTX) |\r\n| `X-PAYMENT-PAYTO` | c32check-encoded Stacks address of the receiver |\r\n| `X-PAYMENT-NETWORK` | CAIP-2 network ID (`stacks:1` mainnet, `stacks:2147483648` testnet) |\r\n| `X-PAYMENT-TOKEN` | `STX` or sBTC Clarity contract principal |\r\n\r\n### Payment Signature Header\r\n\r\nOn the retry, the buyer sends `X-PAYMENT` containing a base64url-encoded JSON object:\r\n\r\n```json\r\n{\r\n  \"scheme\": \"stacks-v2\",\r\n  \"networkId\": \"stacks:2147483648\",\r\n  \"payload\": {\r\n    \"txHex\": \"0x0000000001...\",\r\n    \"signature\": \"...\",\r\n    \"publicKey\": \"03...\",\r\n    \"nonce\": 42,\r\n    \"fee\": 1000,\r\n    \"postConditions\": [...]\r\n  }\r\n}\r\n```\r\n\r\nThe server's `paymentMiddleware` decodes this object, submits the serialized transaction hex to the Stacks node broadcast endpoint, and waits for mempool acceptance before proceeding. Finality is provided by the Stacks Bitcoin anchor block mechanism.\r\n\r\n### Post-Conditions\r\n\r\nEvery payment transaction includes a `STX_TRANSFER_FUNGIBLE_CONDITION` post-condition asserting that exactly `price * 1,000,000 microSTX` leaves the sender's account. This is enforced by the Stacks VM at the consensus layer, making overpayment and underpayment impossible regardless of the server's behavior.\r\n\r\n---\r\n\r\n## Stacks Blockchain Architecture\r\n\r\nStacks is a Layer 1 blockchain that settles every block to Bitcoin via a cryptographic commitment written into a Bitcoin `OP_RETURN` output. This means:\r\n\r\n- Every STX payment made through stackspay is anchored to Bitcoin within one Bitcoin block (~10 minutes for finality, mempool acceptance is immediate).\r\n- The Stacks VM (Clarity) executes smart contracts with read-only access to Bitcoin state, enabling trustless BTC-conditional logic.\r\n- Stacks uses a Proof-of-Transfer (PoX) consensus mechanism: Stacks miners commit BTC to participate in block production, and STX stackers receive BTC yield in return.\r\n\r\nFor stackspay, the relevant Stacks primitives are:\r\n\r\n**Accounts:** Stacks addresses are c32check-encoded compressed secp256k1 public key hashes. c32check is a Stacks-specific base32 encoding with a version byte and checksum that prevents address confusion with Bitcoin addresses.\r\n\r\n**Transactions:** Stacks transactions are serialized using a custom binary encoding (not RLP like Ethereum). A standard STX transfer serializes to approximately 200–250 bytes and costs ~0.001 STX in fees at typical fee market conditions.\r\n\r\n**Nonces:** Each Stacks account has a monotonically increasing nonce. `wrapAxiosWithPayment` fetches the current nonce from the Stacks node before signing to prevent replay attacks.\r\n\r\n**Microblock streams:** Between anchor blocks, Stacks miners produce microblocks that confirm transactions within seconds. stackspay's facilitator accepts mempool confirmation (effectively immediate) rather than waiting for anchor block finality, giving sub-second payment UX.\r\n\r\n---\r\n\r\n## BNS Integration\r\n\r\nThe Bitcoin Name System (BNS) is a decentralized naming protocol built into the Stacks blockchain as a Clarity smart contract (`SP000000000000000000002Q6VF78.bns`). BNS names are human-readable identifiers (e.g., `muneeb.id`) that resolve to Stacks addresses via an on-chain name registry.\r\n\r\nstackspay uses BNS for `--receiver` in `serve` and for split recipients in `split` and `vault` commands. Resolution works as follows:\r\n\r\n1. stackspay calls the BNS contract's `name-resolve` read-only function via the Stacks RPC endpoint.\r\n2. The contract returns the owner's c32 Stacks address.\r\n3. stackspay substitutes this address wherever a BNS name was specified.\r\n4. The resolved address is included in the 402 `X-PAYMENT-PAYTO` header so the buyer's client sends payment directly to the correct beneficiary.\r\n\r\nBNS resolution is cached in memory for the lifetime of the server process to avoid repeated RPC calls on each payment.\r\n\r\n---\r\n\r\n## Vault and Lock Mechanics\r\n\r\nThe `vault` command extends standard serve behavior with time-locked reserve accounting:\r\n\r\n**Reserve holding:** A configurable percentage of each payment is tracked as \"locked reserve\" in the vault's local state file (`~/.stackspay/vault.json`). The actual STX lands in the server wallet immediately (Stacks has no native escrow without a Clarity contract), but vault tracks the reserve balance and prevents manual withdrawal commands until the lock TTL expires.\r\n\r\n**Lock TTL:** The `--lock` flag accepts duration strings (`1h`, `30m`, `7d`). Until the TTL elapses, `stackspay wallet balance` will show the vault reserve as \"locked\" and prevent transfers of that portion.\r\n\r\n**Revenue splits:** Split payments are executed as separate STX transfer transactions broadcast atomically within the settlement flow. Each split recipient gets a discrete transaction, confirmed in the same microblock round as the primary payment.\r\n\r\n---\r\n\r\n## Revenue Split Architecture\r\n\r\nThe `split` command supports mixed BNS and raw address recipients:\r\n\r\n```\r\nGross payment (e.g., 0.002 STX = 2000 microSTX)\r\n    |\r\n    +-- muneeb.id (50%)    --> 1000 microSTX STX transfer tx to resolved c32 address\r\n    |\r\n    +-- ST2NV73... (50%)   --> 1000 microSTX STX transfer tx to raw c32 address\r\n```\r\n\r\nBoth transfers are signed by the server wallet (which receives the gross payment first) and broadcast sequentially with incrementing nonces. The client receives their `200 OK` response only after both split transfers have been accepted into the mempool, providing a consistent view of successful multi-party distribution.\r\n\r\nIf a split transfer fails (e.g., fee estimation fails, node is unreachable), the error is logged to `~/.stackspay/split-errors.log` and the primary command output is still returned to the caller. The split failure does not block the buyer from receiving their result.\r\n\r\n---\r\n\r\n## Proxy Mode\r\n\r\n`stackspay proxy` implements x402 at the HTTP middleware layer without running any local command:\r\n\r\n```\r\nstackspay proxy                       Upstream API\r\n(x402 paywall at :4000)          (https://httpbin.org/post)\r\n        |                                   |\r\n        |<-- POST /proxy -------------------|\r\n        |    [cleared by paymentMiddleware] |\r\n        |                                   |\r\n        |---- forward original request ---->|\r\n        |<---- upstream response -----------|\r\n        |                                   |\r\n        |--> 200 + upstream body ---------->|\r\n             to original caller\r\n```\r\n\r\nThe proxy strips the `X-PAYMENT` and `X-PAYMENT-REQUIRED` headers before forwarding upstream and reattaches the upstream response body and status code verbatim. Any upstream headers in a configurable passlist are forwarded to the caller.\r\n\r\n---\r\n\r\n## sBTC Payments\r\n\r\nsBTC is a 1:1 Bitcoin-backed fungible token on Stacks defined by the Clarity SIP-010 fungible token standard. sBTC is custodied by the decentralized sBTC signer network, which holds the corresponding BTC in a threshold-multisig Bitcoin script.\r\n\r\nWhen `--token SBTC` is specified:\r\n\r\n- The 402 response includes the sBTC Clarity contract principal (`SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token`) in the `X-PAYMENT-TOKEN` header.\r\n- `wrapAxiosWithPayment` constructs a `contract-call` transaction invoking the `transfer` function of the SIP-010 interface rather than a native STX transfer.\r\n- Post-conditions assert that exactly the specified sats worth of sBTC (converted via `BTCtoSats`) debit the sender's sBTC balance.\r\n- The facilitator verifies the SIP-010 transfer event in the transaction receipt rather than a native STX transfer event.\r\n\r\nsBTC pricing uses `BTCtoSats` from `x402-stacks` to convert human-readable BTC amounts to the integer satoshi denomination stored in the sBTC contract's balance map.\r\n\r\n---\r\n\r\n## x402-stacks Integration Map\r\n\r\n| x402-stacks Export | stackspay Usage |\r\n|---|---|\r\n| `paymentMiddleware` | Guards `POST /run` and `POST /proxy` in `serve` and `proxy` |\r\n| `wrapAxiosWithPayment` | Intercepts 402 responses and auto-pays in the `pay` command |\r\n| `privateKeyToAccount` | Reconstructs the Stacks account from the saved private key |\r\n| `generateKeypair` | Called by `wallet create` to produce a fresh secp256k1 keypair |\r\n| `STXtoMicroSTX` | Converts `--price` decimal STX values to microSTX integers |\r\n| `BTCtoSats` | Converts `--price` decimal BTC values to satoshi integers for sBTC |\r\n| `decodePaymentResponse` | Decodes the base64url payment object for TX ID display |\r\n| CAIP-2 network IDs | `stacks:1` (mainnet) and `stacks:2147483648` (testnet) |\r\n| x402 v2 headers | Full header spec compliance on both server and client |\r\n| Facilitator pattern | Settlement via `https://x402-backend-7eby.onrender.com` |\r\n\r\n---\r\n\r\n## File Architecture\r\n\r\n```\r\nstackspay/\r\n├── src/\r\n│   ├── index.ts                 # CLI entry point (commander.js)\r\n│   ├── commands/\r\n│   │   ├── wallet.ts            # create, balance, info, fund\r\n│   │   ├── serve.ts             # x402 command server\r\n│   │   ├── pay.ts               # x402 payment client\r\n│   │   ├── proxy.ts             # x402 reverse proxy\r\n│   │   ├── vault.ts             # serve + reserve locking + splits\r\n│   │   ├── split.ts             # multi-party revenue split\r\n│   │   ├── watch.ts             # live terminal dashboard\r\n│   │   ├── request.ts           # browser payment request page\r\n│   │   └── history.ts           # wallet transaction history\r\n│   └── utils/\r\n│       ├── wallet.ts            # Keypair file management (~/.stackspay/)\r\n│       ├── bns.ts               # BNS name resolution via Stacks RPC\r\n│       ├── split.ts             # Split percentage parsing and execution\r\n│       └── vault.ts             # Vault state file management\r\n├── dist/                        # Compiled JavaScript output\r\n├── package.json\r\n└── tsconfig.json\r\n```\r\n\r\nTech stack: TypeScript + Node.js, `x402-stacks` for the HTTP 402 protocol, `express` for the HTTP server, `commander` for CLI parsing, `axios` with x402 interceptor for the payment client, `chalk` and `ora` for terminal UX.\r\n\r\n---\r\n\r\n## Demos\r\n\r\n### Demo 1 — Wallet Info\r\n\r\n```powershell\r\nstackspay wallet info\r\nstackspay wallet balance\r\n```\r\n\r\n`wallet info` prints the c32check Stacks address, the CAIP-2 network ID, and a Stacks Explorer deep link for the account. `wallet balance` calls the Stacks node's `/v2/accounts/<address>` RPC endpoint and returns the STX balance in both microSTX and formatted STX, plus any sBTC SIP-010 token balance if the account has previously received sBTC.\r\n\r\n---\r\n\r\n### Demo 2 — Basic Serve + Pay\r\n\r\n```powershell\r\n# Terminal 1\r\nstackspay serve --cmd \"echo Hello from Bitcoin!\" --price 0.001 --token STX --port 3000\r\n\r\n# Terminal 2\r\nstackspay pay http://localhost:3000/run\r\n```\r\n\r\nTerminal 1 starts an Express server with `paymentMiddleware` bound to `POST /run`. The middleware emits a `402` with CAIP-2 network ID `stacks:2147483648` (testnet), amount `1000 microSTX`, and the server wallet's c32 address in `X-PAYMENT-PAYTO`.\r\n\r\nTerminal 2 calls `wrapAxiosWithPayment`, which intercepts the 402, builds and signs a 200-byte STX transfer transaction with a `STX_TRANSFER_FUNGIBLE_CONDITION` post-condition, base64url-encodes it, and retries the POST with the `X-PAYMENT` header. The server submits the transaction to the facilitator at `https://x402-backend-7eby.onrender.com`, waits for mempool acceptance, then executes `echo Hello from Bitcoin!` and returns the stdout in the response body.\r\n\r\n---\r\n\r\n### Demo 3 — BNS Serve\r\n\r\n```powershell\r\n# Terminal 1\r\nstackspay serve --cmd \"echo Hello from Bitcoin!\" --price 0.001 --receiver muneeb.id --port 3000\r\n\r\n# Terminal 2\r\nstackspay pay http://localhost:3000/run\r\n```\r\n\r\nBefore starting the Express server, stackspay calls the BNS contract's `name-resolve` read-only function on the Stacks RPC node to resolve `muneeb.id` to its owner c32 address. This resolved address is then passed as the `payTo` parameter to `paymentMiddleware`, so the 402 challenge instructs the buyer to pay directly to `muneeb.id`'s underlying Stacks address. No STX flows through the server wallet.\r\n\r\n---\r\n\r\n### Demo 4 — Proxy Any API\r\n\r\n```powershell\r\n# Terminal 1\r\nstackspay proxy --target \"https://httpbin.org/post\" --price 0.001 --token STX --port 4000\r\n\r\n# Terminal 2\r\nstackspay pay http://localhost:4000/proxy\r\n```\r\n\r\nThe proxy command wraps the upstream `https://httpbin.org/post` endpoint behind a 402 paywall. After `paymentMiddleware` clears the payment, the server forwards the original request body (including any `--data` or `--file` passed to `stackspay pay`) to `https://httpbin.org/post` using axios, and returns the upstream JSON response verbatim to the caller. The `X-PAYMENT` and `X-PAYMENT-REQUIRED` headers are stripped before forwarding to the upstream.\r\n\r\n---\r\n\r\n### Demo 5 — Vault with BNS Split\r\n\r\n```powershell\r\n# Terminal 1\r\nstackspay vault --cmd \"echo Revenue distributed!\" --price 0.003 --token STX --port 3000 --split muneeb.id:30 --reserve 10 --lock 1h\r\n\r\n# Terminal 2\r\nstackspay pay http://localhost:3000/run\r\n```\r\n\r\nOn each payment of 3000 microSTX:\r\n\r\n- 900 microSTX (30%) is transferred to `muneeb.id`'s resolved c32 address as a discrete STX transfer transaction.\r\n- 300 microSTX (10%) is recorded as locked reserve in `~/.stackspay/vault.json` with a 1-hour TTL.\r\n- 1800 microSTX (60%) remains in the server wallet as net revenue.\r\n\r\nThe vault lock prevents the 300 microSTX reserve from being sent out via `stackspay wallet` commands until the 1-hour TTL has elapsed, simulating a holdback period for refunds or dispute resolution.\r\n\r\n---\r\n\r\n### Demo 6 — Split with BNS Names\r\n\r\n```powershell\r\n# Terminal 1\r\nstackspay split --cmd \"echo Collaboration paid!\" --price 0.002 --token STX --port 3000 --split muneeb.id:50 --split ST2NV73HYXQFRSAYEX59BDJPRRX63YBS0YPE32MVQ:50\r\n\r\n# Terminal 2\r\nstackspay pay http://localhost:3000/run\r\n```\r\n\r\nOn each payment of 2000 microSTX, two STX transfer transactions are broadcast with consecutive nonces:\r\n\r\n- Nonce N: 1000 microSTX to `muneeb.id` (BNS-resolved to its owner c32 address)\r\n- Nonce N+1: 1000 microSTX to `ST2NV73HYXQFRSAYEX59BDJPRRX63YBS0YPE32MVQ` (raw c32 address, used directly)\r\n\r\nBoth transactions carry `STX_TRANSFER_FUNGIBLE_CONDITION` post-conditions. The command output is returned to the buyer after both transactions are accepted into the Stacks mempool.\r\n\r\n---\r\n\r\n### Demo 7 — Watch Dashboard\r\n\r\n```powershell\r\nstackspay watch\r\n```\r\n\r\nRenders a terminal dashboard that polls all locally running stackspay server processes (detected via `~/.stackspay/servers.json`, written on `serve`/`vault`/`split`/`proxy` startup) and displays:\r\n\r\n- Service name, port, price, and token type\r\n- Live payment stream with TX ID, sender c32 address, amount, and relative timestamp\r\n- Total payments received and cumulative earnings per service\r\n- Mempool confirmation status fetched from the Stacks API\r\n\r\nThe dashboard auto-refreshes every 2 seconds.\r\n\r\n---\r\n\r\n### Demo 8 — Payment Request Page\r\n\r\n```powershell\r\n# Terminal 1\r\nstackspay request --price 0.05 --token STX --description \"Pay for premium access\" --port 5000\r\n\r\n# Open browser: http://localhost:5000\r\n```\r\n\r\nServes a static HTML page with:\r\n\r\n- A QR code encoding the Stacks address and payment amount in the Stacks URI scheme (`stacks:<address>?amount=<microSTX>`)\r\n- The price, description, and server wallet address rendered as human-readable text\r\n- A Hiro Wallet deep link button for one-click payment from a browser wallet extension\r\n- A polling loop that checks `GET /health` every 3 seconds and displays a \"Payment Received\" confirmation once a matching transaction appears in the mempool\r\n\r\n---\r\n\r\n### Demo 9 — History\r\n\r\n```powershell\r\nstackspay history\r\n```\r\n\r\nFetches the transaction history for the local wallet address from the Stacks API `GET /extended/v1/address/<address>/transactions` endpoint. Displays a paginated table of:\r\n\r\n- TX ID (truncated, with full link to Stacks Explorer)\r\n- Block height and confirmation count\r\n- Transaction type (STX transfer, contract call for sBTC)\r\n- Amount in STX or sBTC\r\n- Counterparty c32 address\r\n\r\n---\r\n\r\n## Demo 10 — AI Agent Economy (Autonomous Negotiation)\r\n\r\nstackspay includes a full agent-to-agent payment protocol. AI agents can autonomously discover services, negotiate prices, and pay — all without human involvement.\r\n\r\n### Start an agent service with negotiation enabled\r\n```bash\r\n# Terminal 1\r\nstackspay agent \\\r\n  --cmd \"echo Intel delivered!\" \\\r\n  --price 0.005 \\\r\n  --min 0.001 \\\r\n  --negotiate \\\r\n  --capabilities \"data,blockchain,realtime\"\r\n```\r\n\r\n### Agent pays at listed price\r\n```bash\r\n# Terminal 2\r\nstackspay agent-pay http://localhost:3000/run\r\n```\r\n\r\n### Agent negotiates autonomously (starts at 70% of listed price)\r\n```bash\r\n# Terminal 2\r\nstackspay agent-pay http://localhost:3000/run --negotiate\r\n```\r\n\r\n### Agent opens with a low-ball offer (triggers counter-offer flow)\r\n```bash\r\n# Terminal 2\r\nstackspay agent-pay http://localhost:3000/run --negotiate --offer 0.0005\r\n```\r\n\r\nThe negotiation output looks like this:\r\n```\r\nNegotiation round 1\r\n  Offering  : 0.0005 STX\r\n  Counter   : 0.001 STX\r\n\r\nNegotiation round 2\r\n  Offering  : 0.00075 STX\r\n  Accepted  : 0.001 STX\r\n\r\nDeal agreed: 0.001 STX\r\nAgent Payment Complete\r\n  TX      : 348ea955...\r\n  Explorer: https://explorer.hiro.so/txid/348ea955...\r\n```\r\n\r\n### Agent service options\r\n\r\n| Flag | Description | Default |\r\n|------|-------------|---------|\r\n| `--cmd` | Command to execute on payment (required) | |\r\n| `--price` | Listed price in STX (required) | |\r\n| `--min` | Minimum acceptable price (sets negotiation floor) | 50% of listed |\r\n| `--negotiate` | Enable autonomous price negotiation | false |\r\n| `--capabilities` | Comma-separated capability tags | data,compute,analysis |\r\n| `--port` | Port to listen on | 3000 |\r\n\r\n### Agent pay options\r\n\r\n| Flag | Description |\r\n|------|-------------|\r\n| `--negotiate` | Attempt price negotiation before paying |\r\n| `--offer` | Initial offer price in STX |\r\n| `--agent-id` | Custom agent identifier |\r\n| `--data` | JSON data to send with request |\r\n| `--file` | Send file contents as request body |\r\n| `--raw` | Print raw response |\r\n\r\n## Real-World Use Cases\r\n\r\n### AI API Monetization\r\n\r\n```bash\r\n# Wrap an AI script — no API key, no subscription\r\nstackspay serve --cmd \"python3 gpt_summarize.py\" --price 0.05 --token STX -d \"GPT-4 Summarizer\"\r\n\r\n# Client pays per use\r\nstackspay pay http://your-server/run --file bigdoc.txt\r\n```\r\n\r\n### Data Feed Pay-Per-Query\r\n\r\n```bash\r\nstackspay serve --cmd \"python3 crypto_price.py\" --price 0.001 --token STX -d \"Live BTC Price\"\r\n```\r\n\r\n### Developer Tool Monetization\r\n\r\n```bash\r\n# Any open-source tool becomes a paid service\r\nstackspay serve --cmd \"npx prettier --write\" --price 0.002 --token STX -d \"Code Formatter\"\r\n```\r\n\r\n### sBTC (Bitcoin-Native) Payments\r\n\r\n```bash\r\n# Accept actual Bitcoin value via sBTC SIP-010 token\r\nstackspay serve --cmd \"node analyze.js\" --price 0.00001 --token SBTC -d \"BTC-Powered Analytics\"\r\n```\r\n\r\n### Multi-Developer Revenue Share\r\n\r\n```bash\r\n# Distribute revenue among open-source contributors\r\nstackspay split \\\r\n  --cmd \"python3 model.py\" \\\r\n  --price 0.01 --token STX \\\r\n  --split contributor1.id:40 \\\r\n  --split contributor2.id:40 \\\r\n  --split ST3FOUNDATION000000000:20\r\n```\r\n\r\n---\r\n\r\n## Development Setup\r\n\r\n```bash\r\ngit clone https://github.com/austinjeremiah/stackspay\r\ncd stackspay\r\nnpm install\r\nnpm run build\r\nnode dist/index.js wallet create\r\nnode dist/index.js wallet fund\r\n```\r\n\r\nTo run without installing globally:\r\n\r\n```bash\r\nnode dist/index.js serve --cmd \"echo test\" --price 0.001 --token STX\r\n```\r\n\r\n---\r\n\r\n## Why stackspay\r\n\r\n| Challenge Goal | stackspay |\r\n|---|---|\r\n| Drive x402-stacks adoption | Any dev can adopt in 30 seconds with zero infrastructure |\r\n| New monetization models | First pay-per-CLI-command model on Stacks |\r\n| Functional MVPs | Fully working testnet demo across all 9 command types |\r\n| Real-world needs | Devs need to monetize tools without building frontends |\r\n| Lower barriers | No frontend, no database, no custom smart contract |\r\n| Developer resources | Open-source SDK others can fork and extend |\r\n| BNS integration | Human-readable payment addresses via Bitcoin Name System |\r\n| Multi-party splits | Atomic revenue distribution in a single payment flow |\r\n| sBTC support | Real Bitcoin-denominated payments via SIP-010 |\r\n\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT — Build freely, earn Bitcoin.\r\n\r\nBuilt for the x402 Stacks Challenge · Powered by [x402-stacks](https://www.npmjs.com/package/x402-stacks)\r\n","readmeFilename":"README.md"}