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.
- package/README.md +183 -34
- package/dist/ai/autoRefill.d.ts +85 -0
- package/dist/ai/autoRefill.d.ts.map +1 -0
- package/dist/ai/autoRefill.js +266 -0
- package/dist/ai/autoRefill.js.map +1 -0
- package/dist/ai/client.d.ts +73 -0
- package/dist/ai/client.d.ts.map +1 -0
- package/dist/ai/client.js +90 -0
- package/dist/ai/client.js.map +1 -0
- package/dist/ai/config.d.ts +8 -0
- package/dist/ai/config.d.ts.map +1 -0
- package/dist/ai/config.js +17 -0
- package/dist/ai/config.js.map +1 -0
- package/dist/ai/configure.d.ts +61 -0
- package/dist/ai/configure.d.ts.map +1 -0
- package/dist/ai/configure.js +452 -0
- package/dist/ai/configure.js.map +1 -0
- package/dist/ai/credits.d.ts +27 -0
- package/dist/ai/credits.d.ts.map +1 -0
- package/dist/ai/credits.js +108 -0
- package/dist/ai/credits.js.map +1 -0
- package/dist/ai/images.d.ts +128 -0
- package/dist/ai/images.d.ts.map +1 -0
- package/dist/ai/images.js +399 -0
- package/dist/ai/images.js.map +1 -0
- package/dist/ai/models.d.ts +13 -0
- package/dist/ai/models.d.ts.map +1 -0
- package/dist/ai/models.js +49 -0
- package/dist/ai/models.js.map +1 -0
- package/dist/ai/oauth.d.ts +45 -0
- package/dist/ai/oauth.d.ts.map +1 -0
- package/dist/ai/oauth.js +137 -0
- package/dist/ai/oauth.js.map +1 -0
- package/dist/ai/purchase.d.ts +30 -0
- package/dist/ai/purchase.d.ts.map +1 -0
- package/dist/ai/purchase.js +456 -0
- package/dist/ai/purchase.js.map +1 -0
- package/dist/commands/address.d.ts.map +1 -1
- package/dist/commands/address.js +86 -47
- package/dist/commands/address.js.map +1 -1
- package/dist/commands/ai.d.ts +9 -0
- package/dist/commands/ai.d.ts.map +1 -0
- package/dist/commands/ai.js +951 -0
- package/dist/commands/ai.js.map +1 -0
- package/dist/commands/balance.d.ts.map +1 -1
- package/dist/commands/balance.js +68 -129
- package/dist/commands/balance.js.map +1 -1
- package/dist/commands/history.d.ts.map +1 -1
- package/dist/commands/history.js +38 -78
- package/dist/commands/history.js.map +1 -1
- package/dist/commands/mcp.d.ts +14 -0
- package/dist/commands/mcp.d.ts.map +1 -0
- package/dist/commands/mcp.js +68 -0
- package/dist/commands/mcp.js.map +1 -0
- package/dist/commands/pay.js +1 -1
- package/dist/commands/pay.js.map +1 -1
- package/dist/commands/receive.d.ts +1 -8
- package/dist/commands/receive.d.ts.map +1 -1
- package/dist/commands/receive.js +51 -124
- package/dist/commands/receive.js.map +1 -1
- package/dist/commands/send.d.ts +0 -10
- package/dist/commands/send.d.ts.map +1 -1
- package/dist/commands/send.js +40 -50
- package/dist/commands/send.js.map +1 -1
- package/dist/commands/swap.js +1 -1
- package/dist/commands/swap.js.map +1 -1
- package/dist/commands/token.d.ts +1 -9
- package/dist/commands/token.d.ts.map +1 -1
- package/dist/commands/token.js +192 -289
- package/dist/commands/token.js.map +1 -1
- package/dist/commands/update.d.ts +32 -0
- package/dist/commands/update.d.ts.map +1 -0
- package/dist/commands/update.js +200 -0
- package/dist/commands/update.js.map +1 -0
- package/dist/commands/wallet.js +1 -1
- package/dist/commands/wallet.js.map +1 -1
- package/dist/commands/web.d.ts +3 -0
- package/dist/commands/web.d.ts.map +1 -0
- package/dist/commands/web.js +71 -0
- package/dist/commands/web.js.map +1 -0
- package/dist/core/context.d.ts +30 -0
- package/dist/core/context.d.ts.map +1 -0
- package/dist/core/context.js +45 -0
- package/dist/core/context.js.map +1 -0
- package/dist/core/wallet.d.ts +130 -0
- package/dist/core/wallet.d.ts.map +1 -0
- package/dist/core/wallet.js +276 -0
- package/dist/core/wallet.js.map +1 -0
- package/dist/index.js +8 -0
- package/dist/index.js.map +1 -1
- package/dist/mcp/server.d.ts +8 -0
- package/dist/mcp/server.d.ts.map +1 -0
- package/dist/mcp/server.js +52 -0
- package/dist/mcp/server.js.map +1 -0
- package/dist/mcp/tools.d.ts +7 -0
- package/dist/mcp/tools.d.ts.map +1 -0
- package/dist/mcp/tools.js +752 -0
- package/dist/mcp/tools.js.map +1 -0
- package/dist/utils/format.d.ts +23 -0
- package/dist/utils/format.d.ts.map +1 -0
- package/dist/utils/format.js +62 -0
- package/dist/utils/format.js.map +1 -0
- package/dist/utils/x402.js +1 -1
- package/dist/utils/x402.js.map +1 -1
- package/dist/wallet/cauldron/swap.d.ts +15 -0
- package/dist/wallet/cauldron/swap.d.ts.map +1 -1
- package/dist/wallet/cauldron/swap.js +31 -0
- package/dist/wallet/cauldron/swap.js.map +1 -1
- package/dist/wallet/index.d.ts +29 -1
- package/dist/wallet/index.d.ts.map +1 -1
- package/dist/wallet/index.js +92 -8
- package/dist/wallet/index.js.map +1 -1
- package/dist/wallet/keys.d.ts.map +1 -1
- package/dist/wallet/keys.js +2 -0
- package/dist/wallet/keys.js.map +1 -1
- package/dist/web/assets.d.ts +3 -0
- package/dist/web/assets.d.ts.map +1 -0
- package/dist/web/assets.js +3 -0
- package/dist/web/assets.js.map +1 -0
- package/dist/web/page.d.ts +2 -0
- package/dist/web/page.d.ts.map +1 -0
- package/dist/web/page.js +637 -0
- package/dist/web/page.js.map +1 -0
- package/dist/web/server.d.ts +79 -0
- package/dist/web/server.d.ts.map +1 -0
- package/dist/web/server.js +665 -0
- package/dist/web/server.js.map +1 -0
- package/package.json +8 -3
- package/dist/commands/wallet.test.d.ts +0 -2
- package/dist/commands/wallet.test.d.ts.map +0 -1
- package/dist/commands/wallet.test.js +0 -68
- package/dist/commands/wallet.test.js.map +0 -1
- package/dist/nostr/chat.test.d.ts +0 -2
- package/dist/nostr/chat.test.d.ts.map +0 -1
- package/dist/nostr/chat.test.js +0 -121
- package/dist/nostr/chat.test.js.map +0 -1
- package/dist/nostr/store.test.d.ts +0 -2
- package/dist/nostr/store.test.d.ts.map +0 -1
- package/dist/nostr/store.test.js +0 -456
- package/dist/nostr/store.test.js.map +0 -1
- package/dist/utils/prices.test.d.ts +0 -5
- package/dist/utils/prices.test.d.ts.map +0 -1
- package/dist/utils/prices.test.js +0 -62
- package/dist/utils/prices.test.js.map +0 -1
- package/dist/utils/x402.test.d.ts +0 -2
- package/dist/utils/x402.test.d.ts.map +0 -1
- package/dist/utils/x402.test.js +0 -216
- package/dist/utils/x402.test.js.map +0 -1
- package/dist/wallet/cauldron/pools.test.d.ts +0 -3
- package/dist/wallet/cauldron/pools.test.d.ts.map +0 -1
- package/dist/wallet/cauldron/pools.test.js +0 -149
- package/dist/wallet/cauldron/pools.test.js.map +0 -1
- package/dist/wallet/cauldron/swap.test.d.ts +0 -2
- package/dist/wallet/cauldron/swap.test.d.ts.map +0 -1
- package/dist/wallet/cauldron/swap.test.js +0 -179
- package/dist/wallet/cauldron/swap.test.js.map +0 -1
- package/skills/README.md +0 -68
- package/skills/paytaca-send/SKILL.md +0 -159
- package/skills/paytaca-wallet/SKILL.md +0 -164
- 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>
|
|
133
|
-
paytaca
|
|
134
|
-
paytaca pay <url>
|
|
135
|
-
paytaca pay <url> --
|
|
136
|
-
paytaca pay <url> --
|
|
137
|
-
paytaca pay <url>
|
|
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
|
-
###
|
|
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
|
-
|
|
190
|
+
### Image Generation
|
|
191
|
+
|
|
192
|
+
Generate images with AI models, paid in BCH on-chain:
|
|
152
193
|
|
|
153
194
|
```bash
|
|
154
|
-
#
|
|
155
|
-
|
|
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
|
-
|
|
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
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
221
|
+
```bash
|
|
222
|
+
paytaca mcp # mainnet
|
|
223
|
+
paytaca mcp --chipnet # default MCP tools to chipnet (testnet)
|
|
224
|
+
```
|
|
175
225
|
|
|
176
|
-
|
|
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
|
|
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
|
|
393
|
+
npm run dev # Start dev server on port 3000 (npm start to run once)
|
|
257
394
|
```
|
|
258
395
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
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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"}
|