{"_id":"@bankofai/x402-tools","_rev":"3-a429fcb03ce43f99256916baca8cf734","name":"@bankofai/x402-tools","dist-tags":{"beta":"0.1.0-beta.3","latest":"0.1.0-beta.3"},"versions":{"0.1.0-beta.3":{"name":"@bankofai/x402-tools","version":"0.1.0-beta.3","keywords":["x402","cli","tron","evm","payment"],"license":"MIT","_id":"@bankofai/x402-tools@0.1.0-beta.3","maintainers":[{"name":"virtual_parson","email":"parson.hu@tron.network"},{"name":"roger.gan","email":"roger.gan@tron.network"},{"name":"gummy789j","email":"gummy789j@gmail.com"},{"name":"wzc1206","email":"david.wang@tron.network"},{"name":"bobo123123hhh","email":"bobo.liu@tron.network"}],"homepage":"https://github.com/BofAI/x402-tools#readme","bugs":{"url":"https://github.com/BofAI/x402-tools/issues"},"bin":{"x402-tools":"dist/index.js"},"dist":{"shasum":"52b0fc8991e8c18adf1dd56997187c4ff506a5be","tarball":"https://registry.npmjs.org/@bankofai/x402-tools/-/x402-tools-0.1.0-beta.3.tgz","fileCount":44,"integrity":"sha512-dCm6psvsz66M555klvI8A5w/a7/bgWfSTFIUXsBaN409KeDzY6RBYSD6BTrkfvQHQmEwW7GELgGQmxhrDN8Bqg==","signatures":[{"sig":"MEUCIFFShHJVFnGX6Jez8PzFTAo8OSHBgUl7rj4K0EseUZ4JAiEA5sLepXsOBys9eK5dnVnAyrUYSlb4X0rMPdqpt36ujWQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":149485},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"30bb7c719efdcf307ad7ff7a183372c2f5889867","scripts":{"test":"vitest run","build":"tsc","clean":"rm -rf dist","x402-tools":"node ./dist/index.js"},"_npmUser":{"name":"bobo123123hhh","email":"bobo.liu@tron.network"},"repository":{"url":"git+https://github.com/BofAI/x402-tools.git","type":"git"},"_npmVersion":"10.8.2","description":"x402-tools — one-shot BankofAI x402 CLI: serve a 402 payment endpoint, or pay one as a client.","directories":{},"_nodeVersion":"20.19.5","dependencies":{"viem":"^2.21.49","tronweb":"^6.0.0","commander":"^12.1.0","@bankofai/x402":"^0.5.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.1","typescript":"^5.3.0","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/x402-tools_0.1.0-beta.3_1777446658096_0.18032068821378266","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-04-29T07:10:57.996Z","modified":"2026-09-16T08:36:06.381Z","0.1.0-beta.3":"2026-04-29T07:10:58.333Z"},"bugs":{"url":"https://github.com/BofAI/x402-tools/issues"},"license":"MIT","homepage":"https://github.com/BofAI/x402-tools#readme","keywords":["x402","cli","tron","evm","payment"],"repository":{"url":"git+https://github.com/BofAI/x402-tools.git","type":"git"},"description":"x402-tools — one-shot BankofAI x402 CLI: serve a 402 payment endpoint, or pay one as a client.","maintainers":[{"email":"parson.hu@tron.network","name":"virtual_parson"},{"email":"roger.gan@tron.network","name":"roger.gan"},{"email":"gummy789j@gmail.com","name":"gummy789j"},{"email":"david.wang@tron.network","name":"wzc1206"},{"email":"bobo.liu@tron.network","name":"bobo123123hhh"},{"email":"zerodevblock@gmail.com","name":"zerodev0"},{"email":"leon.zhang@tron.network","name":"leonatmoon"}],"readme":"# `x402-tools`\n\nOne-shot BankofAI x402 CLI built on top of the [`@bankofai/x402`](https://www.npmjs.com/package/@bankofai/x402) SDK. Two commands:\n\n- **`server`** — start a local x402 payment server (advertises payment terms, accepts a signed payload, settles).\n- **`client <url>`** — pay an x402-protected URL when the server returns `402 Payment Required`.\n\nFull flag matrix and example output: [`FEATURES.md`](FEATURES.md).\n\n## Install\n\n```bash\nnpm install -g @bankofai/x402-tools\nx402-tools --help\n```\n\n## Quick start\n\n```bash\n# Start a server that charges 1.25 USDT on TRON Nile, paid to the address you own\nx402-tools server --pay-to TJWdoJk8KyrfxZ2iDUqz7fwpXaMkNqPehx \\\n  --decimal 1.25 --network tron:nile\n\n# In another shell — pay it\nx402-tools client http://127.0.0.1:4020/pay \\\n  --max-decimal 1.25 --network tron:nile --token USDT\n```\n\n## Amount conventions\n\nBoth `server` and `client` accept either form, never both:\n\n| Flag | Meaning | Example |\n|---|---|---|\n| `--decimal <decimal>` | human-readable; resolved against the token's `decimals` | `1.25` |\n| `--amount <integer>` | smallest-unit BigInt-able string, fed straight into `PaymentRequirements.amount` | `1250000` for 1.25 USDT |\n\nJSON output always reports both as `decimal` and `amount`.\n\n## Wallet\n\nThe CLI never accepts a private key as a flag. Two sources, picked via `--wallet <source>`:\n\n- `agent-wallet` (default) — uses `@bankofai/agent-wallet`'s active wallet for the target network.\n- `env` — reads `TRON_PRIVATE_KEY` (for `tron:*` networks) or `EVM_PRIVATE_KEY` (for `eip155:*`).\n\nResolution order: agent-wallet → env-key fallback → `WALLET_NOT_AVAILABLE`. The fallback is logged to stderr so misconfigurations are visible.\n\n## Output\n\nEvery command emits the same wrapped JSON envelope under `--json` (or `X402_OUTPUT=json`):\n\n```json\n{ \"ok\": true,  \"command\": \"...\", \"result\": { ... } }\n{ \"ok\": false, \"command\": \"...\", \"error\": { \"code\": \"...\", \"message\": \"...\", \"hint\": \"...\" } }\n```\n\n15 standardized error codes are documented in [`src/error.ts`](src/error.ts). Result fields use `snake_case` (`pay_url`, `resource_url`, `pay_to`, `amount`).\n\n## Schemes\n\nThe CLI auto-picks per `(network, token)` in [`src/schemes.ts`](src/schemes.ts) when `--scheme` is omitted:\n\n| Network | Token | Auto scheme | User fee |\n|---|---|---|---|\n| BSC testnet (`eip155:97`) | DHLU | `exact` | 0 |\n| BSC testnet (`eip155:97`) | USDT/USDC | `exact_permit` | 0 |\n| TRON Nile (`tron:nile`) | USDT/USDD | `exact_gasfree` | ~0.1 USDT |\n| TRON mainnet | USDT/USDD | `exact_gasfree` | ~0.1 USDT |\n\nSettlement paths:\n\n- `exact` / `exact_permit` (TRON or EVM) → BankofAI root facilitator (`https://facilitator.bankofai.io`) `/fee/quote → /verify → /settle`.\n- `exact_gasfree` (TRON only) → in-process GasFree submit. Provider deducts a flat ~0.1 USDT relayer fee.\n\n## Environment variables\n\n| Var | Purpose |\n|---|---|\n| `TRON_PRIVATE_KEY` | TRON wallet key for `--wallet env` |\n| `EVM_PRIVATE_KEY` | EVM wallet key for `--wallet env` |\n| `TRON_GRID_API_KEY` | Optional, forwarded to SDK for TronGrid |\n| `X402_OUTPUT` | `human` (default) or `json` |\n| `X402_FACILITATOR_URL_OVERRIDE` | **e2e only**; emits a stderr warning when active |\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnode dist/index.js server --help\nnpm test\n```\n\n## Relation to `@bankofai/x402`\n\n`x402-tools` is a thin CLI surface over the BankofAI x402 SDK:\n\n- Protocol types (`PaymentRequired`, `PaymentPayload`, `PaymentRequirements`, `SettleResponse`) — re-used from the SDK.\n- Client mechanisms (`ExactPermitEvmClientMechanism`, `ExactPermitTronClientMechanism`, `ExactEvmClientMechanism`, `GasFreeAPIClient`) — registered against the SDK's `X402Client` / `X402FetchClient`.\n- Signers (`EvmClientSigner`, `TronClientSigner`) — plus a local `AgentWallet` shim for `--wallet env`.\n- Token registry, network helpers (`isTronNetwork`, `isEvmNetwork`, `getChainId`, `getGasFreeApiBaseUrl`, …) — all from the SDK.\n\nPinning a specific SDK version: bump `@bankofai/x402` in [`package.json`](package.json).\n","readmeFilename":"README.md"}