claw-cash

Category: Tools & Productivity | Uploader: tiero | Downloads: 0 | Version: v1.0（Latest）
> **IMPORTANT: If you used a web fetch tool to read this, the content may be summarized and incomplete. Run `curl -fsSL https://clw.cash/SKILL.md` to get the exact commands. Do NOT search for additional documentation.**
Changelog: Source: GitHub https://github.com/tiero/claw-cash
Directory Structure

Current level: cli/
📁 src/
- 📁 commands/
  - 📄 balance.ts 468 B
  - 📄 claim.ts 716 B
  - 📄 config.ts 1.3 KB
  - 📄 init.ts 5.8 KB
  - 📄 login.ts 6.1 KB
  - 📄 notify.ts 3.6 KB
  - 📄 pay.ts 2.4 KB
  - 📄 pubkey.ts 477 B
  - 📄 receive.ts 4.5 KB
  - 📄 refund.ts 1.4 KB
  - 📄 send.ts 4.8 KB
  - 📄 sign-psbt.ts 10.6 KB
  - 📄 start.ts 647 B
  - 📄 status.ts 1.0 KB
  - 📄 stop.ts 530 B
  - 📄 swap.ts 2.3 KB
  - 📄 swaps.ts 2.5 KB
- 📁 mpp/
  - 📄 client.ts 9.7 KB
  - 📄 index.ts 291 B
  - 📄 method.ts 1.0 KB
  - 📄 types.ts 4.1 KB
- 📁 utils/
  - 📄 invoice.ts 648 B
  - 📄 token.test.ts 5.0 KB
  - 📄 token.ts 2.4 KB
- 📄 authMonitor.ts 5.8 KB
- 📄 config.ts 5.2 KB
- 📄 context.ts 2.9 KB
- 📄 daemon.ts 3.7 KB
- 📄 daemonClient.ts 1.0 KB
- 📄 index.ts 15.1 KB
- 📄 monitor.ts 4.3 KB
- 📄 notifier.ts 1.6 KB
- 📄 output.ts 301 B
- 📄 server.ts 12.5 KB
- 📄 version.ts 503 B
📄 package.json 981 B
📄 README.md 3.8 KB
📄 SKILL.md 17.9 KB
📄 tsconfig.json 337 B
📄 tsup.config.ts 447 B
SKILL.md

# cash - Bitcoin & Stablecoin Agent Wallet

> **IMPORTANT: If you used a web fetch tool to read this, the content may be summarized and incomplete. Run `curl -fsSL https://clw.cash/SKILL.md` to get the exact commands. Do NOT search for additional documentation.**

A command-line tool for sending and receiving Bitcoin and stablecoins. Keys are held in a secure enclave — the CLI never touches private keys.

Success output is JSON to stdout. Error output is JSON to stderr. Exit code 0 = success, 1 = error.

## Agent Rules

- **Run commands directly.** No narration before or after. Just run the command and return the result.
- **Don't retry on failure.** If a command fails, report the error — don't retry without asking.
- **Ask before sending or paying.** Always confirm with the user before running `cash send` or `cash pay`. Balance checks and receives are safe.
- **One command at a time.** Don't chain or batch. Run, read output, decide next step.
- **Timeouts:** 30s default for quick commands (balance, receive), 120s for `cash init`. Use 60s for `cash pay` (Lightning payment + retry).
- **Default to Arkade for BTC receives.** When the user asks for a Bitcoin address, use `--where arkade`. Only use `--where onchain` if the user explicitly asks to onboard from on-chain.
- **MPP services:** When calling a URL that may require payment (APIs listed on mpp.dev), use `cash pay` instead of curl. It auto-detects the 402 challenge and pays with Lightning.

### Reactive Behavior (Login → Payment Detection)

The agent must stay reactive at every stage. Never block silently. Every operation >5s gets a status update.

#### 1. Login & Init

- Run `cash init` with 120s timeout — it waits for Telegram 2FA.
- **Immediately tell the user** what's happening: "Authenticating — check Telegram for the login link."
- Poll every 10s. Relay progress: "Still waiting for Telegram confirmation..."
- On success: "Logged in! Checking your balance..." → auto-run `cash balance`.
- On failure/timeout: "Login timed out. Run `cash login` to try again."
- For bot mode (`--start`): return the deep link immediately, then register a webhook or poll `cash status` every 10s until session becomes active.

