@agenttech/tpay-cli 0.0.2 → 0.0.3

package/README.md

@@ -1,82 +1,170 @@
 # @agenttech/tpay-cli
 
-A CLI for AI agents to send USDT via the T402 x402 v2 payment protocol on Solana.
-Output defaults to structured JSON. Use `--format text` for human-readable output. Logs go to stderr.
+Send USDT payments on Solana via the T402 x402 v2 protocol. Designed for AI agents — all output is structured JSON on stdout, logs go to stderr.
+
+## Install
+
+```bash
+npm install -g @agenttech/tpay-cli
+```
+
+Verify:
+
+```bash
+tpay version
+```
+
+## Setup
+
+The CLI needs a BIP-39 seed phrase to sign transactions. Two setup paths:
+
+### Non-interactive (recommended for agents)
+
+```bash
+WALLET_SEED_PHRASE="your twelve or twenty four word seed phrase here" \
+TPAY_PASSPHRASE="encryption-password" \
+tpay setup
+```
+
+This encrypts and saves the seed phrase to `~/.config/tpay/.env`.
+
+### From env file
+
+```bash
+tpay setup --from-env /path/to/.env
+```
+
+The file must contain `WALLET_SEED_PHRASE=...`.
+
+### Skip setup (inline seed phrase)
+
+You can skip `tpay setup` entirely by passing the seed phrase as an environment variable on every call:
+
+```bash
+WALLET_SEED_PHRASE="your seed phrase" tpay send --to <address> --amount 10
+```
+
+### Setup output
+
+```json
+{"status":"success","saved":true}
+```
 
 ## Commands
 
-| Command | Description |
-|---|---|
-| `tpay setup` | Configure wallet keys interactively |
-| `tpay setup --from-env <file>` | Import keys from an env file |
-| `tpay send --to <addr> --amount <n>` | Send payment |
-| `tpay balance --address <addr>` | Show wallet SOL and USDT balances |
-| `tpay intent status <intent_id>` | Check payment status |
-| `tpay version` | Print version |
-| `tpay help` / `tpay --help` | Show all commands |
-| `tpay send --help` | Show send args |
-
-Global flags:
-- `--verbose` — debug output to stderr
-- `--format text|json` — output format (default: `json`)
+### `tpay send`
+
+Send a USDT payment.
 
 ```bash
-# JSON output (default, for programmatic use)
-tpay send --to <solana-address> --amount 10
-{"status":"success","intent_id":"...","tx_hash":"...","explorer_url":"..."}
+tpay send --to <solana-address> --amount <number>
+```
+
+Or pipe JSON via stdin:
+
+```bash
+echo '{"to":"<solana-address>","amount":"10"}' | tpay send
+```
+
+**Success output:**
 
-# Text output (human-readable)
-tpay send --to <solana-address> --amount 10 --format text
-status: success
-intent_id: abc123
-tx_hash: ...
-explorer_url: https://...
+```json
+{"status":"success","intent_id":"intent_abc123","tx_hash":"5xY...","explorer_url":"https://..."}
 ```
 
+**Error output:**
+
+```json
+{"status":"error","error_type":"payment_error","message":"Payment failed","intent_id":"intent_abc123"}
+```
+
+### `tpay balance`
+
+Check SOL and USDT balances for any address. No wallet keys required.
+
 ```bash
-# Check wallet balance (read-only, no keys needed)
 tpay balance --address <solana-address>
-{"status":"ok","address":"<solana-address>","sol":"0.5","usdt":"100.0"}
 ```
 
-Stdin JSON mode: pipe `{"to":"...","amount":"..."}` to `tpay send`.
+**Output:**
 
-## Supported Chains
+```json
+{"status":"ok","address":"<solana-address>","sol":"1.5","usdt":"100.0"}
+```
 
-| Network |
-|---|
-| Solana Mainnet |
-| Solana Devnet |
+### `tpay intent status`
 
-## Runtime Environment Variables
+Check the status of a payment intent.
 
