paytaca-cli 0.6.1 → 0.7.0

package/skills/README.md

@@ -1,68 +0,0 @@
-# Paytaca CLI Skills
-
-This directory contains AI agent skills for the Paytaca CLI.
-
-## Available Skills
-
-### paytaca-x402
-
-Handles x402 HTTP payment requests using Paytaca BCH wallet. Use when encountering HTTP 402 responses or when calling APIs that may require payment via the x402 protocol.
-
-```bash
-npx skills add paytaca/paytaca-cli --skill paytaca-x402 -a <agent> -g
-```
-
-### paytaca-wallet
-
-Query wallet information including BCH balance, CashToken holdings, addresses, and transaction history. Use for read-only wallet operations.
-
-```bash
-npx skills add paytaca/paytaca-cli --skill paytaca-wallet -a <agent> -g
-```
-
-### paytaca-send
-
-Send BCH and CashTokens from the wallet. **Requires user approval** before any sending operation.
-
-```bash
-npx skills add paytaca/paytaca-cli --skill paytaca-send -a <agent> -g
-```
-
-## Installation
-
-Install specific skill:
-```bash
-npx skills add paytaca/paytaca-cli --skill <skill-name> -a <agent> -g
-```
-
-Install all skills:
-```bash
-npx skills add paytaca/paytaca-cli --all
-```
-
-List available skills:
-```bash
-npx skills add paytaca/paytaca-cli --list
-```
-
-## Skill Overview
-
-| Skill | Purpose | Approval Needed |
-|-------|---------|-----------------|
-| paytaca-x402 | HTTP 402 payment handling | Yes (before payment) |
-| paytaca-wallet | Balance, addresses, history, token info | No (read-only) |
-| paytaca-send | Send BCH and tokens | Yes (before sending) |
-
-## Adding New Skills
-
-To add a new skill:
-
-1. Create a new directory: `skills/<skill-name>/`
-2. Add a `SKILL.md` file with YAML frontmatter:
-   ```yaml
-   ---
-   name: <skill-name>
-   description: What this skill does and when to use it
-   ---
-   ```
-3. Write the skill instructions below the frontmatter

package/skills/paytaca-send/SKILL.md

@@ -1,159 +0,0 @@
----
-name: paytaca-send
-description: Send BCH and CashTokens from the wallet. REQUIRES USER APPROVAL before any sending operation.
----
-
-# Paytaca Send
-
-This skill handles sending BCH and CashTokens. **All sending operations require explicit user approval before execution.**
-
-## ⚠️ User Approval Required
-
-**CRITICAL**: The agent MUST NOT execute any `paytaca send` or `paytaca token send` command without first:
-1. Informing the user of the exact amount and recipient
-2. Waiting for explicit user confirmation (e.g., "yes", "send it", "confirm")
-3. Only then executing the send command
-
-These commands spend real funds from the user's wallet.
-
----
-
-## Send BCH
-
-```bash
-# Basic send (BCH amount)
-paytaca send <address> <amount>
-
-# Send in satoshis
-paytaca send <address> 50000 --unit sats
-
-# Testnet (chipnet)
-paytaca send <address> 0.001 --chipnet
-```
-
-### Example Workflow
-```
-Agent: I'll send 0.001 BCH to bitcoincash:qpm5... 
-Confirm? (This will spend real funds)
-
-User: yes
-
-Agent: paytaca send bitcoincash:qpm5... 0.001
-  → Transaction sent: txid...
-```
-
----
-
-## Send Fungible Tokens
-
-```bash
-# Send tokens (amount in base units)
-paytaca token send <address> <amount> --token <category>
-
-# Example: Send 1000 units of a token
-paytaca token send bitcoincash:zpm5... 1000 --token abc123...
-```
-
-**Note**: Token amounts are in base units. If a token has 8 decimals, sending `1` token requires `100000000` base units.
-
-### Token Address Warning
-Tokens should be sent to token-aware (z-prefix) addresses. The CLI will warn if the recipient address is not token-aware.
-
----
-
-## Send NFTs
-
-```bash
-# Send NFT (auto-detect UTXO)
-paytaca token send-nft <address> --token <category> --commitment <hex>
-
-# Example: Send NFT with empty commitment
-paytaca token send-nft bitcoincash:zpm5... --token abc123... --commitment ""
-
-# With capability (minting or mutable)
-paytaca token send-nft <address> --token <category> --commitment <hex> --capability minting
-```
-
-### Find NFT details
-```bash
-# List NFTs for a token category
-paytaca token info <category>
-```
-
----
-
-## Network
-
-All commands default to **mainnet**. Use `--chipnet` for testnet:
-
-```bash
-paytaca send <address> 0.01 --chipnet
-paytaca token send <address> 100 --token <cat> --chipnet
-paytaca token send-nft <address> --token <cat> --commitment "" --chipnet
-```
-
----
-
-## Decision Flow
-
-When user requests to send funds:
-
-1. **Validate inputs**: Check address format and amount
-2. **Inform user**: State the exact amount, recipient, and network
-3. **Wait for approval**: Ask "Send X [BCH/tokens] to <address>? Confirm?"
-4. **Execute**: Only after explicit approval
-
-### Example: Sending BCH
-```
-User: Send 0.01 BCH to bitcoincash:qpm5qz6j5p5s5s5s5s5s5s5s5s5s5s5s5s5
-
-Agent: Checking wallet balance...
-paytaca balance
-
-Agent: Balance: 0.5 BCH
-Sending 0.01 BCH to bitcoincash:qpm5qz6j5p5s5s5s5s5s5s5s5s5s5s5s5s
-Confirm? (yes/no)
-
-User: yes
-
-Agent: paytaca send bitcoincash:qpm5qz6j5p5s5s5s5s5s5s5s5s5s5s5s5s 0.01
-  → Transaction sent!
-  txid: abc123...
-```
-
-### Example: Sending Tokens
-```
-User: Send 1000 tokens to bitcoincash:zpm5...
-
-Agent: Let me check your token balance first...
-paytaca token info <category>
-
-Agent: You have 5000 tokens.
-Sending 1000 base units to bitcoincash:zpm5...
-Confirm? (yes/no)
-
-User: yes
-
-Agent: paytaca token send bitcoincash:zpm5... 1000 --token <category>
-  → Transaction sent!
-```
-
----
-
-## Error Handling
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| `Insufficient balance` | Not enough BCH | Check `paytaca balance` first |
-| `Insufficient BCH for fees` | Can't afford tx fee | Need more BCH for miner fee |
-| `Invalid address` | Bad address format | Use CashAddr format |
-| `Token not found` | Unknown category | Check token category ID |
-
----
-
-## Security Notes
-
-- Seed phrase is stored in OS keychain (never transmitted)
-- Transactions are signed locally
-- Always verify recipient address before confirming
-- Test with small amounts on mainnet, or use `--chipnet` for testing