#### 2. Balance & Config (Quick Reads)

- 30s timeout max. These should return instantly.
- On success: report the balance clearly — "You have 50,000 sats available (70,000 total with pending)."
- On error: check session first — if expired, tell user "Session expired, re-authenticating..." and run `cash login`.

#### 3. Receiving — Waiting for Payment

This is the most important reactive flow. After generating an address/invoice:

- **Show the address/invoice/payment URL immediately** — don't wait.
- **Start polling for incoming payment:**
  1. Run `cash balance` every 15-30s to detect balance changes.
  2. For Lightning: the daemon auto-claims — poll `cash status` or register a webhook.
  3. For stablecoin receives: poll `cash swaps --pending` to detect when the sender funds the swap.
- **Keep the user informed:**
  - "Waiting for payment... (checking every 15s)"
  - "Still waiting — no payment detected yet."
  - "Payment detected! 50,000 sats received. New balance: 120,000 sats."
- **Use webhooks when available** — register via the daemon's `/notify/register` endpoint for `swap.claimed` events instead of polling.
- **Timeout after 5 minutes** of no payment: "No payment detected after 5 min. The address/invoice is still valid — I'll stop polling but you can ask me to check again."

#### 4. Sending — Swap Execution

- **Always confirm** with user before executing `cash send`.
- Run the send command with `yieldMs=10000` for swap commands (BTC→stablecoin).
- Relay progress:
  - "Sending 10 USDC to 0x... on Polygon..."
  - "Swap initiated — waiting for settlement..."
  - "Sent! Tx: 0x... — 10 USDC delivered."
- If backgrounded, poll `cash swap <id>` every 10s until status is `completed` or `failed`.
- On failure: report error, suggest `cash refund <id>` if applicable.

#### 5. Swap Monitoring

- For any active swap, poll `cash swap <id>` every 10-15s.
- Map status to user-friendly updates:
  - `pending` / `awaiting_funding` → "Swap created, waiting for funding..."
  - `funded` → "Funds received, processing swap..."
  - `processing` → "Swap in progress, settling on-chain..."
  - `completed` → "Swap complete! Funds delivered."
  - `expired` → "Swap expired. You can refund with `cash refund <id>`."
  - `failed` → "Swap failed: [error]. Check `cash swap <id>` for details."
- After `completed`: auto-run `cash balance` and report the new balance.

#### Never Do

- Block silently for >15s without a status update.
- Let a timeout kill a command without telling the user.
- Retry failed commands without asking (except `cash login` on session expiry).
- Go silent after generating a receive address — always poll for payment.
- Assume a swap succeeded without checking status.

## Setup

```bash
# Install globally
npm install -g clw-cash
# First time — authenticates, creates identity, saves config, starts daemon
cash init
# Re-authenticate when session expires (blocking — waits up to 120s)
cash login
```

`init` handles authentication automatically (Telegram 2FA in production, auto-resolves in test mode). If an identity already exists on the server (e.g., from a previous install or sandbox reset), it **auto-recovers** it instead of creating a new one. Config is saved to `~/.clw-cash/config.json`, and it **auto-starts a background daemon** for monitoring swaps (Lightning HTLC claiming and LendaSwap polling).

If the session token expires, run `cash login` to re-authenticate. The daemon can be stopped with `cash stop` and restarted with `cash start`.

### Non-blocking Auth (for Telegram bots)

When running as a Telegram bot, use `--start` to avoid blocking. The daemon polls in the background and sends a Telegram reply when auth completes:

```bash
# Returns immediately with a deep link. Daemon handles the rest.
cash login --start --bot-token <TELEGRAM_BOT_TOKEN> --chat-id <CHAT_ID> --message-id <MSG_ID>
# -> {"ok": true, "data": {"deepLink": "https://t.me/clw_cash_bot?start=...", "challengeId": "..."}}
```

The daemon will reply to `<MSG_ID>` with "Connected, welcome back!" once the user authenticates via the deep link. Requires the daemon to be running (`cash start`).

You can also pass flags explicitly: `cash init --api-url <url> --token <jwt> --ark-server <url> --network <bitcoin|testnet>`.

