clawpowers 1.1.1 → 1.1.3
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 +48 -2
- package/bin/clawpowers.js +254 -19
- package/docs/launch-images/25-skills-breakdown.jpg +0 -0
- package/docs/launch-images/clawpowers-vs-superpowers.jpg +0 -0
- package/docs/launch-images/economic-code-optimization.jpg +0 -0
- package/docs/launch-images/native-vs-bridge-2.jpg +0 -0
- package/docs/launch-images/native-vs-bridge.jpg +0 -0
- package/docs/launch-images/ultimate-stack.jpg +0 -0
- package/docs/quickstart-first-transaction.md +204 -0
- package/package.json +1 -1
- package/runtime/demo/README.md +78 -0
- package/runtime/demo/x402-mock-server.js +230 -0
- package/runtime/init.js +40 -2
- package/runtime/init.sh +34 -1
- package/runtime/payments/ledger.js +305 -0
- package/runtime/payments/ledger.sh +262 -0
- package/runtime/payments/pipeline.js +459 -0
- package/skill.json +38 -6
- package/skills/agent-bounties/SKILL.md +553 -0
- package/skills/agent-payments/SKILL.md +68 -0
- package/skills/market-intelligence/SKILL.md +35 -0
- package/skills/prospecting/SKILL.md +141 -0
- package/skills/security-audit/SKILL.md +45 -0
- package/skills/using-clawpowers/SKILL.md +9 -1
package/README.md
CHANGED
|
@@ -27,7 +27,7 @@ ClawPowers gives your coding agent superpowers that go beyond instructions. Whil
|
|
|
27
27
|
| Windows native support | ✅ | ❌ |
|
|
28
28
|
| Zero dependencies | ✅ | ✅ |
|
|
29
29
|
|
|
30
|
-
**
|
|
30
|
+
**26 skills.** 14 cover everything static frameworks do (TDD, subagent dev, debugging, planning, code review, git worktrees). 6 go where they can't — payments, security, content, prospecting, market intelligence, and metacognitive learning. 4 are things no other framework even attempts — self-healing code, agents that rewrite their own methodology, cross-project knowledge transfer, and property-based formal verification.
|
|
31
31
|
|
|
32
32
|
## Requirements
|
|
33
33
|
|
|
@@ -230,7 +230,7 @@ These skills don't exist in any other framework. They require runtime execution,
|
|
|
230
230
|
|
|
231
231
|
```
|
|
232
232
|
clawpowers/
|
|
233
|
-
├── skills/ #
|
|
233
|
+
├── skills/ # 26 skill directories, each with SKILL.md
|
|
234
234
|
├── runtime/
|
|
235
235
|
│ ├── persistence/ # Cross-session state (store.js + store.sh)
|
|
236
236
|
│ ├── metrics/ # Outcome tracking (collector.js + collector.sh)
|
|
@@ -281,6 +281,40 @@ npx clawpowers store get <key> # Retrieve state
|
|
|
281
281
|
npx clawpowers store list [prefix] # List stored keys
|
|
282
282
|
```
|
|
283
283
|
|
|
284
|
+
## Payments Are Optional (and Safe by Default)
|
|
285
|
+
|
|
286
|
+
ClawPowers works without any wallet.
|
|
287
|
+
|
|
288
|
+
When you hit a paid boundary (HTTP 402 "Payment Required", premium tools, or agent-to-agent settlements), ClawPowers can pay **only if** you enable it and set spending limits.
|
|
289
|
+
|
|
290
|
+
**Default mode: Dry Run**
|
|
291
|
+
- We detect payment requirements.
|
|
292
|
+
- We evaluate your spending policy (limits + allowlist).
|
|
293
|
+
- We log exactly what would happen.
|
|
294
|
+
- **No funds move until you explicitly enable live payments.**
|
|
295
|
+
|
|
296
|
+
### Enable payments (2 minutes)
|
|
297
|
+
|
|
298
|
+
```bash
|
|
299
|
+
npx clawpowers init
|
|
300
|
+
npx clawpowers payments setup
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
Choose:
|
|
304
|
+
- Keep disabled
|
|
305
|
+
- Enable Dry Run (observe what would happen)
|
|
306
|
+
- Enable Live Payments (set per-tx and daily limits)
|
|
307
|
+
|
|
308
|
+
All logs are local at `~/.clawpowers/` (never share this directory).
|
|
309
|
+
|
|
310
|
+
### Try it risk-free
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
npx clawpowers demo x402
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
Runs a local mock x402 merchant — see the full 402 → pay → 200 flow without any real money.
|
|
317
|
+
|
|
284
318
|
## Security Model
|
|
285
319
|
|
|
286
320
|
ClawPowers takes agent autonomy seriously — which means taking agent *limits* seriously.
|
|
@@ -394,6 +428,18 @@ Built by [AI Agent Economy](https://github.com/up2itnow0822) — the team behind
|
|
|
394
428
|
|
|
395
429
|
We welcome contributions. Unlike some frameworks, we don't dismiss legitimate skill proposals with one-word responses. Open an issue or PR — every submission gets a genuine technical review.
|
|
396
430
|
|
|
431
|
+
## Patent Notice
|
|
432
|
+
|
|
433
|
+
**Patent Pending** — The underlying financial infrastructure (agentwallet-sdk, agentpay-mcp) is covered by USPTO provisional patent application filed March 2026: "Non-Custodial Multi-Chain Financial Infrastructure System for Autonomous AI Agents."
|
|
434
|
+
|
|
435
|
+
## Open Standard + Defensive Patent
|
|
436
|
+
|
|
437
|
+
We support the open x402 standard and encourage interoperable implementations. Our [provisional patent filing](https://github.com/up2itnow0822) is defensive — intended to prevent hostile monopolization and protect builders' ability to use open payment rails. Our goal is to be the safest, fastest, most complete implementation, and to help the ecosystem adopt secure agent payments.
|
|
438
|
+
|
|
439
|
+
## Disclaimer
|
|
440
|
+
|
|
441
|
+
ClawPowers and agentwallet-sdk are non-custodial developer tooling. You control your own keys and set your own spending limits. You are responsible for compliance with applicable laws in your jurisdiction. This software is provided as-is under the MIT license. Nothing in this project constitutes financial advice, custody services, or money transmission.
|
|
442
|
+
|
|
397
443
|
## License
|
|
398
444
|
|
|
399
445
|
MIT
|
package/bin/clawpowers.js
CHANGED
|
@@ -25,6 +25,7 @@ const ANALYZE_JS = path.join(REPO_ROOT, 'runtime', 'feedback', 'analyze.js');
|
|
|
25
25
|
const STORE_JS = path.join(REPO_ROOT, 'runtime', 'persistence', 'store.js');
|
|
26
26
|
const COLLECTOR_JS = path.join(REPO_ROOT, 'runtime', 'metrics', 'collector.js');
|
|
27
27
|
const SESSION_JS = path.join(REPO_ROOT, 'hooks', 'session-start.js');
|
|
28
|
+
const LEDGER_JS = path.join(REPO_ROOT, 'runtime', 'payments', 'ledger.js');
|
|
28
29
|
|
|
29
30
|
/**
|
|
30
31
|
* Prints the top-level command usage to stdout.
|
|
@@ -41,6 +42,8 @@ Commands:
|
|
|
41
42
|
metrics <cmd> Record or query skill execution metrics
|
|
42
43
|
analyze [opts] RSI feedback analysis of skill performance
|
|
43
44
|
store <cmd> Key-value state store operations
|
|
45
|
+
payments <cmd> Payment setup, log, and summary commands
|
|
46
|
+
demo <cmd> Run interactive demos (e.g. x402 mock merchant)
|
|
44
47
|
|
|
45
48
|
Examples:
|
|
46
49
|
npx clawpowers init
|
|
@@ -50,6 +53,10 @@ Examples:
|
|
|
50
53
|
npx clawpowers analyze --skill systematic-debugging
|
|
51
54
|
npx clawpowers store set "my:key" "my value"
|
|
52
55
|
npx clawpowers store get "my:key"
|
|
56
|
+
npx clawpowers payments setup
|
|
57
|
+
npx clawpowers payments log
|
|
58
|
+
npx clawpowers payments summary
|
|
59
|
+
npx clawpowers demo x402
|
|
53
60
|
|
|
54
61
|
Run 'npx clawpowers <command> help' for command-specific help.`);
|
|
55
62
|
}
|
|
@@ -100,19 +107,35 @@ function cmdStatus() {
|
|
|
100
107
|
*/
|
|
101
108
|
function cmdUpdate() {
|
|
102
109
|
const repoUrl = 'https://github.com/up2itnow0822/clawpowers';
|
|
103
|
-
const result = spawnSync('git', ['-C', REPO_ROOT, 'pull', '--ff-only', 'origin', 'main'], {
|
|
104
|
-
stdio: 'inherit',
|
|
105
|
-
// On Windows, git must be launched through the shell so PATH is resolved
|
|
106
|
-
shell: os.platform() === 'win32',
|
|
107
|
-
});
|
|
108
110
|
|
|
109
|
-
if (
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
111
|
+
// Check if we're in a git repo (git clone install) or npm install
|
|
112
|
+
const gitDir = path.join(REPO_ROOT, '.git');
|
|
113
|
+
const isGitInstall = fs.existsSync(gitDir);
|
|
114
|
+
|
|
115
|
+
if (isGitInstall) {
|
|
116
|
+
// Git install: pull latest
|
|
117
|
+
const result = spawnSync('git', ['-C', REPO_ROOT, 'pull', '--ff-only', 'origin', 'main'], {
|
|
118
|
+
stdio: 'inherit',
|
|
119
|
+
shell: os.platform() === 'win32',
|
|
120
|
+
});
|
|
121
|
+
|
|
122
|
+
if (result.error) {
|
|
123
|
+
console.log(`git not found or failed. Visit ${repoUrl} to update manually.`);
|
|
124
|
+
} else if (result.status !== 0) {
|
|
125
|
+
console.log(`Warning: could not auto-update. Visit ${repoUrl} for latest.`);
|
|
126
|
+
} else {
|
|
127
|
+
console.log('Updated to latest version.');
|
|
128
|
+
}
|
|
114
129
|
} else {
|
|
115
|
-
|
|
130
|
+
// npm/npx install: instruct user to reinstall via npm
|
|
131
|
+
console.log('ClawPowers was installed via npm. To update:');
|
|
132
|
+
console.log('');
|
|
133
|
+
console.log(' npx clawpowers@latest init');
|
|
134
|
+
console.log('');
|
|
135
|
+
console.log('This will update the CLI and re-initialize the runtime');
|
|
136
|
+
console.log('(your existing state, metrics, and config are preserved).');
|
|
137
|
+
console.log('');
|
|
138
|
+
console.log(`Or visit: ${repoUrl}`);
|
|
116
139
|
}
|
|
117
140
|
}
|
|
118
141
|
|
|
@@ -356,6 +379,216 @@ function delegateToNode(script, args) {
|
|
|
356
379
|
process.exit(result.status || 0);
|
|
357
380
|
}
|
|
358
381
|
|
|
382
|
+
/**
|
|
383
|
+
* `clawpowers payments setup` — Interactive wallet activation wizard.
|
|
384
|
+
*
|
|
385
|
+
* Guides the user through enabling or configuring the payment subsystem.
|
|
386
|
+
* Never asks for private keys — those belong in .env.
|
|
387
|
+
* Reads and writes ~/.clawpowers/config.json (created by init if missing).
|
|
388
|
+
*
|
|
389
|
+
* Wizard steps:
|
|
390
|
+
* 1. Explain that payments are optional
|
|
391
|
+
* 2. Ask user to choose a mode: disabled / dry run / live
|
|
392
|
+
* 3. If dry run: update config payments.mode = "dry_run", payments.enabled = true
|
|
393
|
+
* 4. If live: ask for per_tx_limit and daily_limit, then update config
|
|
394
|
+
* 5. Confirm where logs are stored
|
|
395
|
+
*/
|
|
396
|
+
function cmdPaymentsSetup() {
|
|
397
|
+
const readline = require('readline');
|
|
398
|
+
const CLAWPOWERS_DIR = process.env.CLAWPOWERS_DIR || path.join(os.homedir(), '.clawpowers');
|
|
399
|
+
const configFile = path.join(CLAWPOWERS_DIR, 'config.json');
|
|
400
|
+
|
|
401
|
+
// Load existing config or fall back to defaults
|
|
402
|
+
let config = {};
|
|
403
|
+
if (fs.existsSync(configFile)) {
|
|
404
|
+
try {
|
|
405
|
+
config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
|
|
406
|
+
} catch (_) {
|
|
407
|
+
config = {};
|
|
408
|
+
}
|
|
409
|
+
}
|
|
410
|
+
// Ensure payments section exists with safe defaults
|
|
411
|
+
if (!config.payments) {
|
|
412
|
+
config.payments = {
|
|
413
|
+
enabled: false,
|
|
414
|
+
mode: 'dry_run',
|
|
415
|
+
per_tx_limit_usd: 0,
|
|
416
|
+
daily_limit_usd: 0,
|
|
417
|
+
weekly_limit_usd: 0,
|
|
418
|
+
allowlist: [],
|
|
419
|
+
require_approval_above_usd: 0,
|
|
420
|
+
};
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
const logsPath = path.join(CLAWPOWERS_DIR, 'logs', 'payments.jsonl');
|
|
424
|
+
|
|
425
|
+
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
|
|
426
|
+
|
|
427
|
+
const ask = (question) => new Promise((resolve) => rl.question(question, resolve));
|
|
428
|
+
|
|
429
|
+
async function run() {
|
|
430
|
+
console.log('');
|
|
431
|
+
console.log('╔══════════════════════════════════════════════════╗');
|
|
432
|
+
console.log('║ ClawPowers Payment Setup Wizard ║');
|
|
433
|
+
console.log('╚══════════════════════════════════════════════════╝');
|
|
434
|
+
console.log('');
|
|
435
|
+
console.log('Payments are optional. ClawPowers works without a wallet.');
|
|
436
|
+
console.log('When enabled, agents can autonomously pay for premium APIs');
|
|
437
|
+
console.log('and services using the x402 protocol.');
|
|
438
|
+
console.log('');
|
|
439
|
+
console.log('⚠ Private keys belong in .env — this wizard never asks for them.');
|
|
440
|
+
console.log('');
|
|
441
|
+
console.log('Choose a mode:');
|
|
442
|
+
console.log(' [1] Keep disabled (default — no payments, no wallet required)');
|
|
443
|
+
console.log(' [2] Enable Dry Run (detect payment gates, log what WOULD happen)');
|
|
444
|
+
console.log(' [3] Enable Live (real payments within configured limits)');
|
|
445
|
+
console.log('');
|
|
446
|
+
|
|
447
|
+
const choice = (await ask('Enter choice [1/2/3]: ')).trim();
|
|
448
|
+
|
|
449
|
+
if (choice === '1' || choice === '') {
|
|
450
|
+
config.payments.enabled = false;
|
|
451
|
+
config.payments.mode = 'dry_run';
|
|
452
|
+
console.log('');
|
|
453
|
+
console.log('✓ Payments remain disabled. No wallet required.');
|
|
454
|
+
|
|
455
|
+
} else if (choice === '2') {
|
|
456
|
+
config.payments.enabled = true;
|
|
457
|
+
config.payments.mode = 'dry_run';
|
|
458
|
+
console.log('');
|
|
459
|
+
console.log('✓ Dry Run mode enabled.');
|
|
460
|
+
console.log(' Agents will detect payment requirements and log what would happen.');
|
|
461
|
+
console.log(' No funds will move. Review the log after 10+ cycles, then');
|
|
462
|
+
console.log(' run this wizard again to go live with confidence.');
|
|
463
|
+
|
|
464
|
+
} else if (choice === '3') {
|
|
465
|
+
console.log('');
|
|
466
|
+
console.log('Live payment mode requires spending limits to protect your wallet.');
|
|
467
|
+
console.log('');
|
|
468
|
+
|
|
469
|
+
const perTxRaw = (await ask('Per-transaction limit (USD, e.g. 0.10): ')).trim();
|
|
470
|
+
const dailyRaw = (await ask('Daily limit (USD, e.g. 5.00): ')).trim();
|
|
471
|
+
|
|
472
|
+
const perTxLimit = parseFloat(perTxRaw) || 0;
|
|
473
|
+
const dailyLimit = parseFloat(dailyRaw) || 0;
|
|
474
|
+
|
|
475
|
+
config.payments.enabled = true;
|
|
476
|
+
config.payments.mode = 'live';
|
|
477
|
+
config.payments.per_tx_limit_usd = perTxLimit;
|
|
478
|
+
config.payments.daily_limit_usd = dailyLimit;
|
|
479
|
+
|
|
480
|
+
console.log('');
|
|
481
|
+
console.log(`✓ Live payments enabled.`);
|
|
482
|
+
console.log(` Per-transaction limit: $${perTxLimit.toFixed(2)}`);
|
|
483
|
+
console.log(` Daily limit: $${dailyLimit.toFixed(2)}`);
|
|
484
|
+
console.log('');
|
|
485
|
+
console.log(' Add your private key or mnemonic to ~/.clawpowers/.env');
|
|
486
|
+
console.log(' (never commit this file — it is gitignored by default)');
|
|
487
|
+
|
|
488
|
+
} else {
|
|
489
|
+
console.log('');
|
|
490
|
+
console.log('Invalid choice. No changes made.');
|
|
491
|
+
rl.close();
|
|
492
|
+
return;
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
// Save updated config
|
|
496
|
+
if (!fs.existsSync(CLAWPOWERS_DIR)) {
|
|
497
|
+
fs.mkdirSync(CLAWPOWERS_DIR, { recursive: true, mode: 0o700 });
|
|
498
|
+
}
|
|
499
|
+
fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
|
|
500
|
+
|
|
501
|
+
console.log('');
|
|
502
|
+
console.log(`✓ Configuration saved to: ${configFile}`);
|
|
503
|
+
console.log(` All payment logs are stored locally at: ${logsPath}`);
|
|
504
|
+
console.log('');
|
|
505
|
+
console.log(' Review logs with: npx clawpowers payments log');
|
|
506
|
+
console.log(' See summary with: npx clawpowers payments summary');
|
|
507
|
+
console.log('');
|
|
508
|
+
|
|
509
|
+
rl.close();
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
run().catch((err) => {
|
|
513
|
+
process.stderr.write(`Error: ${err.message}\n`);
|
|
514
|
+
rl.close();
|
|
515
|
+
process.exit(1);
|
|
516
|
+
});
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
/**
|
|
520
|
+
* `clawpowers payments <subcmd> [args]` — Payment ledger and setup commands.
|
|
521
|
+
*
|
|
522
|
+
* Subcommands:
|
|
523
|
+
* setup — Interactive payment mode wizard
|
|
524
|
+
* log — Show recent payment decisions
|
|
525
|
+
* summary — Show payment totals by skill, chain, outcome
|
|
526
|
+
*
|
|
527
|
+
* @param {string[]} args - Remaining argv after 'payments'.
|
|
528
|
+
*/
|
|
529
|
+
function cmdPayments(args) {
|
|
530
|
+
const [subcmd, ...rest] = args;
|
|
531
|
+
|
|
532
|
+
if (!subcmd || subcmd === 'help' || subcmd === '--help' || subcmd === '-h') {
|
|
533
|
+
console.log(`Usage: clawpowers payments <command> [options]
|
|
534
|
+
|
|
535
|
+
Commands:
|
|
536
|
+
setup Interactive payment mode wizard
|
|
537
|
+
log [--limit <n>] Show recent payment decisions (default: last 20)
|
|
538
|
+
summary Show totals by skill, chain, and outcome`);
|
|
539
|
+
return;
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
switch (subcmd) {
|
|
543
|
+
case 'setup':
|
|
544
|
+
cmdPaymentsSetup();
|
|
545
|
+
break;
|
|
546
|
+
case 'log':
|
|
547
|
+
requireModule(LEDGER_JS).cmdLog ? requireModule(LEDGER_JS).cmdLog(rest)
|
|
548
|
+
: delegateToNode(LEDGER_JS, ['log', ...rest]);
|
|
549
|
+
break;
|
|
550
|
+
case 'summary':
|
|
551
|
+
requireModule(LEDGER_JS).cmdSummary ? requireModule(LEDGER_JS).cmdSummary()
|
|
552
|
+
: delegateToNode(LEDGER_JS, ['summary']);
|
|
553
|
+
break;
|
|
554
|
+
default:
|
|
555
|
+
process.stderr.write(`Unknown payments subcommand: ${subcmd}\n`);
|
|
556
|
+
process.stderr.write('Run: npx clawpowers payments help\n');
|
|
557
|
+
process.exit(1);
|
|
558
|
+
}
|
|
559
|
+
}
|
|
560
|
+
|
|
561
|
+
/**
|
|
562
|
+
* `clawpowers demo x402` — Start the x402 mock merchant server for demo purposes.
|
|
563
|
+
* Delegates to runtime/demo/x402-mock-server.js.
|
|
564
|
+
*
|
|
565
|
+
* @param {string[]} args - Remaining argv after 'demo'.
|
|
566
|
+
*/
|
|
567
|
+
function cmdDemo(args) {
|
|
568
|
+
const [subcmd] = args;
|
|
569
|
+
|
|
570
|
+
if (!subcmd || subcmd === 'help' || subcmd === '--help' || subcmd === '-h') {
|
|
571
|
+
console.log(`Usage: clawpowers demo <command>
|
|
572
|
+
|
|
573
|
+
Commands:
|
|
574
|
+
x402 Start the x402 mock merchant server`);
|
|
575
|
+
return;
|
|
576
|
+
}
|
|
577
|
+
|
|
578
|
+
if (subcmd === 'x402') {
|
|
579
|
+
const MOCK_SERVER_JS = path.join(REPO_ROOT, 'runtime', 'demo', 'x402-mock-server.js');
|
|
580
|
+
if (!fs.existsSync(MOCK_SERVER_JS)) {
|
|
581
|
+
process.stderr.write(`Error: runtime module not found: ${MOCK_SERVER_JS}\n`);
|
|
582
|
+
process.exit(1);
|
|
583
|
+
}
|
|
584
|
+
delegateToNode(MOCK_SERVER_JS, []);
|
|
585
|
+
} else {
|
|
586
|
+
process.stderr.write(`Unknown demo subcommand: ${subcmd}\n`);
|
|
587
|
+
process.stderr.write('Run: npx clawpowers demo help\n');
|
|
588
|
+
process.exit(1);
|
|
589
|
+
}
|
|
590
|
+
}
|
|
591
|
+
|
|
359
592
|
// ============================================================
|
|
360
593
|
// Main dispatch — parse the first positional argument as the command
|
|
361
594
|
// ============================================================
|
|
@@ -363,16 +596,18 @@ const [cmd, ...args] = process.argv.slice(2);
|
|
|
363
596
|
|
|
364
597
|
try {
|
|
365
598
|
switch (cmd) {
|
|
366
|
-
case 'init':
|
|
367
|
-
case 'status':
|
|
368
|
-
case 'update':
|
|
369
|
-
case 'inject':
|
|
370
|
-
case 'metrics':
|
|
371
|
-
case 'analyze':
|
|
372
|
-
case 'store':
|
|
599
|
+
case 'init': cmdInit(); break;
|
|
600
|
+
case 'status': cmdStatus(); break;
|
|
601
|
+
case 'update': cmdUpdate(); break;
|
|
602
|
+
case 'inject': cmdInject(); break;
|
|
603
|
+
case 'metrics': cmdMetrics(args); break;
|
|
604
|
+
case 'analyze': cmdAnalyze(args); break;
|
|
605
|
+
case 'store': cmdStore(args); break;
|
|
606
|
+
case 'payments': cmdPayments(args); break;
|
|
607
|
+
case 'demo': cmdDemo(args); break;
|
|
373
608
|
case 'help':
|
|
374
609
|
case '-h':
|
|
375
|
-
case '--help':
|
|
610
|
+
case '--help': printUsage(); break;
|
|
376
611
|
// No command or empty string: show usage and exit 1 (non-zero for scripts)
|
|
377
612
|
case undefined:
|
|
378
613
|
case '':
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# 5-Minute First Transaction
|
|
2
|
+
|
|
3
|
+
Get your AI agent sending real (testnet) transactions in under 5 minutes.
|
|
4
|
+
Two paths — pick the one that matches your stack.
|
|
5
|
+
|
|
6
|
+
> **Testnet only.** Both paths use **Base Sepolia** so no real money moves.
|
|
7
|
+
> Switch `CHAIN_NAME=base` when you're ready for mainnet.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Prerequisites
|
|
12
|
+
|
|
13
|
+
1. **Testnet wallet** — any EOA private key (generate one with `cast wallet new` from Foundry, or MetaMask)
|
|
14
|
+
2. **Deployed AgentAccountV2** — run `npx clawpowers payments setup` for the interactive wizard
|
|
15
|
+
3. **Base Sepolia ETH (gas)** — free from [https://www.coinbase.com/faucets/base-ethereum-goerli-faucet](https://www.coinbase.com/faucets/base-ethereum-goerli-faucet)
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## .env Setup
|
|
20
|
+
|
|
21
|
+
Create a `.env` file (never commit this):
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
# .env — agent wallet config
|
|
25
|
+
AGENT_PRIVATE_KEY=0x... # EOA signing key (32-byte hex)
|
|
26
|
+
AGENT_WALLET_ADDRESS=0x... # AgentAccountV2 contract address
|
|
27
|
+
CHAIN_NAME=base-sepolia # Use Base Sepolia for testing
|
|
28
|
+
RPC_URL=https://sepolia.base.org
|
|
29
|
+
|
|
30
|
+
# Spending limits (USDC, 6 decimals)
|
|
31
|
+
SPEND_LIMIT_PER_TX=1.00 # Max USDC per single transaction
|
|
32
|
+
SPEND_LIMIT_DAILY=10.00 # Max USDC per 24-hour period
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Path A: JavaScript (agentwallet-sdk direct)
|
|
38
|
+
|
|
39
|
+
**Under 10 lines.** Uses the `walletFromEnv()` convenience wrapper so there's
|
|
40
|
+
no viem boilerplate.
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npm install agentwallet-sdk dotenv
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
```javascript
|
|
47
|
+
// first-tx.mjs
|
|
48
|
+
import 'dotenv/config';
|
|
49
|
+
import { walletFromEnv, setPolicyFromEnv, agentExecute } from 'agentwallet-sdk';
|
|
50
|
+
|
|
51
|
+
const wallet = await walletFromEnv(); // reads AGENT_PRIVATE_KEY + AGENT_WALLET_ADDRESS
|
|
52
|
+
await setPolicyFromEnv(wallet); // applies SPEND_LIMIT_PER_TX + SPEND_LIMIT_DAILY
|
|
53
|
+
|
|
54
|
+
const result = await agentExecute(wallet, {
|
|
55
|
+
to: '0x000000000000000000000000000000000000dEaD', // burn address (safe test target)
|
|
56
|
+
value: 1n, // 1 wei — near-zero cost
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
console.log(`✅ txHash: ${result.txHash}`);
|
|
60
|
+
console.log(` executed immediately: ${result.executed}`);
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
node first-tx.mjs
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
**Expected output:**
|
|
68
|
+
```
|
|
69
|
+
✅ txHash: 0x3a7f...c9e2
|
|
70
|
+
executed immediately: true
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
> If `executed: false` — the transaction was queued for owner approval because
|
|
74
|
+
> the amount exceeded your spend policy. Approve it with:
|
|
75
|
+
> ```bash
|
|
76
|
+
> node -e "
|
|
77
|
+
> import('agentwallet-sdk').then(async ({ walletFromEnv, getPendingApprovals, approveTransaction }) => {
|
|
78
|
+
> const w = walletFromEnv();
|
|
79
|
+
> const pending = await getPendingApprovals(w);
|
|
80
|
+
> if (pending.length > 0) await approveTransaction(w, pending[0].txId);
|
|
81
|
+
> console.log('Approved');
|
|
82
|
+
> });
|
|
83
|
+
> "
|
|
84
|
+
> ```
|
|
85
|
+
|
|
86
|
+
### What just happened
|
|
87
|
+
|
|
88
|
+
1. `walletFromEnv()` read your private key from `AGENT_PRIVATE_KEY`, connected
|
|
89
|
+
to Base Sepolia via `RPC_URL`, and instantiated the `AgentAccountV2` smart
|
|
90
|
+
wallet at `AGENT_WALLET_ADDRESS`.
|
|
91
|
+
2. `setPolicyFromEnv()` wrote a spend policy on-chain: USDC transfers up to
|
|
92
|
+
`SPEND_LIMIT_PER_TX` per tx and `SPEND_LIMIT_DAILY` per day execute
|
|
93
|
+
autonomously. Anything above is queued.
|
|
94
|
+
3. `agentExecute()` called `agentExecute()` on the smart contract, which checked
|
|
95
|
+
the native ETH policy and sent 1 wei to the burn address.
|
|
96
|
+
4. The tx hash was returned immediately — you can verify it on
|
|
97
|
+
[https://sepolia.basescan.org](https://sepolia.basescan.org/tx/{txHash}).
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Path B: Python (via agentpay-mcp over MCP)
|
|
102
|
+
|
|
103
|
+
**Under 15 lines.** Uses the official `mcp` Python SDK to connect to the
|
|
104
|
+
`agentpay-mcp` server and call `send_payment` over the Model Context Protocol.
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
pip install mcp python-dotenv
|
|
108
|
+
npx clawpowers mcp start # starts agentpay-mcp on stdio or a local port
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
# first_tx.py
|
|
113
|
+
import asyncio
|
|
114
|
+
import os
|
|
115
|
+
from dotenv import load_dotenv
|
|
116
|
+
from mcp import ClientSession, StdioServerParameters
|
|
117
|
+
from mcp.client.stdio import stdio_client
|
|
118
|
+
|
|
119
|
+
load_dotenv()
|
|
120
|
+
|
|
121
|
+
async def main():
|
|
122
|
+
server = StdioServerParameters(
|
|
123
|
+
command="npx",
|
|
124
|
+
args=["agentpay-mcp"],
|
|
125
|
+
env={**os.environ}, # passes AGENT_PRIVATE_KEY, AGENT_WALLET_ADDRESS, etc.
|
|
126
|
+
)
|
|
127
|
+
async with stdio_client(server) as (read, write):
|
|
128
|
+
async with ClientSession(read, write) as session:
|
|
129
|
+
await session.initialize()
|
|
130
|
+
|
|
131
|
+
result = await session.call_tool("send_payment", {
|
|
132
|
+
"to": "0x000000000000000000000000000000000000dEaD",
|
|
133
|
+
"amount": "0.001", # USDC
|
|
134
|
+
"asset": "USDC",
|
|
135
|
+
"chain": "base-sepolia",
|
|
136
|
+
"reason": "first transaction test",
|
|
137
|
+
})
|
|
138
|
+
print(f"✅ txHash: {result.content[0].text}")
|
|
139
|
+
|
|
140
|
+
asyncio.run(main())
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
python first_tx.py
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
**Expected output:**
|
|
148
|
+
```
|
|
149
|
+
✅ txHash: 0x8b2d...f410
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### What just happened
|
|
153
|
+
|
|
154
|
+
1. `stdio_client` spawned `agentpay-mcp` as a subprocess — the MCP server
|
|
155
|
+
loaded your `.env` credentials and connected to Base Sepolia.
|
|
156
|
+
2. `session.call_tool("send_payment", ...)` sent an MCP tool call over stdio,
|
|
157
|
+
which the server translated into an `agentTransferToken()` call on your
|
|
158
|
+
`AgentAccountV2` smart wallet.
|
|
159
|
+
3. The server returned the transaction hash, which you can verify at
|
|
160
|
+
[https://sepolia.basescan.org](https://sepolia.basescan.org).
|
|
161
|
+
|
|
162
|
+
> **Python + MCP** is ideal when your agent framework is Python-based
|
|
163
|
+
> (LangChain, AutoGen, CrewAI) and you want to avoid writing viem/TypeScript.
|
|
164
|
+
> The MCP server handles all wallet logic; your Python code just calls tools.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Verify Your Transaction
|
|
169
|
+
|
|
170
|
+
Both paths produce a `txHash`. Verify on-chain:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
# Quick verification via cast (Foundry)
|
|
174
|
+
cast tx $TX_HASH --rpc-url https://sepolia.base.org
|
|
175
|
+
|
|
176
|
+
# Or open in browser
|
|
177
|
+
echo "https://sepolia.basescan.org/tx/$TX_HASH"
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Next Steps
|
|
183
|
+
|
|
184
|
+
| Goal | Resource |
|
|
185
|
+
|------|----------|
|
|
186
|
+
| Set up x402 automatic payments | `skills/agent-payments/SKILL.md` |
|
|
187
|
+
| Enable premium enrichment in prospecting | `skills/prospecting/SKILL.md` → "Premium Enrichment" section |
|
|
188
|
+
| Post a task bounty for another agent | `skills/agent-bounties/SKILL.md` |
|
|
189
|
+
| Review payment history | `npx clawpowers payments log` |
|
|
190
|
+
| Configure spending limits interactively | `npx clawpowers payments setup` (setup wizard) |
|
|
191
|
+
| Demo — see the full x402 flow in 60s | `runtime/demo/README.md` |
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Troubleshooting
|
|
196
|
+
|
|
197
|
+
| Error | Fix |
|
|
198
|
+
|-------|-----|
|
|
199
|
+
| `AGENT_PRIVATE_KEY environment variable is required` | Check your `.env` file exists and is loaded |
|
|
200
|
+
| `Unsupported chain: base-sepolia` | Ensure `agentwallet-sdk` is v0.3+ |
|
|
201
|
+
| `executed: false` (queued) | Amount > spend policy; lower `SPEND_LIMIT_PER_TX` or approve manually |
|
|
202
|
+
| `insufficient funds` | Get Base Sepolia ETH from the faucet link above |
|
|
203
|
+
| `nonce too low` | Another tx is pending; wait for confirmation or reset nonce |
|
|
204
|
+
| MCP: `spawn npx ENOENT` | Run `npm install -g agentpay-mcp` or use `npx --yes` |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "clawpowers",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.3",
|
|
4
4
|
"description": "The skills framework that actually does something — runtime execution, persistent memory, self-improvement, and autonomous payments for coding agents.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "AI Agent Economy <https://github.com/up2itnow0822>",
|