package/skills/paytaca-wallet/SKILL.md

@@ -1,164 +0,0 @@
----
-name: paytaca-wallet
-description: Query wallet information including BCH balance, CashToken holdings, addresses, and transaction history. Use for read-only wallet operations.
----
-
-# Paytaca Wallet Info
-
-This skill provides read-only access to wallet information via the Paytaca CLI.
-
-## Commands
-
-### Check Balance
-
-```bash
-# BCH balance
-paytaca balance
-
-# Balance in satoshis
-paytaca balance --sats
-
-# CashToken balances only (positive balances)
-paytaca balance --tokens
-
-# BCH and CashToken balances
-paytaca balance --all
-
-# Balance for a specific token
-paytaca balance --token <category>
-
-# Testnet (chipnet)
-paytaca balance --chipnet
-```
-
-### View Transaction History
-
-```bash
-# Recent transactions
-paytaca history
-
-# Filter by type
-paytaca history --type incoming
-paytaca history --type outgoing
-
-# Filter by token
-paytaca history --token <category>
-
-# Pagination
-paytaca history --page 2
-
-# Satoshis display
-paytaca history --sats
-```
-
-### Get Receiving Address
-
-```bash
-# BCH address with QR code
-paytaca receive
-
-# Address at specific index
-paytaca receive --index 5
-
-# Address only (no QR)
-paytaca receive --no-qr
-
-# Token-aware address (z-prefix)
-paytaca receive --token
-
-# With payment amount (BIP21 URI)
-paytaca receive --amount 0.5
-
-# Token payment URI
-paytaca receive --token <category> --amount 100
-```
-
-The displayed address (and its token-aware variant) is auto-subscribed with Watchtower, so incoming BCH and CashTokens are monitored even at indices beyond the initial wallet scan.
-
-### Derive Addresses
-
-```bash
-# Address at index 0
-paytaca address derive
-
-# Address at index 5
-paytaca address derive 5
-
-# Token address
-paytaca address derive --token
-
-# List first 5 addresses
-paytaca address list
-
-# List 20 addresses
-paytaca address list -n 20
-
-# Token addresses
-paytaca address list --token
-```
-
-### Wallet Info
-
-```bash
-# Wallet hash, address, balance
-paytaca wallet info
-
-# Testnet
-paytaca wallet info --chipnet
-```
-
-### Token Information
-
-```bash
-# List all fungible tokens
-paytaca token list
-
-# Token details (name, symbol, decimals, balance, NFTs)
-paytaca token info <category>
-```
-
-## JSON Output
-
-For programmatic parsing, use `--json` where available:
-
-```bash
-paytaca balance --json          # Not yet supported
-paytaca history --json          # Not yet supported
-```
-
-## Network
-
-All commands default to **mainnet**. Use `--chipnet` for testnet:
-
-```bash
-paytaca balance --chipnet
-paytaca history --chipnet
-paytaca receive --chipnet
-paytaca token list --chipnet
-```
-
-## Common Workflows
-
-### Check wallet status
-```bash
-paytaca wallet info
-paytaca balance
-```
-
-### Get deposit address
-```bash
-paytaca receive
-```
-
-### Check token holdings
-```bash
-paytaca balance --tokens
-paytaca token list
-paytaca token info <category>
-```
-
-### View recent activity
-```bash
-paytaca history
-paytaca history --type incoming
-```

