{"_id":"botpay","_rev":"46-8126e822d724ea3a62e9f2fc709f109f","name":"botpay","dist-tags":{"latest":"0.4.0"},"versions":{"0.3.3":{"name":"botpay","version":"0.3.3","keywords":["botpay","x402","mcp","agent-skills","cursor","claude-code","codex","openclaw","hermes-agent","manus","agent-payment","usdc","ai-agent"],"author":{"name":"BotYi Labs"},"license":"MIT","_id":"botpay@0.3.3","maintainers":[{"name":"alexwang47","email":"alexwang47@126.com"}],"bin":{"botpay":"bin/botpay.js","botpay-mcp":"bin/botpay-mcp.js"},"dist":{"shasum":"9a7f654ddecf545ee0c9e089d52706278ad4458d","tarball":"https://registry.npmjs.org/botpay/-/botpay-0.3.3.tgz","fileCount":25,"integrity":"sha512-4N2CujDCugKhMt/Lsj4H4X/CWGsjepe1Y5do7o2Cr6X3fAdShu0XEjyoRw78AHh4jOEq8zk4ePJAEo2j2vmTGw==","signatures":[{"sig":"MEUCIFPl3BxM2nW3rV5r/9qoQ5jY5AuOg2CTSKTmkX2lbpFGAiEA9erkgDbNysglyFwqoha38yCqOyTis9tVD/KiGJ/+gDI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":171062},"type":"module","engines":{"node":">=20"},"scripts":{"test":"node --test","check":"node --check bin/botpay.js && node --check bin/botpay-mcp.js && node --check src/cli.js && node --check src/mcp.js && node --check src/agent-integration.js && node --check src/walletconnect-topup.js","prepublishOnly":"npm run check && npm test"},"_npmUser":{"name":"alexwang47","email":"alexwang47@126.com"},"_npmVersion":"11.6.2","description":"Developer CLI for free x402 Bazaar discovery, direct payments, BotPay services, and escrow vouchers","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^4.4.3","viem":"^2.54.1","yaml":"^2.9.0","dotenv":"^17.4.2","ethers":"^6.16.0","fflate":"^0.8.3","@x402/evm":"^2.17.0","commander":"^14.0.3","@x402/core":"^2.17.0","qrcode-terminal":"^0.12.0","@modelcontextprotocol/sdk":"^1.29.0","@walletconnect/sign-client":"^2.23.9"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/botpay_0.3.3_1786881738917_0.7854892715315147","host":"s3://npm-registry-packages-npm-production"}},"0.3.4":{"name":"botpay","version":"0.3.4","keywords":["botpay","x402","mcp","agent-skills","cursor","claude-code","codex","openclaw","hermes-agent","manus","agent-payment","usdc","ai-agent"],"author":{"name":"BotYi Labs"},"license":"MIT","_id":"botpay@0.3.4","maintainers":[{"name":"alexwang47","email":"alexwang47@126.com"}],"bin":{"botpay":"bin/botpay.js","botpay-mcp":"bin/botpay-mcp.js"},"dist":{"shasum":"80009f37f9de29c69eeab0fe8f428312f7cc084f","tarball":"https://registry.npmjs.org/botpay/-/botpay-0.3.4.tgz","fileCount":25,"integrity":"sha512-3K1l8hDiXsqIpSwQAb1B6vAca7u38+f7E1nXMk7GmVkeFYrGO7FLedOo9i4kmsylEWJl258v82mJ3+qZ/s9O2A==","signatures":[{"sig":"MEUCIQCxeK0pSHOt3k8pMNktwuP6YqO7opTX8cndqJSsuoV5awIgC7IhNOA+VPTeXxfpJ3KT2P5WwsCuYCv5o4O7GiipM+8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":181021},"type":"module","engines":{"node":">=20"},"scripts":{"test":"node --test","check":"node --check bin/botpay.js && node --check bin/botpay-mcp.js && node --check src/cli.js && node --check src/mcp.js && node --check src/agent-integration.js && node --check src/walletconnect-topup.js","prepublishOnly":"npm run check && npm test"},"_npmUser":{"name":"alexwang47","email":"alexwang47@126.com"},"_npmVersion":"11.6.2","description":"Developer CLI for gated x402 Bazaar access, direct payments, BotPay services, and escrow vouchers","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^4.4.3","viem":"^2.54.1","yaml":"^2.9.0","dotenv":"^17.4.2","ethers":"^6.16.0","fflate":"^0.8.3","@x402/evm":"^2.17.0","commander":"^14.0.3","@x402/core":"^2.17.0","qrcode-terminal":"^0.12.0","@modelcontextprotocol/sdk":"^1.29.0","@walletconnect/sign-client":"^2.23.9"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/botpay_0.3.4_1788185201555_0.7486544291608239","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"botpay","version":"0.4.0","description":"Production x402 CLI with paid BotPay /go access to guarded exchange MCP tools","type":"module","bin":{"botpay":"bin/botpay.js","botpay-mcp":"bin/botpay-mcp.js"},"engines":{"node":">=20"},"scripts":{"test":"node --test","check":"node --check bin/botpay.js && node --check bin/botpay-mcp.js && node --check src/cli.js && node --check src/mcp.js && node --check src/agent-integration.js && node --check src/go-connector.js && node --check src/walletconnect-topup.js","prepublishOnly":"npm run check && npm test"},"keywords":["botpay","x402","mcp","agent-skills","cursor","claude-code","codex","openclaw","hermes-agent","manus","agent-payment","usdc","ai-agent","agent-trading","polymarket","binance"],"author":{"name":"BotYi Labs"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","@walletconnect/sign-client":"^2.23.9","@x402/core":"^2.17.0","@x402/evm":"^2.17.0","commander":"^14.0.3","dotenv":"^17.4.2","ethers":"^6.16.0","fflate":"^0.8.3","qrcode-terminal":"^0.12.0","viem":"^2.54.1","yaml":"^2.9.0","zod":"^4.4.3"},"overrides":{"qs":"6.16.0"},"_id":"botpay@0.4.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-mo0Xpx/uRfeVIIATH0Ifci6ZmtB6tqh1ocaPpw1T7zNHuu+w0jomXofFyGCpfajRvqGLdA+/sWslY1ERSnXMZQ==","shasum":"4c53ada463ba9ac6c652014b292a72afcb6d1817","tarball":"https://registry.npmjs.org/botpay/-/botpay-0.4.0.tgz","fileCount":26,"unpackedSize":190828,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCGPRRq3IxQdjz1XxkOtG26pMlndIjYAvKDtCzlDvkgNgIhAPkaTdsEn9mKZKTAjIYr6JFa3vVqswop3PS3Ylc364mE"}]},"_npmUser":{"name":"alexwang47","email":"alexwang47@126.com"},"directories":{},"maintainers":[{"name":"alexwang47","email":"alexwang47@126.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/botpay_0.4.0_1788365436776_0.5903770264022206"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-31T02:54:05.335Z","modified":"2026-09-02T16:10:37.336Z","0.1.0":"2026-05-31T02:54:05.520Z","0.1.1":"2026-05-31T03:12:53.741Z","0.1.3":"2026-06-09T18:07:42.070Z","0.1.4":"2026-06-16T08:39:50.651Z","0.1.5":"2026-06-16T15:00:16.610Z","0.1.6":"2026-06-17T11:57:26.214Z","0.1.7":"2026-06-17T12:23:31.865Z","0.1.8":"2026-07-03T09:15:44.497Z","0.1.9":"2026-07-03T11:45:48.757Z","0.1.10":"2026-07-03T13:18:07.684Z","0.1.11":"2026-07-04T08:56:10.115Z","0.1.12":"2026-07-07T16:59:57.099Z","0.1.14":"2026-07-09T08:13:40.188Z","0.2.1":"2026-07-11T02:09:38.810Z","0.2.2":"2026-07-11T02:18:01.512Z","0.2.3":"2026-07-14T02:33:15.946Z","0.2.4":"2026-07-14T09:49:04.953Z","0.2.5":"2026-07-18T10:18:40.862Z","0.3.0":"2026-07-21T14:36:39.163Z","0.3.1":"2026-07-22T11:00:02.876Z","0.3.2":"2026-08-13T11:47:54.838Z","0.3.3":"2026-08-16T12:02:19.057Z","0.3.4":"2026-08-31T14:06:41.697Z","0.4.0":"2026-09-02T16:10:36.917Z"},"author":{"name":"BotYi Labs"},"license":"MIT","keywords":["botpay","x402","mcp","agent-skills","cursor","claude-code","codex","openclaw","hermes-agent","manus","agent-payment","usdc","ai-agent","agent-trading","polymarket","binance"],"description":"Production x402 CLI with paid BotPay /go access to guarded exchange MCP tools","maintainers":[{"name":"alexwang47","email":"alexwang47@126.com"}],"readme":"# BotPay CLI\n\nBotPay is a production CLI for x402 service discovery, direct Agent wallet payments, and paid access to the guarded BotPay `/go` exchange MCP. Bazaar commands are unlocked locally by one successful `0.01 USDC` `/pay` purchase; the `/go` connector is unlocked separately by one successful `0.10 USDC` `/go` purchase.\n\nThe payment path is direct:\n\n```text\ndeveloper or agent -> BotPay CLI -> seller x402 endpoint -> seller/facilitator\n```\n\n## Principles\n\n- Explicit access: Bazaar commands require a successful local `/pay` receipt; `/openapi.json` and `/.well-known/x402` origin inspection remain free.\n- Separate authorities: a paid `/go` receipt unlocks the trading connector, but never approves an exchange order. Live orders require a separate operator approval in the trading gateway.\n- No hidden payments: commands transfer USDC only when `--yes` is present.\n- Direct settlement: BotPay signs the seller's x402 challenge with the local Agent wallet.\n- Constrained signing: network, asset, maximum/exact amount, `payTo`, and cross-origin resource changes are checked before signing.\n- Escrow vouchers remain supported.\n- Stable JSON output is available with `--json`.\n\n## Install\n\n```bash\nnpm install -g botpay\nbotpay --help\nbotpay wallet init\n```\n\nRunning `--help`, `services`, `bazaar`, `discover`, `check`, or a payment plan does not create a wallet automatically.\n\nFund the local Agent wallet with Base USDC (beta limit: 5 USDC):\n\n```bash\n# Scan a WalletConnect QR code and approve a direct Base USDC transfer\nnpx botpay wallet topup --method walletconnect --amount 1 --yes\n\n# Redeem Scan Credits at 200 Credits per USDC through gasless x402/PayAI\nnpx botpay login\nnpx botpay wallet topup --method scan --amount 1 --yes\n```\n\nWithout `--yes`, either command prints a plan and changes nothing. Reuse\n`--idempotency-key` when retrying the same Scan redemption.\n\n## Codex, Cursor, Claude Code, OpenClaw, Hermes, and Manus\n\nBotPay includes a standard stdio MCP server, so compatible Agent clients can discover typed BotPay tools for services, Bazaar search/list/stats, origin discovery, endpoint inspection, wallet balance, payment planning, and guarded service execution.\n\nCodex:\n\n```bash\ncodex mcp add botpay -- npx -y botpay@latest mcp\n```\n\nClaude Code:\n\n```bash\nclaude mcp add --transport stdio --scope user botpay -- npx -y botpay@latest mcp\n```\n\nCursor project configuration (`.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"botpay\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"botpay@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nOther stdio MCP clients can use the same command: `npx -y botpay@latest mcp`. The separate `botpay-mcp` executable is also included for globally installed packages.\n\nAfter purchasing `/go` access, add the guarded trading MCP as a second server:\n\n```bash\nbotpay plan go\nbotpay execute go --yes\nbotpay go status\ncodex mcp add botpay-go -- npx -y botpay@latest go mcp\n```\n\nClaude Code uses `claude mcp add --transport stdio --scope user botpay-go -- npx -y botpay@latest go mcp`. Cursor and other stdio clients use command `npx` with arguments `-y`, `botpay@latest`, `go`, `mcp`. The connector runs `read_only` by default. Configure exchange secrets only in the trusted gateway environment, never in Agent prompts or skill files.\n\nBotPay also ships one portable [Agent Skills](https://agentskills.io) skill. Install every supported local integration and create a Manus upload bundle:\n\n```bash\nbotpay agent install --target all\n```\n\nUse `--project .` for repository-scoped installation, or select one client with `--target codex`, `--target cursor`, `--target claude`, `--target openclaw`, `--target hermes`, or `--target manus`. Reload the local client after installation. The skill prefers MCP and falls back to stable `--json` CLI commands when an Agent has shell access but no MCP configuration.\n\nOpenClaw installs the Skill in its native location and configures the BotPay stdio MCP server when the `openclaw` executable is available:\n\n```bash\nnpx -y botpay@latest agent install --target openclaw\n```\n\nThe installer also runs `openclaw mcp doctor botpay --probe`. If OpenClaw is not on `PATH`, it still installs the Skill and prints the exact MCP setup command instead of reporting a false success.\n\nHermes installs the Skill in `$HERMES_HOME/skills/botpay` (or `~/.hermes/skills/botpay` by default), safely merges the BotPay server into the matching `config.yaml`, preserves existing configuration and comments, and runs `hermes mcp test botpay` when the Hermes executable is available:\n\n```bash\nnpx -y botpay@latest agent install --target hermes\n```\n\nFor a project-scoped Hermes install, BotPay also adds that project's `.agents/skills` directory to Hermes `skills.external_dirs`.\n\nManus runs in the cloud and cannot launch a local stdio process from the user's machine. BotPay therefore creates a Skill ZIP with `SKILL.md` at its root, ready for **Skills > + Add > Upload a skill**:\n\n```bash\nnpx -y botpay@latest agent install --target manus --output ./botpay-manus-skill.zip\n```\n\nThe imported Manus Skill uses BotPay's stable JSON CLI fallback when shell execution is available. Typed BotPay tools in Manus require a separately deployed HTTPS MCP endpoint; this installer does not pretend that the local stdio MCP is reachable from Manus. Use `--no-mcp` to install only Skill files, or `--no-probe` to skip local MCP health checks.\n\nMCP starts read-only: `botpay_execute_service` rejects all payments unless the user deliberately sets `BOTPAY_MCP_ALLOW_PAYMENTS=1` in that MCP server's environment. Even then, the tool also requires `confirmed: true` after explicit human approval of the exact plan. Discovery, listing, search, statistics, inspection, balances, and planning never pay.\n\n## BotPay Scan Account\n\nThe CLI is an authorized device for a BotPay Scan user. Email, Google, EVM, and Solana remain web login identities; none of them becomes the CLI account key.\n\n```bash\nbotpay login\nbotpay whoami\nbotpay workspace list\nbotpay workspace use <workspace-id>\nbotpay project list\nbotpay project use <project-id>\n```\n\n`botpay login` opens BotPay Scan and shows a short device code and QR code. After approval, the CLI receives a 15-minute access token and a rotating 30-day refresh token. Account login does not grant `invoke:write` and does not create or fund a payment wallet.\n\nThe previous wallet-first entry remains available as a web login shortcut:\n\n```bash\nbotpay login --wallet\n```\n\nIt opens the same device authorization page with the wallet sign-in pane selected. The approved CLI still belongs to the resulting stable BotPay user.\n\nManage local account profiles and remotely revocable devices:\n\n```bash\nbotpay profile list\nbotpay profile use personal\nbotpay profile use company\nbotpay device list\nbotpay device revoke <device-id>\nbotpay logout\nbotpay logout --all\n```\n\nWallet roles are separate from login identities:\n\n```bash\nbotpay wallet list\nbotpay wallet link --purpose payment\nbotpay wallet use <wallet-id> --purpose payout\n```\n\nFor CI/CD, create a project-scoped service token and provide it through the environment. The default service-token scopes are catalog read and API publish; they do not include payment invocation.\n\n```bash\nbotpay token create --name ci-publisher --scope catalog:read,api:publish\n```\n\n## Bazaar Access and Discovery\n\nThe default Bazaar source is Coinbase's official x402 discovery endpoint. Before the first Bazaar read on a local installation, explicitly plan and purchase access:\n\n```bash\nbotpay plan pay\nbotpay execute pay --yes\nbotpay bazaar list --page 1 --page-size 20 --network eip155:8453 --max-usdc 0.10\nbotpay bazaar list --limit 50\nbotpay bazaar stats\nbotpay bazaar search \"video generation\" --pages 20 --max-usdc 3\nbotpay bazaar origin https://mvp.botpay.network\nbotpay discover https://video.botpay.network\nbotpay check https://video.botpay.network/api/x402/video/watch --method POST\n```\n\n`bazaar list` always displays one bounded page and never prints the complete catalog; the maximum display limit is 100. `bazaar stats` walks the complete catalog only to aggregate statistics, stopping when Bazaar reports that pagination has ended (or returns an empty page). In an interactive terminal it writes one updating progress line to stderr, while final text or JSON remains on stdout; `--quiet` and `--json` disable progress. It never emits individual resources or estimates totals from a configured page count. `bazaar search` performs local keyword ranking over Bazaar pages. Increase `--pages` for broader search coverage. `bazaar origin` scans those same pages for one exact seller origin. These commands verify the local `/pay` receipt but never initiate another payment themselves.\n\n## Direct API Calls\n\nBuild a no-payment plan:\n\n```bash\nbotpay call https://provider.example/api --method POST \\\n  --body '{\"query\":\"example\"}' --max-usdc 0.05\n```\n\nExecute only after review:\n\n```bash\nbotpay call https://provider.example/api --method POST \\\n  --body @request.json --max-usdc 0.05 --yes\n```\n\nUse `--body -` to read JSON from stdin and repeat `--header 'Name: value'` for headers. `check --probe` sends an unpaid runtime request and may invoke an unprotected route, so use it deliberately for non-GET methods.\n\n## BotPay Services\n\n```bash\nbotpay services\nbotpay plan pay\nbotpay execute pay --yes\nbotpay plan go\nbotpay go status\nbotpay plan safe\nbotpay plan nft --to 0xRecipient\nbotpay plan token --amount 0.5\nbotpay execute nft --to 0xRecipient --yes\nbotpay plan video\nbotpay execute video --yes\n```\n\nThe production catalog includes the five canonical `api.botpay.network` resources: `GET /pay`, `GET /go`, `POST /safe`, `POST /nft`, and `POST /token`. The token resource requires `--amount` from `0.1` through `10` USDC. These are non-interactive production commands; the unpublished local nine-menu demo is not part of this package.\n\n`GET /go` is a distinct paid capability. A successful `0.10 USDC` x402 call stores a local `/go` access receipt and returns the endpoint's six-digit `verificationCode` once; only its SHA-256 hash is stored. The access receipt allows `botpay go mcp` to launch the pinned `botpay-go-mcp@0.2.0` connector for Binance, OKX, Coinbase, Hyperliquid spot, and Polymarket. The access payment is not a trade approval and does not move funds into any exchange.\n\nThe exchange connector intentionally exposes no withdrawals, transfers, margin, futures, or leverage. It defaults to `TRADING_MODE=read_only`; `paper` and `live` execution require explicit configuration. Agents may inspect markets and prepare proposals, while a human-controlled operator credential must separately approve each proposal or batch before execution. Cross-venue batches are non-atomic and can partially execute.\n\nBazaar commands require a successful one-time local access purchase through `/pay`:\n\n```bash\nbotpay plan pay\nbotpay execute pay --yes\nbotpay bazaar search \"market data\"\n```\n\nThe access receipt is stored locally under `~/.botpay/receipts.ndjson`. Bazaar commands never initiate a payment themselves; without a valid `/pay` receipt they return `BAZAAR_ACCESS_REQUIRED` and show the explicit unlock command.\n\nService origins are configurable. The CLI reads free origin discovery first and uses its built-in manifest only when the origin does not publish compatible discovery.\n\n## Escrow Voucher\n\n```bash\nbotpay voucher create --yes\nbotpay voucher redeem --voucher 'BOTPAY-VOUCHER:...' --yes\n```\n\nVoucher creation pays 1 USDC to the voucher treasury. Redemption pays the advertised 0.01 USDC fee. The full voucher secret is returned once and is not written to receipts; only its SHA-256 hash is stored.\n\n## Full Refund\n\n```bash\nbotpay refund \\\n  --to 0xOriginalPayer \\\n  --original-payer 0xOriginalPayer \\\n  --yes\n```\n\nRefund ignores BotPay Credits and sends the complete Base USDC balance from the local Agent wallet through an x402 payment signed by that local Agent wallet. The recipient must equal the original payer. The Agent Voucher Treasury (`0x008D030704CFAfaeE1dA041Fdec6de071Bd546d9`) and its private key are never used by this refund path. Native ETH is not refunded.\n\n## Credits\n\n```bash\nbotpay credits balance\nbotpay credits topup --amount 10 --open\n```\n\nHuman-readable balance output is intentionally one line: `BotPay Credits: N`.\n\n## Configuration\n\nState is stored under `~/.botpay` by default:\n\n- `agent-wallets.json`: private keys, mode `0600`\n- `config.json`: non-secret overrides, mode `0600`\n- `profiles.json`: account profile, Scan origin, Workspace, and Project selection, mode `0600`\n- Account credentials: macOS Keychain when available; otherwise AES-256-GCM encrypted `credentials.json` with a restricted local key file\n- `discovery-cache.json`: free origin discovery cache\n- `receipts.ndjson`: `/pay` and `/go` access receipts plus voucher hashes, never voucher secrets or exchange credentials\n\nUseful environment variables:\n\n| Variable | Purpose |\n| --- | --- |\n| `BOTPAY_HOME` | Override the state directory |\n| `BOTPAY_TOKEN` | Use a BotPay project/service token for CI/CD |\n| `BOTPAY_CREDENTIALS_KEY` | Supply the 32-byte hex key for encrypted credential fallback storage |\n| `BOTPAY_AGENT_PRIVATE_KEY` | Use an external EVM key without writing it to disk |\n| `BOTPAY_BAZAAR_URLS` | Comma-separated free Bazaar endpoints |\n| `BOTPAY_API_ORIGIN` | Override the canonical BotPay API origin |\n| `BOTPAY_VOUCHER_API_BASE` | Override the escrow voucher origin |\n| `BOTPAY_NFT_ORIGIN` | Override the NFT origin |\n| `BOTPAY_VIDEO_ORIGIN` | Override the video origin |\n| `BOTPAY_MCP_ALLOW_PAYMENTS` | Set to `1` only in an explicitly approved MCP server to unlock guarded service execution |\n| `BASE_RPC_URL` | Override the Base RPC URL |\n\nNon-secret values can also be managed with `botpay config show` and `botpay config set`.\n\n## Automation\n\n```bash\nbotpay --json bazaar search \"market data\" --pages 10\nbotpay --json wallet balance\nbotpay --json plan voucher-create\n```\n\nSuccessful commands emit `{ \"ok\": true, \"data\": ..., \"meta\": ... }`. Failures emit `{ \"ok\": false, \"error\": { \"code\", \"message\", \"details\" }, \"meta\": ... }` to stderr and set a non-zero exit code.\n\n## Diagnostics\n\n```bash\nbotpay doctor\n```\n","readmeFilename":"README.md"}