-| Variable | Required | Description |
-|---|---|---|
-| `WALLET_SEED_PHRASE` | Yes | BIP-39 mnemonic seed phrase |
-| `TPAY_PASSPHRASE` | No | Passphrase for decrypting config file (cleared from env after use) |
-| `SOLANA_FEE_PAYER` | No | Override fee payer address (build-time default used if unset) |
+```bash
+tpay intent status <intent_id>
+```
+
+Or via stdin:
+
+```bash
+echo '{"intent_id":"intent_abc123"}' | tpay intent status
+```
+
+**Output:**
+
+```json
+{"status":"ok","intent_id":"intent_abc123","payment_status":"BASE_SETTLED","sending_amount":"10","receiving_amount":"10","payer_chain":"solana","created_at":"...","expires_at":"...","tx_hash":"5xY...","explorer_url":"https://..."}
+```
 
-## Build
+### `tpay version`
 
 ```bash
-T402_API_URL=https://api.example.com \
-SOLANA_RPC_URL=https://your-rpc.example.com \
-SOLANA_FEE_PAYER=<base58> \
-bun build --compile src/index.ts --outfile tpay
+tpay version
 ```
 
-## Development
+### `tpay help`
 
 ```bash
-bun install
-bun test
-WALLET_SEED_PHRASE="..." bun run src/index.ts send --to <solana-address> --amount 1
+tpay help
 ```
 
-## Adding a New Chain Plugin
+## Global Flags
+
+| Flag | Description |
+|---|---|
+| `--verbose` | Debug logs to stderr |
+| `--format json\|text` | Output format (default: `json`) |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `WALLET_SEED_PHRASE` | Yes (if no config file) | BIP-39 mnemonic (12–24 words) |
+| `TPAY_PASSPHRASE` | No | Decrypts saved config at `~/.config/tpay/.env` |
+| `SOLANA_FEE_PAYER` | No | Override fee payer address |
+
+If both `WALLET_SEED_PHRASE` env var and an encrypted config file exist, the env var takes precedence.
+
+## Exit Codes
+
+| Code | Type | Meaning |
+|---|---|---|
+| 0 | — | Success |
+| 1 | `validation_error` | Invalid arguments or input |
+| 2 | `runtime_error` | Unexpected runtime failure |
+| 3 | `configuration_error` | Missing or invalid config |
+| 4 | `network_error` | API or RPC failure |
+| 5 | `payment_error` | Payment-specific failure |
+
+All errors output JSON to stdout:
+
+```json
+{"status":"error","error_type":"<type>","message":"<description>"}
+```
+
+## Supported Chains
+
+| Chain | Network ID |
+|---|---|
+| Solana Mainnet | `solana` |
+| Solana Devnet | `solana-devnet` |
+
+## License
 
-- [ ] Create `src/plugins/chains/<name>.ts`
-- [ ] Implement `ChainPlugin` interface (`name`, `chains[]`, `sign()`)
-- [ ] Add to `CHAIN_PLUGIN_LOADERS` in `src/loader.ts`
-- [ ] Add to Supported Chains table above
-- [ ] Test: verify x402 payload structure matches T402 backend
+ISC

package/dist/index.js

@@ -64037,7 +64037,7 @@ async function runHelp(ctx) {
 async function runVersion(ctx) {
   output(ctx.format, {
     name: "@agenttech/tpay-cli",
-    version: "0.0.2"
+    version: "0.0.3"
   });
   return 0;
 }
@@ -64422,7 +64422,7 @@ function createProgram() {
   const program2 = new Command;
   const versionInfo = {
     name: "@agenttech/tpay-cli",
-    version: "0.0.2"
+    version: "0.0.3"
   };
   const versionString = typeof versionInfo === "string" ? versionInfo : versionInfo.version;
   program2.name("tpay").version(versionString, "-v, --version", "Show version").option("--verbose", "Enable debug logging to stderr").option("--format <fmt>", "Output format: json | text", "json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenttech/tpay-cli",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "T402 CLI for agent automation",
   "type": "module",
   "main": "dist/index.js",