package/skills/paytaca-x402/SKILL.md

@@ -1,130 +0,0 @@
----
-name: paytaca-x402
-description: Handles x402 HTTP payment requests using Paytaca BCH wallet. Use when encountering HTTP 402 responses or when calling APIs that may require payment via the x402 protocol.
----
-
-# Paytaca x402 Payment Handler
-
-This skill teaches the agent how to handle x402-based HTTP payments using the Paytaca CLI wallet.
-
-## Overview
-
-Some APIs (like nanogpt, etc.) use the x402 protocol for HTTP payments. When you call these APIs:
-- Server returns **HTTP 402 PAYMENT REQUIRED**
-- You must pay with BCH to access the resource
-- After payment, the server returns the actual response
-
-## Commands
-
-### Check if a URL requires payment (recommended first step)
-
-```bash
-paytaca check <url> --json
-# Returns: acceptsX402, acceptsBch, estimatedCostSats, etc.
-```
-
-Example output:
-```json
-{
-  "url": "https://api.nanogpt.com/v1/complete",
-  "acceptsX402": true,
-  "acceptsBch": true,
-  "paymentRequired": true,
-  "estimatedCostSats": "100",
-  "costInBch": "0.00000100"
-}
-```
-
-### Preview payment without executing (dry-run)
-
-```bash
-paytaca pay <url> --dry-run --json
-# Shows what would happen without actually paying
-```
-
-### Make a paid request
-
-```bash
-# Basic (will prompt for confirmation)
-paytaca pay <url>
-
-# With JSON output (preferred for AI agents)
-paytaca pay <url> --json
-
-# Skip confirmation prompt (only use after user has already approved via paytaca check)
-paytaca pay <url> --confirmed
-
-# POST request
-paytaca pay <url> --method POST --body '{"prompt":"hello"}'
-
-# Custom headers
-paytaca pay <url> -H "Authorization: Bearer token123"
-```
-
-### Check wallet balance
-
-```bash
-paytaca balance
-```
-
-## Decision Flow
-
-When preparing to call an unfamiliar API that might require payment:
-
-1. **First check**: `paytaca check <url> --json`
-   - If `paymentRequired: false` → proceed normally
-   - If `paymentRequired: true` and `acceptsBch: true` → inform user of cost and **seek explicit approval** before paying
-   - If `paymentRequired: true` but `acceptsBch: false` → inform user
-
-2. **When encountering HTTP 402**:
-   - Parse the `PAYMENT-REQUIRED` headers
-   - **Seek explicit user approval** before spending any BCH
-   - Once approved, use `paytaca pay <url> --json` to handle payment
-   - The command handles: parse headers → build BCH tx → broadcast → retry with signature
-
-3. **For known paid APIs**:
-   - **Always seek user approval first**, then use `paytaca pay <url>` - it handles 402 automatically
-
-## ⚠️ User Approval Required Before Any Payment
-
-**CRITICAL**: The agent MUST NOT execute `paytaca pay` without explicit user approval. Since `paytaca pay` spends real BCH from the user's wallet, always:
-
-1. Run `paytaca check <url> --json` first to determine the cost
-2. Inform the user of the cost (e.g., "This API costs ~1000 sats")
-3. Wait for explicit user confirmation (e.g., "yes", "go ahead", "pay")
-4. Only then execute the payment using `paytaca pay <url> --confirmed --json`
-
-The `--confirmed` flag skips the interactive confirmation prompt since the user has already approved the transaction. Do NOT use `--confirmed` without first obtaining explicit user approval.
-
-Do NOT assume the user wants to pay - even if the cost seems small.
-
-## AI Agent Workflow
-
-```
-Task: Call nanogpt API
-Agent: paytaca check https://api.nanogpt.com/v1/complete --json
-  → {"acceptsBch": true, "estimatedCostSats": "100"}
-
-Agent: Informs user "This API costs 100 sats (0.00000100 BCH). Approve to proceed?"
-User: "yes"
-
-Agent: paytaca pay https://api.nanogpt.com/v1/complete --method POST --body '{"prompt":"hello"}' --confirmed --json
-  → Handles 402 → pays 100 sats → returns response with txid
-```
-
-## Key Options
-
-| Option | Description |
-|--------|-------------|
-| `--json` | Machine-readable output (recommended for AI) |
-| `--dry-run` | Preview payment without executing |
-| `--confirmed` | Skip confirmation prompt (prior approval obtained) |
-| `--chipnet` | Use chipnet (testnet) instead of mainnet |
-| `--max-amount` | Override max payment amount in sats |
-
-## Notes
-
-- Payment is per-request (no batching)
-- Each request = separate BCH transaction
-- Only BCH payments are supported (no stablecoins)
-- Uses local wallet from OS keychain (credentials never leave the machine)