@agenttech/tpay-cli 0.0.1 → 0.0.3

package/README.md

@@ -1,87 +1,170 @@
-# @agentpay/tpay-cli
+# @agenttech/tpay-cli
 
-A CLI for AI agents to send USDC/USDT via the T402 x402 v2 payment protocol.
-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> --chain <chain>` | Send payment |
-| `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 0x... --amount 10 --chain base
-{"status":"success","intent_id":"...","tx_hash":"...","explorer_url":"..."}
+tpay send --to <solana-address> --amount <number>
+```
 
-# Text output (human-readable)
-tpay send --to 0x... --amount 10 --chain base --format text
-status: success
-intent_id: abc123
-tx_hash: 0x...
-explorer_url: https://...
+Or pipe JSON via stdin:
+
+```bash
+echo '{"to":"<solana-address>","amount":"10"}' | tpay send
 ```
 
-Stdin JSON mode: pipe `{"to":"...","amount":"...","chain":"..."}` to `tpay send`.
+**Success output:**
 
-## Supported Chains
+```json
+{"status":"success","intent_id":"intent_abc123","tx_hash":"5xY...","explorer_url":"https://..."}
+```
 
-| `--chain` value | Network |
-|---|---|
-| `base` | Base Mainnet (EVM) |
-| `bsc` | BSC Mainnet (EVM) |
-| `base-sepolia` | Base Sepolia (EVM testnet) |
-| `solana` | Solana Mainnet |
-| `solana-devnet` | Solana Devnet |
+**Error output:**
+
+```json
+{"status":"error","error_type":"payment_error","message":"Payment failed","intent_id":"intent_abc123"}
+```
 
-## Runtime Environment Variables
+### `tpay balance`
 
-| Variable | Required | Description |
-|---|---|---|
-| `WALLET_PROVIDER` | No (default: `env`) | Wallet plugin name |
-| `WALLET_SEED_PHRASE` | Yes (for Solana) | BIP-39 mnemonic seed phrase |
-| `WALLET_EVM_PRIVATE_KEY` | For EVM chains | Hex private key (`0x...`) |
+Check SOL and USDT balances for any address. No wallet keys required.
+
+```bash
+tpay balance --address <solana-address>
+```
+
+**Output:**
+
+```json
+{"status":"ok","address":"<solana-address>","sol":"1.5","usdt":"100.0"}
+```
+
+### `tpay intent status`
 
-## Build
+Check the status of a payment intent.
 
 ```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 intent status <intent_id>
 ```
 
-## Development
+Or via stdin:
 
 ```bash
-bun install
-bun test
-T402_API_URL=https://... WALLET_EVM_PRIVATE_KEY=0x... bun run src/index.ts send --to 0x... --amount 1 --chain base
+echo '{"intent_id":"intent_abc123"}' | tpay intent status
 ```
 
-## Adding a New Chain Plugin
+**Output:**
 
-- [ ] 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
+```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://..."}
+```
+
+### `tpay version`
+
+```bash
+tpay version
+```
+
+### `tpay help`
+
+```bash
+tpay help
+```
+
+## 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` |
 
-## Adding a New Wallet Plugin
+## License
 
-- [ ] Create `src/plugins/wallets/<name>.ts`
-- [ ] Implement `WalletPlugin` interface (`name`, `getEvmPrivateKey()`, `getSolanaSeed()`)
-- [ ] Add to `WALLET_PLUGINS` map in `src/loader.ts`
-- [ ] Document required env vars above
-- [ ] Ensure key/seed return values are never logged
-- [ ] Test: verify loads when `WALLET_PROVIDER=<name>` is set
+ISC

package/dist/index.js

