paytaca-cli 0.6.2 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/README.md +183 -34
  2. package/dist/ai/autoRefill.d.ts +85 -0
  3. package/dist/ai/autoRefill.d.ts.map +1 -0
  4. package/dist/ai/autoRefill.js +266 -0
  5. package/dist/ai/autoRefill.js.map +1 -0
  6. package/dist/ai/client.d.ts +73 -0
  7. package/dist/ai/client.d.ts.map +1 -0
  8. package/dist/ai/client.js +90 -0
  9. package/dist/ai/client.js.map +1 -0
  10. package/dist/ai/config.d.ts +8 -0
  11. package/dist/ai/config.d.ts.map +1 -0
  12. package/dist/ai/config.js +17 -0
  13. package/dist/ai/config.js.map +1 -0
  14. package/dist/ai/configure.d.ts +61 -0
  15. package/dist/ai/configure.d.ts.map +1 -0
  16. package/dist/ai/configure.js +452 -0
  17. package/dist/ai/configure.js.map +1 -0
  18. package/dist/ai/credits.d.ts +27 -0
  19. package/dist/ai/credits.d.ts.map +1 -0
  20. package/dist/ai/credits.js +108 -0
  21. package/dist/ai/credits.js.map +1 -0
  22. package/dist/ai/images.d.ts +128 -0
  23. package/dist/ai/images.d.ts.map +1 -0
  24. package/dist/ai/images.js +399 -0
  25. package/dist/ai/images.js.map +1 -0
  26. package/dist/ai/models.d.ts +13 -0
  27. package/dist/ai/models.d.ts.map +1 -0
  28. package/dist/ai/models.js +49 -0
  29. package/dist/ai/models.js.map +1 -0
  30. package/dist/ai/oauth.d.ts +45 -0
  31. package/dist/ai/oauth.d.ts.map +1 -0
  32. package/dist/ai/oauth.js +137 -0
  33. package/dist/ai/oauth.js.map +1 -0
  34. package/dist/ai/purchase.d.ts +30 -0
  35. package/dist/ai/purchase.d.ts.map +1 -0
  36. package/dist/ai/purchase.js +456 -0
  37. package/dist/ai/purchase.js.map +1 -0
  38. package/dist/commands/address.d.ts.map +1 -1
  39. package/dist/commands/address.js +86 -47
  40. package/dist/commands/address.js.map +1 -1
  41. package/dist/commands/ai.d.ts +9 -0
  42. package/dist/commands/ai.d.ts.map +1 -0
  43. package/dist/commands/ai.js +951 -0
  44. package/dist/commands/ai.js.map +1 -0
  45. package/dist/commands/balance.d.ts.map +1 -1
  46. package/dist/commands/balance.js +68 -129
  47. package/dist/commands/balance.js.map +1 -1
  48. package/dist/commands/history.d.ts.map +1 -1
  49. package/dist/commands/history.js +38 -78
  50. package/dist/commands/history.js.map +1 -1
  51. package/dist/commands/mcp.d.ts +14 -0
  52. package/dist/commands/mcp.d.ts.map +1 -0
  53. package/dist/commands/mcp.js +68 -0
  54. package/dist/commands/mcp.js.map +1 -0
  55. package/dist/commands/pay.js +1 -1
  56. package/dist/commands/pay.js.map +1 -1
  57. package/dist/commands/receive.d.ts +1 -8
  58. package/dist/commands/receive.d.ts.map +1 -1
  59. package/dist/commands/receive.js +51 -124
  60. package/dist/commands/receive.js.map +1 -1
  61. package/dist/commands/send.d.ts +0 -10
  62. package/dist/commands/send.d.ts.map +1 -1
  63. package/dist/commands/send.js +40 -50
  64. package/dist/commands/send.js.map +1 -1
  65. package/dist/commands/swap.js +1 -1
  66. package/dist/commands/swap.js.map +1 -1
  67. package/dist/commands/token.d.ts +1 -9
  68. package/dist/commands/token.d.ts.map +1 -1
  69. package/dist/commands/token.js +192 -289
  70. package/dist/commands/token.js.map +1 -1
  71. package/dist/commands/update.d.ts +32 -0
  72. package/dist/commands/update.d.ts.map +1 -0
  73. package/dist/commands/update.js +200 -0
  74. package/dist/commands/update.js.map +1 -0
  75. package/dist/commands/wallet.js +1 -1
  76. package/dist/commands/wallet.js.map +1 -1
  77. package/dist/commands/web.d.ts +3 -0
  78. package/dist/commands/web.d.ts.map +1 -0
  79. package/dist/commands/web.js +71 -0
  80. package/dist/commands/web.js.map +1 -0
  81. package/dist/core/context.d.ts +30 -0
  82. package/dist/core/context.d.ts.map +1 -0
  83. package/dist/core/context.js +45 -0
  84. package/dist/core/context.js.map +1 -0
  85. package/dist/core/wallet.d.ts +130 -0
  86. package/dist/core/wallet.d.ts.map +1 -0
  87. package/dist/core/wallet.js +276 -0
  88. package/dist/core/wallet.js.map +1 -0
  89. package/dist/index.js +8 -0
  90. package/dist/index.js.map +1 -1
  91. package/dist/mcp/server.d.ts +8 -0
  92. package/dist/mcp/server.d.ts.map +1 -0
  93. package/dist/mcp/server.js +52 -0
  94. package/dist/mcp/server.js.map +1 -0
  95. package/dist/mcp/tools.d.ts +7 -0
  96. package/dist/mcp/tools.d.ts.map +1 -0
  97. package/dist/mcp/tools.js +752 -0
  98. package/dist/mcp/tools.js.map +1 -0
  99. package/dist/utils/format.d.ts +23 -0
  100. package/dist/utils/format.d.ts.map +1 -0
  101. package/dist/utils/format.js +62 -0
  102. package/dist/utils/format.js.map +1 -0
  103. package/dist/utils/x402.js +1 -1
  104. package/dist/utils/x402.js.map +1 -1
  105. package/dist/wallet/cauldron/swap.d.ts +15 -0
  106. package/dist/wallet/cauldron/swap.d.ts.map +1 -1
  107. package/dist/wallet/cauldron/swap.js +31 -0
  108. package/dist/wallet/cauldron/swap.js.map +1 -1
  109. package/dist/wallet/index.d.ts +29 -1
  110. package/dist/wallet/index.d.ts.map +1 -1
  111. package/dist/wallet/index.js +92 -8
  112. package/dist/wallet/index.js.map +1 -1
  113. package/dist/wallet/keys.d.ts.map +1 -1
  114. package/dist/wallet/keys.js +2 -0
  115. package/dist/wallet/keys.js.map +1 -1
  116. package/dist/web/assets.d.ts +3 -0
  117. package/dist/web/assets.d.ts.map +1 -0
  118. package/dist/web/assets.js +3 -0
  119. package/dist/web/assets.js.map +1 -0
  120. package/dist/web/page.d.ts +2 -0
  121. package/dist/web/page.d.ts.map +1 -0
  122. package/dist/web/page.js +637 -0
  123. package/dist/web/page.js.map +1 -0
  124. package/dist/web/server.d.ts +79 -0
  125. package/dist/web/server.d.ts.map +1 -0
  126. package/dist/web/server.js +665 -0
  127. package/dist/web/server.js.map +1 -0
  128. package/package.json +8 -3
  129. package/dist/commands/wallet.test.d.ts +0 -2
  130. package/dist/commands/wallet.test.d.ts.map +0 -1
  131. package/dist/commands/wallet.test.js +0 -68
  132. package/dist/commands/wallet.test.js.map +0 -1
  133. package/dist/nostr/chat.test.d.ts +0 -2
  134. package/dist/nostr/chat.test.d.ts.map +0 -1
  135. package/dist/nostr/chat.test.js +0 -121
  136. package/dist/nostr/chat.test.js.map +0 -1
  137. package/dist/nostr/store.test.d.ts +0 -2
  138. package/dist/nostr/store.test.d.ts.map +0 -1
  139. package/dist/nostr/store.test.js +0 -456
  140. package/dist/nostr/store.test.js.map +0 -1
  141. package/dist/utils/prices.test.d.ts +0 -5
  142. package/dist/utils/prices.test.d.ts.map +0 -1
  143. package/dist/utils/prices.test.js +0 -62
  144. package/dist/utils/prices.test.js.map +0 -1
  145. package/dist/utils/x402.test.d.ts +0 -2
  146. package/dist/utils/x402.test.d.ts.map +0 -1
  147. package/dist/utils/x402.test.js +0 -216
  148. package/dist/utils/x402.test.js.map +0 -1
  149. package/dist/wallet/cauldron/pools.test.d.ts +0 -3
  150. package/dist/wallet/cauldron/pools.test.d.ts.map +0 -1
  151. package/dist/wallet/cauldron/pools.test.js +0 -149
  152. package/dist/wallet/cauldron/pools.test.js.map +0 -1
  153. package/dist/wallet/cauldron/swap.test.d.ts +0 -2
  154. package/dist/wallet/cauldron/swap.test.d.ts.map +0 -1
  155. package/dist/wallet/cauldron/swap.test.js +0 -179
  156. package/dist/wallet/cauldron/swap.test.js.map +0 -1
  157. package/skills/README.md +0 -68
  158. package/skills/paytaca-send/SKILL.md +0 -159
  159. package/skills/paytaca-wallet/SKILL.md +0 -164
  160. package/skills/paytaca-x402/SKILL.md +0 -130