Or set environment variables:

```bash
CLW_API_URL=https://api.clw.cash
CLW_SESSION_TOKEN=<jwt>
CLW_IDENTITY_ID=<uuid>
CLW_PUBLIC_KEY=<hex>
CLW_ARK_SERVER_URL=https://ark.clw.cash
CLW_NETWORK=bitcoin          # bitcoin or testnet
CLW_DAEMON_PORT=3457          # default: 3457
```

## Commands

### Send Bitcoin

```bash
# Send via Ark (instant, off-chain) — use the unit that matches user input
cash send --amount 100000 --currency sats --where arkade --to <ark-address>
cash send --amount 0.001  --currency btc  --where arkade --to <ark-address>

# Send on-chain
cash send --amount 100000 --currency sats --where onchain --to <bitcoin-address>
cash send --amount 0.001  --currency btc  --where onchain --to <bitcoin-address>

# Pay a Lightning invoice
cash send --amount 50000 --currency sats --where lightning --to <bolt11-invoice>
cash send --amount 0.001 --currency btc  --where lightning --to <bolt11-invoice>

# Auto-detect invoice format (bolt11 or BIP21, positional arg)
cash send lnbc500n1pj...
cash send bitcoin:bc1q...?amount=0.001&lightning=lnbc...
```

### Send Stablecoins (BTC to Stablecoin swap)

```bash
# Swap BTC to USDT on Polygon
cash send --amount 10 --currency usdt --where polygon --to <0x-address>

# Swap BTC to USDC on Arbitrum
cash send --amount 50 --currency usdc --where arbitrum --to <0x-address>
```

### Receive Bitcoin

```bash
# Get an Ark address
cash receive --amount 100000 --currency sats --where arkade
cash receive --amount 0.001  --currency btc  --where arkade

# Create a Lightning invoice — use the unit that matches user input
cash receive --amount 50000 --currency sats --where lightning
# -> {"ok": true, "data": {"bolt11": "lnbc...", "paymentHash": "...", "amount": 50000}}
cash receive --amount 0.001 --currency btc  --where lightning
# -> {"ok": true, "data": {"bolt11": "lnbc...", "paymentHash": "...", "amount": 100000}}

# Get a boarding (on-chain) address
cash receive --amount 100000 --currency sats --where onchain
cash receive --amount 0.001  --currency btc  --where onchain
```

### Receive Stablecoins (Stablecoin to BTC swap)

```bash
# Receive stablecoins — sender picks chain on web page (no --where)
cash receive --amount 10 --currency usdt
# -> {"ok": true, "data": {"paymentUrl": "https://pay.clw.cash?amount=10&to=ark1q...&currency=usdt", "amount": 10, "currency": "usdt", "targetAddress": "ark1q..."}}

# Receive stablecoins — specify chain (creates swap, generates payment URL with swap ID)
cash receive --amount 10 --currency usdt --where polygon
# -> {"ok": true, "data": {"paymentUrl": "https://pay.clw.cash?id=<swapId>", "swapId": "...", "amount": 10, "token": "usdt0_pol", "chain": "polygon", "targetAddress": "ark1q..."}}
```

### Pay MPP-Enabled Services

MPP (Machine Payments Protocol) is an open protocol for machine-to-machine payments over HTTP (IETF draft `draft-httpauth-payment-00`). When an API returns `HTTP 402` with a `WWW-Authenticate: Payment ...` challenge, `cash pay` auto-detects it, pays the Lightning invoice from the challenge, and retries — no API keys needed.

The BTC treasury is used to fund payments. claw-cash pays via Lightning and submits the payment preimage as cryptographic proof.

```bash
# Call any MPP-enabled service (GET by default)
cash pay https://api.example.com/resource
# -> {"ok": true, "data": {"url": "...", "status": 200, "body": {...}, "paid": true, "method": "lightning", "preimage": "abcdef..."}}

# POST with JSON body
cash pay https://api.example.com/v1/generate --method POST --body '{"prompt":"hello"}'

# With extra headers
cash pay https://api.example.com/resource --header 'X-Session-Id: abc123'

# Non-MPP services (no 402 challenge) are passed through unchanged
cash pay https://api.example.com/free-resource
# -> {"ok": true, "data": {"url": "...", "status": 200, "body": {...}, "paid": false}}
```

