{"_id":"@claw_wallet/claw-wallet-sdk","name":"@claw_wallet/claw-wallet-sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@claw_wallet/claw-wallet-sdk","version":"0.2.0","description":"Stripe for AI Agent Wallets — Add wallet functionality to any AI agent in seconds","main":"src/index.js","types":"src/index.d.ts","type":"module","bin":{"claw-wallet":"cli.js"},"exports":{".":{"import":"./src/index.js","types":"./src/index.d.ts"},"./sdk":{"import":"./sdk.js","types":"./sdk.d.ts"},"./cli":"./cli.js"},"scripts":{"start":"node src/index.js","dev":"node --watch src/index.js","demo":"node demo.js","cli":"node cli.js","test":"node tests/run-tests.js","test:all":"node tests/run-all-tests.js","test:policy":"node tests/test-policy.js","test:wallet":"node tests/test-wallet.js","test:auth":"node tests/test-auth.js","test:rate-limit":"node tests/test-rate-limit.js","test:hitl":"node tests/test-hitl.js","prepublishOnly":"npm test","test:auth:security":"node tests/test-auth-security.js"},"keywords":["ai","agent","wallet","crypto","ethereum","base","blockchain","viem","solana","sui","aptos","starknet","multi-chain","ai-wallet","agent-wallet","mcp","model-context-protocol","erc-8004","agent-identity"],"author":{"name":"Mr. Claw"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/Vibes-me/Claw-wallet.git","directory":"agent-wallet-service"},"bugs":{"url":"https://github.com/Vibes-me/Claw-wallet/issues"},"homepage":"https://github.com/Vibes-me/Claw-wallet#readme","dependencies":{"@aptos-labs/ts-sdk":"^6.2.0","@coinbase/agentkit":"^0.2.3","@modelcontextprotocol/sdk":"^1.27.1","@mysten/sui":"^2.7.0","@solana/spl-token":"^0.4.0","@solana/web3.js":"^1.91.0","chalk":"^5.6.2","commander":"^14.0.3","dotenv":"^16.6.1","express":"^4.18.2","inquirer":"^13.3.0","ioredis":"^5.4.1","ora":"^9.3.0","pg":"^8.11.5","pino":"^8.19.0","pino-pretty":"^11.0.0","starknet":"^5.25.0","viem":"^2.47.2","zod":"^3.22.4"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"_id":"@claw_wallet/claw-wallet-sdk@0.2.0","gitHead":"d8cca2b0e20c0ce957aa99f895f72778f4bca4a5","_nodeVersion":"22.21.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-yoxVQ2T7wnfA/ogKwhLUUABi8igfGt07WWPjObJeOwgvymtgQCXgER2cVeyYsbMzJbMChUYveNJ3Tt9DCBFBuA==","shasum":"eb2eb0e81248324670fad27628212931d9a0507c","tarball":"https://registry.npmjs.org/@claw_wallet/claw-wallet-sdk/-/claw-wallet-sdk-0.2.0.tgz","fileCount":71,"unpackedSize":678770,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDY2Qijxsl0WczbmsWxFGf0al/EVRBwy40hoo4OIn0GsgIhAMgGGmrvY4EsnneNXEJHp+t0rwGgXSS36WRCuIpUUnE+"}]},"_npmUser":{"name":"claw_wallet","email":"neo.kunal.s@proton.me"},"directories":{},"maintainers":[{"name":"claw_wallet","email":"neo.kunal.s@proton.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claw-wallet-sdk_0.2.0_1773561994467_0.44161864252870275"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-15T08:06:34.298Z","0.2.0":"2026-03-15T08:06:34.628Z","modified":"2026-03-15T08:06:34.902Z"},"maintainers":[{"name":"claw_wallet","email":"neo.kunal.s@proton.me"}],"description":"Stripe for AI Agent Wallets — Add wallet functionality to any AI agent in seconds","homepage":"https://github.com/Vibes-me/Claw-wallet#readme","keywords":["ai","agent","wallet","crypto","ethereum","base","blockchain","viem","solana","sui","aptos","starknet","multi-chain","ai-wallet","agent-wallet","mcp","model-context-protocol","erc-8004","agent-identity"],"repository":{"type":"git","url":"git+https://github.com/Vibes-me/Claw-wallet.git","directory":"agent-wallet-service"},"author":{"name":"Mr. Claw"},"bugs":{"url":"https://github.com/Vibes-me/Claw-wallet/issues"},"license":"Apache-2.0","readme":"# Agent Wallet Service\n\n**Stripe for AI Agent Wallets**\n\nAdd wallet functionality to any AI agent in seconds. No blockchain SDKs, no key management, no contract deployment.\n\n## 5-minute Quickstart (copy once)\n\n> Goal: start the server, create a scoped API key, create a wallet, and verify balance with one paste.\n\n### 0) Start the service\n\n```bash\nnpm install\nnpm start\n```\n\n### 1) In a second terminal, run this single block\n\n```bash\nset -euo pipefail\n\nif ! command -v jq >/dev/null 2>&1; then\n  echo \"jq is required for this copy-once flow.\"\n  echo \"Install jq: brew install jq   # macOS\"\n  echo \"         sudo apt-get install jq   # Debian/Ubuntu\"\n  echo \"Or use CLI onboarding instead: node cli.js setup --init\"\n  exit 1\nfi\n\n# Edit only if your server is not on localhost:3000\nexport AGENT_WALLET_API=\"http://localhost:3000\"\n\n# 1) Obtain bootstrap admin key (one-time setup mode)\n#    Run the server once with SHOW_BOOTSTRAP_SECRET=true to print the full key.\n#    The key is not stored in plaintext on disk.\nexport BOOTSTRAP_KEY=\"<paste_bootstrap_key_from_startup_log>\"\necho \"bootstrap key: ${BOOTSTRAP_KEY:0:12}...\"\n\n# 2) Create scoped app key (read/write)\nAPP_KEY_JSON=\"$(curl -sS -X POST \"$AGENT_WALLET_API/api-keys\" \\\n  -H 'Content-Type: application/json' \\\n  -H \"X-API-Key: $BOOTSTRAP_KEY\" \\\n  -d '{\"name\":\"quickstart\",\"permissions\":[\"read\",\"write\"]}')\"\n\necho \"$APP_KEY_JSON\" | jq -e '.success == true and (.key.key | startswith(\"sk_\"))' >/dev/null\nexport AGENT_WALLET_API_KEY=\"$(echo \"$APP_KEY_JSON\" | jq -r '.key.key')\"\necho \"✅ key created: ${AGENT_WALLET_API_KEY:0:12}...\"\n\n# 3) Create wallet\nWALLET_JSON=\"$(curl -sS -X POST \"$AGENT_WALLET_API/wallet/create\" \\\n  -H 'Content-Type: application/json' \\\n  -H \"X-API-Key: $AGENT_WALLET_API_KEY\" \\\n  -d '{\"agentName\":\"QuickstartBot\",\"chain\":\"base-sepolia\"}')\"\n\necho \"$WALLET_JSON\" | jq -e '.success == true and (.wallet.address | startswith(\"0x\"))' >/dev/null\nexport FROM_WALLET=\"$(echo \"$WALLET_JSON\" | jq -r '.wallet.address')\"\necho \"✅ wallet created: $FROM_WALLET\"\n\n# 4) Verify balance\nBALANCE_JSON=\"$(curl -sS \"$AGENT_WALLET_API/wallet/$FROM_WALLET/balance?chain=base-sepolia\" \\\n  -H \"X-API-Key: $AGENT_WALLET_API_KEY\")\"\n\necho \"$BALANCE_JSON\" | jq -e '.balance.chain == \"base-sepolia\"' >/dev/null\necho \"$BALANCE_JSON\" | jq '{chain: .balance.chain, eth: .balance.eth, rpc: .balance.rpc}'\necho \"✅ balance verified\"\n```\n\n### No `jq`?\n\nUse CLI onboarding instead (no JSON parsing required):\n\n```bash\nnode cli.js setup --init\n```\n\n---\n\n## Status: ✅ Production Ready v0.1.0\n\n- Multi-chain support (9 chains)\n- ERC-8004 AI Agent Identity\n- API key authentication\n- Full CLI + SDK\n\n## Features\n\n### 🔗 Multi-Chain Support\n\n| Testnets | Mainnets |\n|----------|----------|\n| base-sepolia ✓ | base |\n| ethereum-sepolia ✓ | ethereum |\n| optimism-sepolia ✓ | polygon |\n| arbitrum-sepolia ✓ | optimism |\n| | arbitrum |\n\nEach chain has fallback RPCs for reliability.\n\n### 🆔 ERC-8004 Agent Identity\n\nOn-chain identity for AI agents:\n- Verifiable agent IDs\n- Capability tracking\n- W3C Verifiable Credentials compatible\n- Agent types: `assistant`, `autonomous`, `hybrid`\n\n### 🔐 API Key Authentication\n\n- Generate/revoke API keys (header transport only)\n- API keys are hashed at rest in `api-keys.json`\n- Role-based permissions (read/write/admin)\n- Weighted rate limiting built-in (route-aware costs)\n- Tier-aware limits (`free`, `pro`, `enterprise`)\n- RPC mode by tier:\n  - `tier:free` => BYO RPC required on chain-call wallet routes\n  - `tier:pro` / `tier:enterprise` => managed RPC\n- Rate limit headers: `RateLimit-*`, `X-RateLimit-*`, `Retry-After`\n\n### 🛡️ Policy Engine Guardrails\n\n- Per-wallet transfer limits (`perTxLimitEth`, `dailyLimitEth`)\n- Recipient allowlist/denylist\n- Policy simulation endpoint before sending funds\n\n## Role-specific snippets\n\n### 1) Backend API service (server-to-server)\n\n```bash\n# health\ncurl -s http://localhost:3000/health\n\n# check a wallet balance\ncurl -s \"http://localhost:3000/wallet/0xYourWallet/balance?chain=base-sepolia\" \\\n  -H \"X-API-Key: $API_KEY\"\n```\n\n### 2) CLI-only operator\n\n```bash\n# via package script\nnpm run cli -- create OpsBot base-sepolia\nnpm run cli -- list\nnpm run cli -- chains\nnpm run cli -- balance 0xYourWallet\nnpm run cli -- send 0xFrom 0xTo 0.001\n```\n\n### 3) SDK integration (Node)\n\n```javascript\nimport AgentWallet from './sdk.js';\n\nconst wallet = new AgentWallet('http://localhost:3000');\n\nconst created = await wallet.createWallet('SdkBot');\nconst balance = await wallet.getBalance(created.wallet.address);\nconst tx = await wallet.send(created.wallet.address, '0x000000000000000000000000000000000000dead', '0.000001');\nconsole.log({ created, balance, tx });\n```\n\n### Free tier: BYO RPC (Alchemy)\n\nCreate a free key:\n\n```bash\ncurl -X POST http://localhost:3000/api-keys \\\n  -H 'Content-Type: application/json' \\\n  -H \"X-API-Key: $BOOTSTRAP_KEY\" \\\n  -d '{\"name\":\"free-key\",\"permissions\":[\"read\",\"write\",\"tier:free\"]}'\n```\n\nUse that key with your own RPC URL on chain-call wallet routes:\n\n```bash\ncurl \"http://localhost:3000/wallet/$FROM_WALLET/balance?chain=base-sepolia\" \\\n  -H \"X-API-Key: $FREE_KEY\" \\\n  -H \"X-RPC-URL: https://base-sepolia.g.alchemy.com/v2/<ALCHEMY_KEY>\"\n```\n\nSupported BYO input fields:\n- Header: `X-RPC-URL`\n- Query: `?rpcUrl=...`\n- Body: `{ \"rpcUrl\": \"...\" }`\n\n### First-run onboarding\n\nUse the **copy-once quickstart** at the top of this README, or run:\n\n```bash\nnode cli.js setup --init\n```\n\n## CLI Usage\n\n```bash\n# Wallet commands\nnode cli.js create MyBot base-sepolia\nnode cli.js balance 0x...\nnode cli.js balances 0x...          # All chains\nnode cli.js send 0xfrom 0xto 0.001\nnode cli.js sweep 0xfrom 0xto       # Send all funds\nnode cli.js estimate 0xfrom 0xto 0.001\nnode cli.js list\nnode cli.js chains\n\n# Identity commands (ERC-8004)\nnode cli.js identity create 0xwallet BotName assistant\nnode cli.js identity list\nnode cli.js identity get agent:xxx\nnode cli.js identity wallet 0xaddress\n\n# ENS commands\nnode cli.js ens list\nnode cli.js ens get myagent.eth\nnode cli.js ens check myagent.eth\n\n# Setup helper\nnode cli.js setup\nnode cli.js setup --init   # health + onboarding + scoped key + .env.local\n\n# Demo\nnode cli.js demo\n```\n\n## API Endpoints (runtime)\n\n### Core + API key management\n\n```\nGET    /                                 Service metadata\nGET    /health                           Health + features + endpoint index\nGET    /dashboard                        Dashboard metadata + links\nGET    /onboarding                       Onboarding metadata + examples\nPOST   /api-keys                         Create API key (admin)\nGET    /api-keys                         List API keys (admin)\nDELETE /api-keys/:prefix                 Revoke API key (admin)\n```\n\n### Wallet\n\n```\nPOST /wallet/create                      Create new wallet\nPOST /wallet/import                      Import from private key\nGET  /wallet/list                        List all wallets\nGET  /wallet/chains                      Supported chains\nGET  /wallet/fees                        Fee configuration\nGET  /wallet/history                     Global transaction history\nGET  /wallet/tx/:hash                    Transaction status/receipt (free tier requires BYO rpcUrl)\nPOST /wallet/estimate-gas                Estimate gas cost (free tier requires BYO rpcUrl)\n\nGET  /wallet/:address                    Wallet details\nGET  /wallet/:address/balance            Balance on wallet chain (or ?chain=) (free tier requires BYO rpcUrl)\nGET  /wallet/:address/balance/all        Balance across all chains (managed tiers only)\nGET  /wallet/:address/history            Wallet transaction history\nPOST /wallet/:address/send               Send transaction (free tier requires BYO rpcUrl)\nPOST /wallet/:address/sweep              Sweep all funds (free tier requires BYO rpcUrl)\n```\n\n### Identity (ERC-8004)\n\n```\nPOST  /identity/create                   Create agent identity\nGET   /identity/list                     List all identities\nGET   /identity/types                    Agent types\nGET   /identity/capabilities             Supported capabilities\nGET   /identity/wallet/:address          Identities by wallet\nGET   /identity/:agentId                 Get identity\nPATCH /identity/:agentId/capability      Update capability\nPOST  /identity/:agentId/revoke          Revoke identity\nGET   /identity/:agentId/credential      W3C Verifiable Credential\n```\n\n### ENS\n\n```\nGET  /ens/check/:name                    Check ENS availability\nGET  /ens/price/:name                    Get registration price\nPOST /ens/register                       Register ENS name\nGET  /ens/list                           List managed ENS names\nGET  /ens/:name                          Resolve ENS details\n```\n\n## Error envelope\n\nAll API errors now use a single response shape:\n\n```json\n{\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Validation failed\",\n    \"details\": [\n      { \"field\": \"agentName\", \"message\": \"Required\" }\n    ]\n  }\n}\n```\n\nExamples by status code:\n\n```json\n// 401\n{ \"error\": { \"code\": \"API_KEY_REQUIRED\", \"message\": \"API key required\" } }\n\n// 403\n{ \"error\": { \"code\": \"API_KEY_INVALID\", \"message\": \"Invalid API key\" } }\n\n// 404\n{ \"error\": { \"code\": \"IDENTITY_NOT_FOUND\", \"message\": \"Identity not found\" } }\n\n// 429\n{ \"error\": { \"code\": \"RATE_LIMIT_EXCEEDED\", \"message\": \"Rate limit exceeded\" } }\n\n// 500\n{ \"error\": { \"code\": \"INTERNAL_ERROR\", \"message\": \"Internal server error\" } }\n```\n\n## Common errors\n\n| Error case | HTTP status | Typical message | What to do |\n|---|---:|---|---|\n| Missing API key | 401 | `API key required` | Send `X-API-Key` header. Query param auth is rejected by default. |\n| Invalid API key | 403 | `Invalid API key` | Ensure the key exists and has not been revoked. |\n| Free-tier missing RPC URL | 400 | `Free-tier API keys must provide a BYO RPC URL` | Send `X-RPC-URL` header (or `rpcUrl` query/body). |\n| Free-tier balance/all call | 403 | `BYO RPC does not support /balance/all` | Use `GET /wallet/:address/balance?chain=...&rpcUrl=...` instead. |\n| Invalid chain | 400 or 500 | `Unsupported chain` / chain validation error | Call `GET /wallet/chains` and use one of the returned chain IDs. |\n| Insufficient funds | 500 | `insufficient funds` | Fund the sender on the same chain and reduce transfer amount to account for gas. |\n| RPC fallback failures | 500 | `All RPC endpoints failed` / transport errors | Retry shortly; verify RPC/network connectivity and try another supported chain. |\n\n## Rate limit tuning\n\n- Set `RATE_LIMIT_STRATEGY` (`memory` for local dev, `redis` for distributed/prod; default: `memory`).\n- Set `RATE_LIMIT_WINDOW_MS` (default: `60000`).\n- Set per-tier limits:\n  - `RATE_LIMIT_MAX_POINTS_FREE` (default: `100`)\n  - `RATE_LIMIT_MAX_POINTS_PRO` (default: `300`)\n  - `RATE_LIMIT_MAX_POINTS_ENTERPRISE` (default: `1000`)\n- Set request costs:\n  - `RATE_LIMIT_COST_READ` (default: `1`)\n  - `RATE_LIMIT_COST_WRITE` (default: `2`)\n  - `RATE_LIMIT_COST_EXPENSIVE` (default: `10`)\n- Assign tier on key creation via permission tag, e.g. `[\"read\",\"write\",\"tier:pro\"]`.\n- Free-tier (`tier:free`) keys must provide BYO RPC URL (`X-RPC-URL`, `rpcUrl` query/body).\n- Restrict BYO hosts via `BYO_RPC_ALLOWED_HOSTS` (default: `*.g.alchemy.com,*.alchemy.com`).\n- When using `RATE_LIMIT_STRATEGY=redis`, set `REDIS_URL` and ensure Redis is reachable from all instances.\n\n## Security migration notes\n\n- `api-keys.json` now stores `{ keyHash, keyPrefix, ... }` only. Plain API keys are never persisted.\n- If you already had plaintext `api-keys.json` entries, they are migrated to hashed records on startup.\n- Query parameter auth (`?apiKey=`) is disabled by default. Use `X-API-Key` header.\n- Temporary local fallback is available only in non-production by setting `ALLOW_QUERY_API_KEY_FALLBACK=true`.\n- `SHOW_BOOTSTRAP_SECRET=true` is intended for explicit one-time setup only and is ignored in production.\n\n## Architecture\n\n```\nsrc/\n├── index.js                    Express server\n├── routes/\n│   ├── wallet.js               Wallet endpoints\n│   └── identity.js             ERC-8004 endpoints\n├── services/\n│   ├── viem-wallet.js          Core wallet ops\n│   ├── agent-identity.js       ERC-8004 identity\n│   ├── fee-collector.js        Fee calculations\n│   └── tx-history.js           Transaction logging\n└── middleware/\n    └── auth.js                 Canonical API key auth + weighted rate limiting\n```\n\n## Live Transaction\n\nFirst successful transaction on Base Sepolia:\n```\n0x7f8feba9bd220fdee58499422135f2cafab818a829d76e72d17273e50d3e3a6c\n```\n\n## Coming Soon\n\n- [ ] Public deployment\n- [ ] NPM package\n- [ ] Web dashboard\n- [ ] Webhook notifications\n- [ ] Multi-signature wallets\n\n## Positioning\n\n> \"Add a wallet to any agent in 60 seconds. Your agent can hold funds, pay for services, and earn fees — without touching a single blockchain SDK, managing private keys, or deploying smart contracts.\"\n\n---\n\nBuilt by Mr. Claw 🦞\n\n\n## Policy Example\n\n```bash\n# Set policy for a wallet\ncurl -X PUT http://localhost:3000/wallet/policy/$FROM_WALLET \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $API_KEY\" \\\n  -d '{\n    \"dailyLimitEth\": \"0.05\",\n    \"perTxLimitEth\": \"0.01\",\n    \"allowedRecipients\": [\"0xabc...\"],\n    \"blockedRecipients\": []\n  }'\n\n# Check if a transfer would pass policy\ncurl -X POST http://localhost:3000/wallet/policy/$FROM_WALLET/evaluate \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $API_KEY\" \\\n  -d '{\"to\":\"0xabc...\",\"value\":\"0.005\",\"chain\":\"base-sepolia\"}'\n```\n","readmeFilename":"README.md","_rev":"1-dd40a0d685fd2286b556d71cf4edc844"}