package/README.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  A command-line interface for the Paytaca [Bitcoin Cash](https://bitcoincash.org) (BCH) wallet. Built with the same core logic as the [Paytaca mobile app](https://github.com/paytaca/paytaca-app), using [watchtower-cash-js](https://github.com/paytaca/watchtower-cash-js) for transaction operations and [libauth](https://github.com/bitauth/libauth) for HD key derivation.
4
4
 
5
- Bitcoin Cash is peer-to-peer electronic cash, enabling fast, low-fee transactions for everyday use. Paytaca CLI brings the full capabilities of the Paytaca wallet to the terminal — create wallets, derive addresses, send and receive BCH, manage CashTokens (fungible tokens and NFTs), and view transaction history, all from the command line.
5
+ Bitcoin Cash is peer-to-peer electronic cash, enabling fast, low-fee transactions for everyday use. Paytaca CLI brings the full capabilities of the Paytaca wallet to the terminal — create wallets, derive addresses, send and receive BCH, manage CashTokens (fungible tokens and NFTs), swap tokens on the Cauldron DEX, pay x402 HTTP APIs, chat over Nostr, and view transaction history, all from the command line.
6
6
 
7
- Designed to be AI agent-friendly and useful for automation by power users.
7
+ Designed to be AI agent-friendly and useful for automation by power users. It ships an MCP server and a one-step installer for the Paytaca AI provider.
8
8
 
9
9
  ## Requirements
10
10
 
@@ -29,6 +29,8 @@ After installing, the `paytaca` command is available globally.
29
29
 
30
30
  ## Commands
31
31
 
32
+ Most commands accept `--json` for machine-readable output and `--chipnet` to target testnet (see [Network](#network)). Run `paytaca <command> --help` for the full option list.
33
+
32
34
  ### Wallet
33
35
 
34
36
  ```bash
@@ -111,8 +113,11 @@ paytaca token info <category> # Token metadata, balance,
111
113
  paytaca token price <category> [amount] # USD price of a token and value of an amount (default: balance)
112
114
  paytaca token send <address> <amount> --token <cat> # Send fungible tokens
113
115
  paytaca token send-nft <address> --token <cat> --commitment <hex> # Send an NFT
116
+ paytaca token send-nft <address> --token <cat> --commitment '' --capability minting
114
117
  ```
115
118
 
119
+ `token send-nft` also accepts `--capability <none|minting|mutable>` (default `none`), and `--txid` / `--vout` to pin a specific NFT UTXO (auto-detected otherwise).
120
+
116
121
  ### Swap (Cauldron DEX)
117
122
 
118
123
  ```bash
@@ -122,19 +127,23 @@ paytaca swap <tokenId> <amount> --raw # Amount is in raw base units
122
127
  paytaca swap <tokenId> <amount> --yes # Skip the confirmation prompt
123
128
  ```
124
129
 
125
- The `--action` option is `sell` (token→BCH) or `buy` (BCH→token). Swaps run on mainnet only.
130
+ The `--action` option is `sell` (token→BCH) or `buy` (BCH→token). Swaps run on mainnet only; `--chipnet` is accepted but exits with an error.
126
131
 
127
132
  ### x402 Payments
128
133
 
129
134
  The x402 protocol enables HTTP payments via BCH. Some APIs require payment to access.
130
135
 
131
136
  ```bash
132
- paytaca check <url> # Check if URL requires payment, shows estimated cost
133
- paytaca pay <url> # Make a paid HTTP request (handles 402 automatically)
134
- paytaca pay <url> --json # JSON output (recommended for AI agents)
135
- paytaca pay <url> --dry-run # Preview payment without executing
136
- paytaca pay <url> --method POST # POST request with body
137
- paytaca pay <url> --body '{"prompt":"hello"}'
137
+ paytaca check <url> # Check if URL requires payment, shows estimated cost
138
+ paytaca check <url> -X POST -d '{}' # Check a POST endpoint (-X/--method, -H/--header, -d/--body)
139
+ paytaca pay <url> # Make a paid HTTP request (handles 402 automatically)
140
+ paytaca pay <url> --json # JSON output (recommended for AI agents)
141
+ paytaca pay <url> --dry-run # Preview payment without executing
142
+ paytaca pay <url> -X POST -d '{"prompt":"hello"}'
143
+ paytaca pay <url> --max-amount 500 # Cap payment in sats (overrides server max)
144
+ paytaca pay <url> --change-address <addr> # Custom change address
145
+ paytaca pay <url> --payer <value> # Payer identifier (defaults to wallet index 0)
146
+ paytaca pay <url> --confirmed # Skip the confirmation prompt
138
147
  ```
139
148
 
140
149
  **Example workflow:**
@@ -146,34 +155,121 @@ paytaca pay https://api.example.com/v1/complete --method POST --body '{"prompt":
146
155
  # → Handles 402 → pays → returns response
147
156
  ```
148
157
 
149
- ### AI Agent Integration
158
+ ### Update
159
+
160
+ ```bash
161
+ paytaca update # Update paytaca-cli to the latest version on npm
162
+ paytaca update --check # Only check for updates; do not install
163
+ paytaca update --registry <url> # Override the npm registry URL
164
+ ```
165
+
166
+ Compares the installed version against the latest published version on npm and, when behind, runs `npm install -g paytaca-cli@latest`. Pass `--check` to see available updates without installing.
167
+
168
+ ### Paytaca AI
169
+
170
+ Paytaca AI is a pay-as-you-go model gateway paid with BCH or LIFT via x402. Manage it from the CLI:
171
+
172
+ ```bash
173
+ paytaca ai configure [harness] # Install MCP + AI provider (opencode is the default)
174
+ paytaca ai api-key create # Create a wallet-bound API key (shown once)
175
+ paytaca ai models # List available models
176
+ paytaca ai plans [model] # Plan pricing, optionally for a single model
177
+ paytaca ai credits [--model <id>] # Remaining time credits per model
178
+ paytaca ai usage # Per-session usage
179
+ paytaca ai balance # BCH + LIFT funds available for purchases
180
+ paytaca ai purchase --model <id> --minutes <n> # Buy a plan
181
+ paytaca ai purchase --model <id> --minutes 60 --lift # Pay with LIFT (discount)
182
+ paytaca ai auto-refill --enable --model <id> --minutes <n> --max-minutes <n>
183
+ paytaca ai auto-refill --status # Inspect; also --disable, --delete
184
+ ```
185
+
186
+ `ai configure` accepts `--backend`, `--path`, `--api-key`, `--chipnet`, and `-y/--yes`. `ai purchase` and `ai auto-refill` accept `--lift` to pay with LIFT tokens at a discount. Add `--json` to any `ai` subcommand for machine-readable output.
187
+
188
+ Armed auto-refill state lives at `~/.paytaca/auto-refill.json`. It runs inline — arming performs one immediate check (buying right away if the armed model has no credits), the `get_credits` MCP tool refills on demand, and the `paytaca mcp` server keeps a background backstop while a session is running. Each execution is appended to `~/.paytaca/auto-refill-events.jsonl` and the latest is reported as `lastEvent`. It disarms when the budget is spent, funds are short, or the plan is no longer offered. Use `--disable` to pause and `--delete` to remove the configuration (history is kept).
150
189
 
151
- Paytaca CLI provides AI agent skills for wallet operations. Install from GitHub (supports 45+ AI frameworks):
190
+ ### Image Generation
191
+
192
+ Generate images with AI models, paid in BCH on-chain:
152
193
 
153
194
  ```bash
154
- # Install specific skill
155
- npx skills add paytaca/paytaca-cli --skill <skill-name> -a <agent> -g
195
+ paytaca ai image models # List available image models
196
+ paytaca ai image generate "a green phoenix" # Generate an image from a prompt
197
+ paytaca ai image generate "prompt" --model <id> # Specify model (defaults to cheapest)
198
+ paytaca ai image generate "prompt" --aspect-ratio 16:9 # Aspect ratio (default: 1:1)
199
+ paytaca ai image generate "prompt" --quality high # Quality: low, medium, high, auto
200
+ paytaca ai image generate "prompt" --resolution 2K # Resolution: 512, 1K, 2K, 4K
201
+ paytaca ai image generate "prompt" --yes # Skip confirmation prompt
202
+ paytaca ai image history # Show order history
203
+ paytaca ai image history --page 2 # Paginate history
204
+ paytaca ai image status <order-id> # Poll a pending generation order
205
+ ```
156
206
 
157
- # Install all skills
158
- npx skills add paytaca/paytaca-cli --all
207
+ Image generation uses a two-phase flow: an order is created (returning a CashScript contract address and sats price), BCH is paid on-chain, the backend confirms payment via Watchtower, generation runs server-side, and the finished image is saved under `~/.paytaca/images/`. Use `image status` to resume if a generation is still processing when the initial request returns.
159
208
 
160
- # Examples
161
- npx skills add paytaca/paytaca-cli --skill paytaca-x402 -a opencode -g
162
- npx skills add paytaca/paytaca-cli --skill paytaca-wallet -a claude-code -g
163
- npx skills add paytaca/paytaca-cli --skill paytaca-send -a openclaw -g
209
+ ### MCP Server
210
+
211
+ Configure an AI harness in one step. This installs the Paytaca MCP server and, for opencode, also the Paytaca AI provider (model catalogue + API key) so the Paytaca AI models are usable immediately:
212
+
213
+ ```bash
214
+ paytaca ai configure opencode # opencode | pi | omp
164
215
  ```
165
216
 
166
- **Available Skills:**
217
+ The command creates a wallet-bound API key against the Paytaca AI backend, writes the provider (base URL, models, key) and MCP server into the harness config, then checks your AI credits and offers to buy a plan when none are active.
167
218
 
168
- | Skill | Purpose | Approval Needed |
169
- |-------|---------|------------------|
170
- | `paytaca-x402` | HTTP 402 payment handling | Yes (before payment) |
171
- | `paytaca-wallet` | Balance, addresses, history, token info | No (read-only) |
172
- | `paytaca-send` | Send BCH and CashTokens | Yes (before sending) |
219
+ Re-running is idempotent: an existing provider API key is reused. Then run the server over stdio:
173
220
 
174
- **Supported frameworks:** OpenCode, Claude Code, OpenClaw, Cursor, Cline, Windsurf, Roo, Gemini CLI, Codex, GitHub Copilot, Goose, Trae, Kiro CLI, and 30+ more.
221
+ ```bash
222
+ paytaca mcp # mainnet
223
+ paytaca mcp --chipnet # default MCP tools to chipnet (testnet)
224
+ ```
175
225
 
176
- See [skills/README.md](skills/README.md) for detailed skill documentation.
226
+ **Read-only wallets:** if the active wallet cannot sign (no seed phrase in the keychain), `ai configure` asks for an API key instead of creating one. Generate it from your full wallet and hand it over:
227
+
228
+ ```bash
229
+ paytaca ai api-key create # full wallet: prints sk-pytc-… once
230
+ paytaca ai configure opencode --api-key sk-pytc-… # read-only wallet
231
+ ```
232
+
233
+ Read-only wallets report credits from the shared wallet hash but can't buy plans — fund credits from the full wallet.
234
+
235
+ **MCP tools:** wallet reads (`get_balance`, `get_transactions`, `get_receiving_address`, `get_tokens`, `send`) plus Paytaca AI (`get_models`, `get_plans`, `get_credits`, `buy_plan`, `auto_refill`, `get_help`, `generate_image`, `get_image_status`, `get_image_models`, `get_image_history`).
236
+
237
+ Spending tools (`send`, `buy_plan`, `auto_refill`, `generate_image`) require host-level approval. By default MCP operates on your **main wallet** and can spend real funds.
238
+
239
+ When `get_credits` finds a model with no active session (e.g. after a `402` from the Paytaca AI provider), the result includes a `purchaseHint`. Relay `purchaseHint.message` as-is — it carries the exact copy-paste top-up command (no upsell or follow-up questions needed):
240
+
241
+ ```json
242
+ {
243
+ "modelId": "deepseek/deepseek-v4.1-flash",
244
+ "active": false,
245
+ "purchaseHint": {
246
+ "model": "deepseek/deepseek-v4.1-flash",
247
+ "minutes": 15,
248
+ "command": "paytaca ai purchase --model deepseek/deepseek-v4.1-flash --minutes 15",
249
+ "message": "To keep using DeepSeek V4.1 Flash, top up by running this in a terminal:\n\n paytaca ai purchase --model deepseek/deepseek-v4.1-flash --minutes 15\n\n(Switch models with `paytaca ai plans`.)"
250
+ }
251
+ }
252
+ ```
253
+
254
+ ### Nostr Chat
255
+
256
+ End-to-end encrypted Nostr chat keyed from the wallet mnemonic (HD path `m/44'/1237'/0'/0/0`; keys are derived in memory and never stored). Conversation metadata (contacts, rooms, messages) is persisted at `~/.paytaca/chat-state.json`.
257
+
258
+ ```bash
259
+ paytaca chat identity # Show your npub and pubkey
260
+ paytaca chat profile # Show display name and published BCH address
261
+ paytaca chat contacts # List saved contacts
262
+ paytaca chat add-contact <npub> [name] # Add a contact
263
+ paytaca chat start <npub> # Start a 1:1 conversation
264
+ paytaca chat list # List conversations
265
+ paytaca chat open <room-id> --tail 20 # Show recent messages (--tail, --json)
266
+ paytaca chat send <room-id> <text> # Send a message
267
+ paytaca chat listen [--contact <npub|name>] # Subscribe to new messages (long-running)
268
+ paytaca chat set-display-name <name> # Publish profile name to relays (NIP-78)
269
+ paytaca chat set-bch-address <address> # Publish a BCH address to relays (NIP-78)
270
+ paytaca chat remove-display-name # Remove published name
271
+ paytaca chat remove-bch-address # Remove published address
272
+ ```
177
273
 
178
274
  ## Network
179
275
 
@@ -195,6 +291,8 @@ Seed phrases are stored in the OS native keychain:
195
291
 
196
292
  Powered by [@napi-rs/keyring](https://github.com/Brooooooklyn/keyring-node) (prebuilt Rust binaries, no node-gyp required).
197
293
 
294
+ Nostr chat keys are **not** persisted — they are re-derived from the wallet mnemonic at runtime via HD path `m/44'/1237'/0'/0/0` and held only in memory for the duration of a session. Non-secret chat metadata (contacts, rooms, messages) is written to `~/.paytaca/chat-state.json` with mode `0600`; no key material is ever written there.
295
+
198
296
  ## Architecture
199
297
 
200
298
  ```
@@ -210,20 +308,51 @@ src/
210
308
  swap.ts Cauldron DEX swaps (sell/buy with --action)
211
309
  pay.ts x402 BCH payment handler for HTTP requests
212
310
  check.ts Check if URL requires x402 payment
311
+ ai.ts Paytaca AI (configure, api-key, models, plans, credits, purchase, auto-refill, image)
312
+ chat.ts Nostr chat (contacts, conversations, identity, listen)
313
+ mcp.ts `paytaca mcp` stdio entry + per-harness config templates
314
+ update.ts Self-update from npm registry
315
+ core/
316
+ context.ts Wallet context resolution (keychain + network), embed-safe
317
+ wallet.ts Render-agnostic wallet ops shared by CLI and MCP tools
318
+ mcp/
319
+ server.ts MCP server construction and stdio lifecycle
320
+ tools.ts MCP tool registration (wallet reads, send, Paytaca AI)
213
321
  wallet/
214
322
  index.ts Wallet class, mnemonic gen/import/load
215
323
  bch.ts BchWallet (balance, send, history, CashTokens)
216
324
  keys.ts LibauthHDWallet (HD key derivation, token addresses)
217
325
  x402.ts X402Payer (BCH payment signing and verification)
326
+ cauldron/
327
+ api.ts Cauldron (riften indexer) REST client
328
+ pools.ts Pool conversions and helpers
329
+ swap.ts Swap orchestration: quote estimation and execution
330
+ transact.ts Cauldron trade transaction building
218
331
  storage/
219
332
  keychain.ts OS keychain wrapper (@napi-rs/keyring)
220
333
  utils/
221
334
  crypto.ts pubkey -> CashAddress pipeline
335
+ format.ts Shared display/formatting helpers
222
336
  network.ts Watchtower URLs, derivation paths
223
337
  prices.ts Watchtower asset-prices client (USD per token/BCH)
224
338
  x402.ts x402 header parsing, payment requirement selection
225
339
  types/
226
340
  x402.ts x402 payment types (PaymentRequired, PaymentPayload, etc.)
341
+ ai/
342
+ client.ts Paytaca AI backend client (config, wallet status)
343
+ config.ts Backend URL, LIFT token id, ~/.paytaca paths
344
+ oauth.ts BCH OAuth challenge -> access token -> API key
345
+ models.ts Model catalogue, plan tiers, price/duration helpers
346
+ credits.ts Credit session lookup and summaries
347
+ images.ts Image generation client, order orchestration, polling
348
+ purchase.ts Plan purchase via x402 (BCH or LIFT)
349
+ autoRefill.ts Auto-refill state and orchestration
350
+ configure.ts Harness setup (MCP + Paytaca AI provider + credits offer)
351
+ nostr/
352
+ keys.ts Nostr key derivation from wallet mnemonic (in memory)
353
+ chat.ts DM event building/signing (NIP-17 style)
354
+ relay.ts Relay connection/subscription service
355
+ store.ts Contact/room/message JSON store (~/.paytaca)
227
356
  ```
228
357
 
229
358
  ## Key Dependencies
@@ -232,35 +361,55 @@ src/
232
361
  |---------|---------|
233
362
  | `watchtower-cash-js` | UTXO fetching, tx building/signing/broadcasting |
234
363
  | `@bitauth/libauth` | HD key derivation (pinned to 2.0.0-alpha.8) |
364
+ | `@cashlab/cauldron` | Cauldron DEX swap building |
235
365
  | `@napi-rs/keyring` | OS-native keychain storage |
366
+ | `@modelcontextprotocol/sdk` | MCP server (stdio) |
236
367
  | `bip39` | Mnemonic generation and validation |
368
+ | `nostr-tools` | Nostr chat events, keys, and relay transport |
369
+ | `js-sha256` | Hashing for key derivation and payment headers |
237
370
  | `commander` | CLI framework |
238
371
  | `chalk` | Terminal colors |
239
372
  | `qrcode-terminal` | Terminal QR code rendering |
373
+ | `zod` | MCP tool input schemas |
240
374
 
241
375
  ## Development
242
376
 
243
377
  ```bash
244
378
  npm run dev # Watch mode (recompile on change)
245
- npm run build # One-time build
379
+ npm run build # One-time build (also type-checks)
380
+ npm test # Run the Vitest suite
246
381
  npm run clean # Remove dist/
247
382
  ```
248
383
 
384
+ There is no lint script; `npm run build` is the type-check. Tests live next to sources as `*.test.ts`.
385
+
249
386
  ## x402 Server
250
387
 
251
- A reference x402 server implementation is included for testing:
388
+ A reference x402 server accepting BCH (the `utxo` scheme) is included for testing:
252
389
 
253
390
  ```bash
254
391
  cd x402-server
255
392
  npm install
256
- npm run dev # Start dev server on port 3001
393
+ npm run dev # Start dev server on port 3000 (npm start to run once)
257
394
  ```
258
395
 
259
- The server implements the x402-bch v2.2 specification and provides:
260
- - `GET /api/quote` — Returns a quote (requires payment)
261
- - `POST /api/generate` Text generation endpoint (requires payment)
396
+ Configuration via environment variables:
397
+
398
+ | Variable | Description | Default |
399
+ |----------|-------------|---------|
400
+ | `PORT` | Server port | `3000` |
401
+ | `BCH_NETWORK` | `mainnet` or `chipnet` | `mainnet` |
402
+ | `RECEIVE_ADDRESS` | BCH address to receive payments | required for real payments |
403
+
404
+ The server exposes:
405
+
406
+ | Endpoint | Cost | Description |
407
+ |----------|------|-------------|
408
+ | `GET /api/quote` | 100 sats | Random inspirational quote |
409
+ | `GET /api/weather` | 50 sats | Fake weather data |
410
+ | `GET /api/status` | 1 sat | Server status |
262
411
 
263
- Useful for testing the `paytaca pay` workflow locally.
412
+ Useful for testing the `paytaca check` / `paytaca pay` workflow locally (see `x402-server/README.md` for the header-level protocol details).
264
413
 
265
414
  ## License
266
415
 
@@ -0,0 +1,85 @@
1
+ export type PaymentMethod = 'bch' | 'lift';
2
+ export interface RefillLastEvent {
3
+ action: 'refilled' | 'disarmed';
4
+ reason: string | null;
5
+ at: string;
6
+ txid: string | null;
7
+ status: 'completed' | 'failed';
8
+ }
9
+ export interface RefillEvent extends RefillLastEvent {
10
+ model: string | null;
11
+ minutes: number | null;
12
+ priceSats: number | null;
13
+ paymentMethod: PaymentMethod | null;
14
+ }
15
+ export interface AutoRefillState {
16
+ enabled: boolean;
17
+ model?: string;
18
+ minutes?: number;
19
+ maxMinutes?: number;
20
+ spentMinutes?: number;
21
+ refillCount?: number;
22
+ paymentMethod?: PaymentMethod;
23
+ startedAt?: string;
24
+ lastRefillAt?: string;
25
+ lastRefillTxid?: string | null;
26
+ lastEvent?: RefillLastEvent;
27
+ }
28
+ export declare function readAutoRefillState(): AutoRefillState | null;
29
+ export declare function writeAutoRefillState(state: AutoRefillState): void;
30
+ export declare function appendAutoRefillEvent(event: RefillEvent, file?: string): void;
31
+ export declare function deleteAutoRefill(file?: string): boolean;
32
+ export interface ArmAutoRefillOptions {
33
+ model?: string;
34
+ minutes?: number;
35
+ maxMinutes?: number;
36
+ paymentMethod?: PaymentMethod;
37
+ }
38
+ export declare function armAutoRefill(opts: ArmAutoRefillOptions): AutoRefillState;
39
+ export declare function disarmAutoRefill(): AutoRefillState;
40
+ export declare function remainingBudget(state: AutoRefillState | null): number | null;
41
+ export declare function autoRefillCanBuy(state: AutoRefillState | null, model: string, minutes: number): {
42
+ canBuy: boolean;
43
+ reason?: string;
44
+ };
45
+ export declare const REFILL_COOLDOWN_MS: number;
46
+ export interface RefillBuyOptions {
47
+ model: string;
48
+ minutes: number;
49
+ paymentMethod: PaymentMethod;
50
+ }
51
+ export interface RefillBuyResult {
52
+ success: boolean;
53
+ paid?: boolean;
54
+ txid?: string;
55
+ priceSats?: number;
56
+ error?: string;
57
+ }
58
+ export interface RefillTickDeps {
59
+ hasActiveCredits: (model: string) => Promise<boolean>;
60
+ buy: (opts: RefillBuyOptions) => Promise<RefillBuyResult>;
61
+ readState?: () => AutoRefillState | null;
62
+ writeState?: (state: AutoRefillState) => void;
63
+ appendEvent?: (event: RefillEvent) => void;
64
+ now?: () => number;
65
+ }
66
+ export type RefillTickResult = {
67
+ action: 'idle';
68
+ } | {
69
+ action: 'skipped';
70
+ reason: string;
71
+ } | {
72
+ action: 'refilled';
73
+ state: AutoRefillState;
74
+ } | {
75
+ action: 'disarmed';
76
+ reason: string;
77
+ state: AutoRefillState;
78
+ };
79
+ export declare function autoRefillTick(deps: RefillTickDeps): Promise<RefillTickResult>;
80
+ export interface RefillLoopOptions extends RefillTickDeps {
81
+ intervalMs?: number;
82
+ onEvent?: (result: RefillTickResult) => void;
83
+ }
84
+ export declare function startAutoRefillLoop(opts: RefillLoopOptions): () => void;
85
+ //# sourceMappingURL=autoRefill.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"autoRefill.d.ts","sourceRoot":"","sources":["../../src/ai/autoRefill.ts"],"names":[],"mappings":"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"}