@@ -64009,6 +64009,7 @@ async function runHelp(ctx) {
     commands: {
       setup: 'Configure wallet keys with encryption. Use --from-env <file> to import. Non-interactive: WALLET_SEED_PHRASE="..." TPAY_PASSPHRASE="..." tpay setup',
       send: "Send USDC/USDT via T402. Args: --to, --amount",
+      balance: "Show wallet SOL and USDT balances",
       "intent status <intent_id>": "Fetch current status of a payment intent",
       version: "Print CLI version",
       help: "Show this help"
@@ -64036,7 +64037,7 @@ async function runHelp(ctx) {
 async function runVersion(ctx) {
   output(ctx.format, {
     name: "@agenttech/tpay-cli",
-    version: "0.0.1"
+    version: "0.0.3"
   });
   return 0;
 }
@@ -64236,7 +64237,6 @@ var CONFIG = {
     feePayer: ""
   }
 };
-console.log("CONFIG", CONFIG);
 
 class SendCommand extends BaseCommand {
   async execute(opts) {
@@ -64344,12 +64344,85 @@ async function runIntentStatus(ctx, intentId) {
   return command.execute(intentId);
 }
 
+// src/cli/commands/balance.ts
+init_index_cjs();
+var CONFIG3 = {
+  apiUrl: "https://api-staging-t402-pay.agent.tech",
+  solana: {
+    rpcUrl: "https://api.mainnet-beta.solana.com",
+    feePayer: ""
+  }
+};
+var USDT_MINT = new $PublicKey("Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB");
+var TOKEN_PROGRAM_ID2 = new $PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+var LAMPORTS_PER_SOL = 1000000000n;
+var USDT_DECIMALS = 6;
+
+class BalanceCommand extends BaseCommand {
+  async execute(opts) {
+    const address3 = this.requireArg(opts.address, "address");
+    let pubkey;
+    try {
+      pubkey = new $PublicKey(address3);
+    } catch {
+      throw new ValidationError(`Invalid Solana address: ${address3}`);
+    }
+    const connection = new $Connection(CONFIG3.solana.rpcUrl);
+    try {
+      this.ctx.logger.debug("Fetching balances", { address: address3 });
+      const [solLamports, tokenAccounts] = await Promise.all([
+        connection.getBalance(pubkey),
+        connection.getParsedTokenAccountsByOwner(pubkey, { mint: USDT_MINT, programId: TOKEN_PROGRAM_ID2 })
+      ]);
+      let usdtRaw = 0n;
+      for (const { account } of tokenAccounts.value) {
+        const amount = account.data.parsed?.info?.tokenAmount?.amount;
+        if (amount)
+          usdtRaw += BigInt(amount);
+      }
+      output(this.ctx.format, {
+        status: "ok",
+        address: address3,
+        sol: formatLamports(BigInt(solLamports)),
+        usdt: formatToken(usdtRaw, USDT_DECIMALS)
+      });
+      return 0;
+    } catch (error) {
+      if (error instanceof ValidationError)
+        throw error;
+      if (error instanceof Error && error.message.includes("Server error")) {
+        throw new NetworkError(error.message, error);
+      }
+      throw error;
+    }
+  }
+}
+function formatLamports(lamports) {
+  const whole = lamports / LAMPORTS_PER_SOL;
+  const frac = lamports % LAMPORTS_PER_SOL;
+  if (frac === 0n)
+    return whole.toString();
+  return `${whole}.${frac.toString().padStart(9, "0").replace(/0+$/, "")}`;
+}
+function formatToken(raw, decimals) {
+  const divisor = 10n ** BigInt(decimals);
+  const whole = raw / divisor;
+  const frac = raw % divisor;
+  if (frac === 0n)
+    return whole.toString();
+  return `${whole}.${frac.toString().padStart(decimals, "0").replace(/0+$/, "")}`;
+}
+async function runBalance(ctx, opts) {
+  const command = new BalanceCommand(ctx);
+  return command.execute(opts);
+}
+
 // src/cli/program.ts
 function createProgram() {
   const program2 = new Command;
   const versionInfo = {
     name: "@agenttech/tpay-cli",
-    version: "0.0.1"
+    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");
@@ -64389,6 +64462,9 @@ function registerCommands(program2) {
     await loadEnv();
     process.exitCode = await runSend(getContext(), opts);
   });
+  program2.command("balance").description("Show wallet SOL and USDT balances").option("--address <addr>", "Solana wallet address to query").action(async (opts) => {
+    process.exitCode = await runBalance(getContext(), opts);
+  });
   const intentCmd = program2.command("intent").description("Payment intent operations");
   intentCmd.command("status [intentId]").description("Check payment intent status").action(async (intentId) => {
     process.exitCode = await runIntentStatus(getContext(), intentId);

package/package.json

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