Output fields:

- `paid` — `true` if a Lightning payment was made, `false` if no 402 challenge
- `method` — payment method used (currently `"lightning"`)
- `preimage` — Lightning payment preimage (proof of payment)
- `body` — the API response body (parsed as JSON if possible)
- `status` — HTTP status of the final response

Supported MPP methods: `lightning` (pays BOLT11 invoice; submits preimage as proof).

For service discovery, see [mpp.dev](https://mpp.dev) — a registry of APIs that accept MPP payments.

Common MPP errors:

- `"No supported MPP payment challenge found"` — service requires `tempo` or `stripe` (not yet supported); use a different payment method or service
- `"MPP lightning challenge missing methodDetails.invoice"` — malformed challenge from server; contact service provider
- `"Insufficient BTC balance"` — run `cash balance` and top up via `cash receive`

### Check Balance

```bash
cash balance
# -> {"ok": true, "data": {"total": 250000, "offchain": {"settled": 50000, "preconfirmed": 20000, "available": 70000}, "onchain": {"confirmed": 30000, "total": 30000}}}
```

### Public Key

```bash
# Get the wallet's x-only Taproot public key (for multisig script construction)
cash pubkey
# -> {"ok": true, "data": {"publicKey": "9350761ae700..."}}

# Pipe into multisig tooling
PUBKEY=$(cash pubkey | jq -r .data.publicKey)
```

### Configuration

```bash
cash config
# -> {"ok": true, "data": {"apiBaseUrl": {"value": "...", "source": "file"}, "payBaseUrl": "...", "arkServerUrl": {"value": "...", "source": "..."}, "network": {"value": "bitcoin", "source": "default"}, ..., "daemonPort": 3457, "configFile": "~/.clw-cash/config.json", "dataDir": "~/.clw-cash/data", "session": "active", "sessionExpiresAt": 1739...}}
```

### Swap Management

```bash
# Check a single swap by ID
cash swap <swap-id>
# -> {"ok": true, "data": {"id": "...", "status": "funded", "direction": "btc_to_stablecoin", "local": {"direction": "...", "status": "...", "sourceToken": "...", "targetToken": "...", "sourceAmount": ..., "targetAmount": ..., "exchangeRate": ..., "createdAt": "...", "completedAt": null, "txid": null}, "remote": {...}}}

# List swaps (grouped by status, last 5 per category)
cash swaps
# -> {"ok": true, "data": {"lendaswap": {"pending": [...], "claimed": [...], "refunded": [...], "expired": [...], "failed": [...]}}}

# Filter by status
cash swaps --pending
cash swaps --claimed --limit 10

# Manually claim a completed swap
cash claim <swap-id>
# -> {"ok": true, "data": {"success": true, "txHash": "0x...", "chain": "polygon"}}

# Refund a BTC→Stablecoin swap (refunds directly via SDK)
cash refund <swap-id>
# -> {"ok": true, "data": {"success": true, "txId": "...", "refundAmount": 95000}}

# Refund a Stablecoin→BTC swap (returns unsigned EVM tx call data)
cash refund <swap-id>
# -> {"ok": true, "data": {"type": "evm_refund", "swapId": "...", "timelockExpired": true, "timelockExpiry": "...", "transaction": {"to": "0x...", "data": "0x..."}}}

# Optional: specify refund destination
cash refund <swap-id> --address <destination>
```

### Daemon (Swap Monitoring)

The daemon runs in the background to automatically claim Lightning HTLCs and monitor LendaSwap swaps. It is **auto-started by `cash init`**. Use these commands to manage it manually:

```bash
# Start the daemon
cash start
# -> {"ok": true, "data": {"started": true, "pid": 12345, "port": 3457}}
# (if already running: {"ok": true, "data": {"started": false, "reason": "already_running", "pid": 12345, "port": 3457}})

# Check daemon and session status
cash status
# -> {"ok": true, "data": {"session": "active", "sessionExpiresAt": 1739..., "sessionRemainingSeconds": 3200, "daemon": {"running": true, "pid": 12345, "port": 3457, "detail": {...}}}}

# List pending swaps
cash swaps --pending

# Stop the daemon
cash stop
# -> {"ok": true, "data": {"stopped": true, "pid": 12345}}
# (if not running: {"ok": true, "data": {"stopped": false, "reason": "not_running"}})
```

### Swap Event Webhooks

Register a webhook URL to receive notifications when the daemon claims, refunds, or fails a swap. Webhooks are in-memory (re-register after daemon restart).

```bash
# Register for swap event notifications (daemon HTTP API, default port 3457)
curl -X POST http://127.0.0.1:3457/notify/register \
  -H 'content-type: application/json' \
  -d '{"url": "https://my-bot/webhook", "events": ["swap.claimed", "swap.refunded", "swap.failed"]}'
# -> {"id": "<uuid>", "url": "https://my-bot/webhook", "events": ["swap.claimed", "swap.refunded", "swap.failed"]}

# List active webhooks
curl http://127.0.0.1:3457/notify
# -> {"webhooks": [{"id": "...", "url": "...", "events": [...]}]}

# Unregister a webhook
curl -X DELETE http://127.0.0.1:3457/notify/<id>
# -> {"removed": true}
```

Webhook payload (POST to registered URL):

```json
{
  "event": "swap.claimed",
  "swapId": "abc123...",
  "status": "completed",
  "direction": "btc_to_stablecoin",
  "sourceAmount": 100000,
  "sourceToken": "btc_arkade",
  "targetAmount": 10.5,
  "targetToken": "usdc_pol",
  "message": "Swap abc123... claimed successfully",
  "timestamp": "2026-02-16T12:00:00Z"
}
```

Events: `swap.claimed`, `swap.refunded`, `swap.failed`.

## Output Format

Success (stdout):

```json
{"ok": true, "data": { ... }}
```

Error (stderr):

```json
{"ok": false, "error": "description of what went wrong"}
```

## Currency & Network Matrix

| Currency | Networks                    | Notes                                     |
| -------- | --------------------------- | ----------------------------------------- |
| sats     | onchain, lightning, arkade  | Amount in satoshis — use when user says "sats" |
| btc      | onchain, lightning, arkade  | Amount in BTC — use when user says "BTC"        |
| usdt     | polygon, ethereum, arbitrum |                                           |
| usdc     | polygon, ethereum, arbitrum |                                           |

## Swap Status Lifecycle

| Status             | Meaning                        |
| ------------------ | ------------------------------ |
| pending            | Swap created, awaiting funding |
| awaiting_funding   | Initial state                  |
| funded             | User has sent funds            |
| processing         | Swap in progress               |
| completed          | Swap done, claimed             |
| expired            | Timelock expired               |
| refunded           | Funds returned                 |
| failed             | Swap failed                    |

Directions: `btc_to_stablecoin` or `stablecoin_to_btc`.

Token identifiers: `btc_arkade`, `usdc_pol`, `usdc_eth`, `usdc_arb`, `usdt0_pol`, `usdt_eth`, `usdt_arb`.

## Agent Tips

All output is JSON — pipe through `jq` to extract specific fields:

```bash
# Get just the swap status
cash swap <swap-id> | jq .data.status

# Get total balance in sats
cash balance | jq .data.total

# Get offchain available balance
cash balance | jq .data.offchain.available

# Check if daemon is running
cash status | jq .data.daemon.running

# Check session state (active or expired)
cash status | jq .data.session

# List only pending swap IDs
cash swaps --pending | jq '[.data.lendaswap.pending[].id]'

# Get the payment bolt11 invoice
cash receive --amount 50000 --currency sats --where lightning | jq -r .data.bolt11

# Get the ark address for receiving
cash receive --amount 100000 --currency sats --where arkade | jq -r .data.address

# Get the payment URL for stablecoin receive
cash receive --amount 10 --currency usdc | jq -r .data.paymentUrl

# Check if a command succeeded
cash send ... && echo "sent" || echo "failed"
```

Common workflow for monitoring a stablecoin swap:

```bash
# 1. Initiate the swap
cash send --amount 10 --currency usdc --where polygon --to 0x...

# 2. Poll status until completed (daemon does this automatically)
cash swap <swap-id> | jq .data.status

# 3. If expired, refund
cash refund <swap-id>
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
claw-cash

Directory Structure

SKILL.md

Report

Notice
