Flowpayra CLI

A command-line tool for HD wallet and RSA key management operations.

Features

• HD Wallet Generation: Generate BIP39 24-word mnemonics with optional passphrase protection
• HD Key Derivation: Derive private keys and addresses from mnemonics for single or batch operations
• Multi-chain Support: Support for Bitcoin, Ethereum/EVM, and TRON blockchains
• RSA Operations: Generate RSA key pairs and sign data using PKCS#8 PEM format
• Security First: Secure passphrase input with no console echo and signal handling
• Batch Processing: Efficient batch derivation with CSV export functionality

Installation

npm install -g flowpayra

Configuration

API Server Configuration

The CLI needs to connect to a FlowPayra operation API server for authentication and collection task operations. You can configure the API server URL in three ways (listed by priority, highest to lowest):

Method 1: Command-line Parameter (Highest Priority)

Pass the API URL directly when executing authentication commands:

flowpayra auth login --api-url https://api.flowpayra.com/api/v1

Method 2: Environment Variable

Set the FLOWPAYRA_API_URL environment variable:

export FLOWPAYRA_API_URL=https://api.flowpayra.com/api/v1
flowpayra auth login

You can add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent:

echo 'export FLOWPAYRA_API_URL=https://api.flowpayra.com/api/v1' >> ~/.bashrc
source ~/.bashrc

Method 3: Default Value (Lowest Priority)

If no API URL is specified, the CLI uses the default value: http://localhost:8081/api/v1

Authentication

Before using collection commands, you must authenticate with the API server:

# Login (opens browser for OAuth-style authentication; override API if needed)
flowpayra auth login --api-url https://api.flowpayra.com/api/v1

# Check authentication status
flowpayra auth status

# Logout and clear local credentials
flowpayra auth logout

auth login options:

• --api-url <url>: Override API base URL for this login
• --no-browser: Do not open the browser automatically; copy the verification URL manually
• --operator <operator>: Optional operator identifier to tag the session

How Authentication Works:

1. The CLI creates an authentication session with the API server
2. Your browser opens to a verification URL where you can approve the session
3. The CLI polls the API server until you confirm the session in the browser
4. Upon confirmation, the CLI receives an access token and refresh token
5. Credentials are encrypted and stored locally in ~/.flowpayra/credentials.enc
6. All subsequent commands automatically use the stored credentials

Security Features:

• Credentials are encrypted using AES-256-GCM
• Encryption key is derived from machine ID and username
• Secure file permissions (0600) are set automatically
• Access tokens are automatically included in API requests
• Token expiration is monitored and displayed in status commands

Configuration Files

The CLI stores configuration and credentials in the following locations:

• Config Directory: ~/.flowpayra/
• Credentials File: ~/.flowpayra/credentials.enc (encrypted)
• File Permissions:
  • Directory: 0700 (read/write/execute for owner only)
  • Credentials: 0600 (read/write for owner only)

HTTP Client Configuration

The following settings are used for API communication:

• Request Timeout: 10 seconds (10,000ms)
• Authentication Poll Interval: 2 seconds
• Max Poll Attempts: 150 (5 minutes total timeout)
• Retry Mechanism: Exponential backoff with jitter for failed requests

Example: Quick Start with Custom API Server

# Step 1: Configure the API server URL
export FLOWPAYRA_API_URL=https://api.example.com/api/v1

# Step 2: Authenticate
flowpayra auth login

# Step 3: Check authentication status
flowpayra auth status

# Step 4: Use collection commands (credentials are used automatically)
flowpayra bitcoin collect --task-id 123 --to bc1q...
flowpayra eip7702 delegate --task-id 456 --dry-run
flowpayra eip7702 collect --task-id 456 --to 0x...

Note: All commands that communicate with the API server (collection tasks, delegation, etc.) will use the configured API URL and stored credentials automatically. You only need to login once until the credentials expire.

Commands

1. HD Wallet Generation

Generate a 24-word mnemonic and xpub files for all supported blockchains:

flowpayra hd generate --with-passphrase <true|false>

Options:

• --with-passphrase [value]: Enable passphrase protection (default: true)

Features:

• Generates 24-word BIP39 mnemonic
• Optional passphrase protection (hidden input)
• Creates xpub files for: solana.xpub, tron.xpub, tron-testnet.xpub, btc.xpub, btc-testnet.xpub, evm.xpub, evm-testnet.xpub
• Secure signal handling (Ctrl+C, SIGTERM, etc.)

⚠️ Security Warning: Passphrases are never displayed or stored. If lost, wallet recovery is impossible.

2. HD Single Key Derivation

Derive private key and addresses for a single account index:

flowpayra hd derived-single -i <account-index> [options]

Options:

• -i, --account-index <index>: Account index (0-2147483647) [required]
• --mnemonic <mnemonic>: BIP39 mnemonic phrase (24 words). If not provided, will prompt securely
• --passphrase <passphrase>: Optional passphrase for additional security. If not provided, will prompt
• -c, --chain <chain>: Specific chain to derive (btc|evm|tron|eth). If not specified, derives all supported chains
• --testnet: Include testnet addresses (applies to BTC, EVM, and TRON)

Example:

# Derive for all chains
flowpayra hd derived-single -i 0

# Derive for specific chain
flowpayra hd derived-single -i 5 --chain evm

# Include testnet
flowpayra hd derived-single -i 0 --testnet

Sample Output:

==================================================
Private Key: 0x1053fae1b3ac64f178bcc21026fd06a3f4544ec2f35338b001f02d1d8efa3d5f
==================================================
HD Path: m/44'/60'/0'/0/0

BTC:            bc1qca600p6lwp84dzvrwxmyyjmwda3j34l6dk2t4z
BTC (Testnet):  tb1q673e9jt0797e5ad534ztg3q6tkxwwjeanvv227
EVM:            0xF278cF59F82eDcf871d630F28EcC8056f25C1cdb
TRON:           T3bdf67eaf22794bccfb73dc64fb35ff0af32ed2c

Security Features:

• Interactive mnemonic input with hidden display and format validation
• Optional passphrase prompt with secure input
• No storage of private keys or sensitive data

3. HD Batch Key Derivation

Derive private keys and addresses for multiple account indices:

flowpayra hd derived-batch --account-index-begin <start> --account-index-end <end> -c <chain> [options]

Options:

• --account-index-begin <begin>: Starting account index [required]
• --account-index-end <end>: Ending account index [required]
• -c, --chain <chain>: Chain to derive (btc|evm|tron|eth) [required for batch]
• --mnemonic <mnemonic>: BIP39 mnemonic phrase. If not provided, will prompt securely
• --passphrase <passphrase>: Optional passphrase. If not provided, will prompt
• -o, --out <filepath>: Output CSV file path. If not specified, outputs to console
• --testnet: Use testnet network (applies to BTC, EVM, and TRON)

Examples:

# Batch derive to console
flowpayra hd derived-batch --account-index-begin 0 --account-index-end 10 -c evm

# Batch derive to file
flowpayra hd derived-batch --account-index-begin 0 --account-index-end 100 -c btc -o ./btc_keys.csv

# BTC testnet batch
flowpayra hd derived-batch --account-index-begin 0 --account-index-end 5 -c btc --testnet

CSV Output Format:

PrivateKey,Address
0x1053fae1b3ac64f178bcc21026fd06a3f4544ec2f35338b001f02d1d8efa3d5f,0xF278cF59F82eDcf871d630F28EcC8056f25C1cdb
0x0855b75d03a8830e390b5483d81694c9c7121d971e092145cf8b9c6fa3a5b373,0xf785bD075874b8423D3583728a981399f31e95aA

Performance Features:

• Progress indicators for large batches
• Performance metrics (keys generated per second)
• Confirmation prompts for very large operations (>10,000 accounts)
• Memory-efficient processing

EVM Address Derivation from Xpub

Derive one or more EVM addresses directly from an account-level xpub:

flowpayra hd from-xpub [options]

Options:

• -x, --xpub <xpub>: Account-level xpub (m/44'/60'/0')
• -f, --xpub-file <path>: Path to file containing the xpub
• -i, --index <index>: Single account index (0-2147483647)
• --indices <list>: Comma-separated indices, for example 0,1,2,10,56
• -c, --change <change>: Change branch (0 external, 1 internal). Default: 0

Either --index or --indices must be provided. The command prints each requested index and its derived EVM address.

4. RSA Key Pair Generation

Generate RSA PKCS#8 PEM 4096-bit key pairs:

flowpayra rsa generate

Output:

• private.pem: PKCS#8 private key
• public.pem: X.509 public key

5. RSA Data Signing

Sign data using an RSA private key:

flowpayra rsa sign -d|--data <data> --private-key <keyfile>

Options:

• -d, --data <data>: Data to sign
• --private-key <path>: Path to private key file

Output: Base64-encoded RSA-PSS signature using SHA-384

6. EIP-7702 Delegation

Authorize deposit addresses to delegate execution to the configured smart contract:

flowpayra eip7702 delegate --task-id <id> [options]

Required:

• --task-id <id>: Collection task identifier from the operation API

Options:

• --dry-run: Inspect delegation requirements without submitting transactions
• -y, --yes: Skip confirmation prompts
• --batch-size <size>: Addresses per authorization batch (default: 20)
• --gas-price <gwei>: Legacy gas price override
• --max-fee-per-gas <gwei>: EIP-1559 max fee per gas override
• --max-priority-fee-per-gas <gwei>: EIP-1559 priority fee override
• --confirmations <count>: Confirmation depth to wait for (default: 1)

Workflow:

1. Fetches task configuration and exported addresses from the operation API
2. Prompts for mnemonic/passphrase, then verifies each derived address
3. Checks on-chain delegation status to identify pending authorizations
4. Sends EIP-7702 Type-4 transactions in batches via the stored or prompted relayer key
5. Waits for confirmations and prints a per-batch summary

ℹ️ The relayer private key is read silently from the CLI auth session when available. If not present, the CLI prompts for it securely.

7. EIP-7702 Collection

Sweep delegated accounts (native coin plus configured ERC-20 tokens) into a destination wallet:

flowpayra eip7702 collect --task-id <id> --to <address> [options]

Required:

• --task-id <id>: Collection task identifier
• --to <address>: Destination address for the aggregated funds

Options:

• --dry-run: Scan balances and print a report without broadcasting
• -y, --yes: Skip confirmation prompts
• --gas-price <gwei> / --max-fee-per-gas <gwei> / --max-priority-fee-per-gas <gwei>: Gas overrides
• --confirmations <count>: Confirmation depth to wait for each submission (default: 1)
• --relayer-key <key>: Override the relayer private key for this run

Dry Run Output:

• Lists every address with ETH or configured token balances
• Displays formatted token balances using metadata returned by the backend
• Exits without creating transactions

Execution Flow:

1. Derives and validates each address from the exported ZIP archive
2. Uses collect_all utilities to build multicall transfers per account
3. Relayer submits sponsored transactions through the delegate contract
4. Waits for the requested confirmations and prints success/skip/failure summaries

⚠️ Ensure the destination address is controlled and that the relayer wallet holds sufficient native gas before executing collection.

8. EVM Collection (Summary)

For EVM chains, use the EIP-7702 collection command (detailed in section 7):

flowpayra eip7702 collect --task-id <id> --to <address> [options]

This command handles:

• Native ETH collection from delegated accounts
• ERC-20 token collection (USDT, USDC, etc.)
• Multicall batch transfers through delegate contract
• Sponsored transactions via relayer

Key Features:

• No gas fees required in deposit addresses (relayer pays)
• Batch collection of ETH + multiple tokens in single transaction
• EIP-7702 delegation-based execution
• Supports EIP-1559 gas settings

See Section 7: EIP-7702 Collection above for complete documentation.

9. BTC Collection

Collect Bitcoin from multiple deposit addresses to a single destination address:

flowpayra bitcoin collect --task-id <id> --to <address> [options]

Required:

• --task-id <id>: Collection task identifier from the operation API
• --to <address>: Destination BTC address for collected funds

Options:

• --dry-run: Simulate execution without broadcasting transactions
• -y, --yes: Skip confirmation prompts
• --fee-rate <satVB>: Override fee rate in sat/vB (default: dynamic from mempool.space)
• --min-collect-amount <satoshis>: Minimum balance to collect in satoshis (default: dust threshold)

Workflow:

1. Fetches task configuration and addresses from the operation API
2. Prompts for mnemonic/passphrase and derives BTC private keys
3. Scans UTXO balances from blockchain API (blockstream.info)
4. Calculates optimal fees and maximum transferable amounts
5. Displays collection summary and requests confirmation
6. Broadcasts transactions and reports results to API

Examples:

# Dry run to preview collection
flowpayra bitcoin collect --task-id 123 --to bc1qReceiver... --dry-run

# Execute collection with custom fee rate
flowpayra bitcoin collect --task-id 123 --to bc1qReceiver... --fee-rate 10 -y

# Collect with minimum threshold
flowpayra bitcoin collect --task-id 123 --to bc1qReceiver... --min-collect-amount 100000

Features:

• Dynamic fee rate from mempool.space
• UTXO consolidation per address
• Dust threshold protection (546 satoshis)
• Progress tracking with real-time updates
• Partial failure handling
• API result synchronization

Quick Reference

Common HD Operations

# Generate new wallet
flowpayra hd generate

# Single account derivation (all chains)
flowpayra hd ds -i 0

# Single account derivation (specific chain)
flowpayra hd ds -i 5 -c evm

# Batch derivation to file
flowpayra hd db --account-index-begin 0 --account-index-end 100 -c btc -o keys.csv

# Interactive mode (will prompt for mnemonic and passphrase)
flowpayra hd ds -i 0
flowpayra hd db --account-index-begin 0 --account-index-end 10 -c evm

# Inspect delegation status without broadcasting
flowpayra eip7702 delegate --task-id 123 --dry-run

# Authorize addresses with custom gas settings
flowpayra eip7702 delegate --task-id 123 --batch-size 10 --max-fee-per-gas 30 --max-priority-fee-per-gas 2 -y

# Preview balances to collect later
flowpayra eip7702 collect --task-id 123 --to 0xReceiver --dry-run

# Execute collection using stored relayer credentials
flowpayra eip7702 collect --task-id 123 --to 0xReceiver -y --confirmations 2

EIP-7702 Delegation and Collection

# EIP-7702 delegation - dry run to check status
flowpayra eip7702 delegate --task-id 120 --dry-run

# EIP-7702 delegation - execute with custom batch size
flowpayra eip7702 delegate --task-id 120 --batch-size 10 -y

# EIP-7702 delegation - custom gas settings
flowpayra eip7702 delegate --task-id 120 --max-fee-per-gas 30 --max-priority-fee-per-gas 2

# EIP-7702 collection - dry run preview
flowpayra eip7702 collect --task-id 120 --to 0xReceiver... --dry-run

# EIP-7702 collection - execute with confirmations
flowpayra eip7702 collect --task-id 120 --to 0xReceiver... -y --confirmations 2

# EIP-7702 collection - custom gas settings
flowpayra eip7702 collect --task-id 120 --to 0xReceiver... --max-fee-per-gas 30 --max-priority-fee-per-gas 2

Traditional Collection Operations

# BTC collection - dry run preview
flowpayra bitcoin collect -t 123 --to bc1qReceiver... --dry-run

# BTC collection - execute with custom fee
flowpayra bitcoin collect -t 123 --to bc1qReceiver... --fee-rate 10 -y

# Traditional EVM collection (native coin or ERC-20)
flowpayra traditional collect -t 200 --to 0xReceiver... --dry-run

Supported Chains

| Chain | ID | Testnet Support | Address Format | Collection Support | |-------|----|-----------------|----------------|-------------------| | Bitcoin | btc | ✅ (--testnet) | bc1q... / tb1q... | ✅ bitcoin collect | | Ethereum/EVM | evm or eth | ✅ (HD: --testnet) | 0x... | ✅ eip7702 collect, traditional collect | | TRON | tron | ✅ (HD: --testnet) | T... | ❌ |

Development

Build from Source

Option 1: Using build script (Recommended)

cd flowpayra-cli
./build.sh

This will:

• Install dependencies
• Compile TypeScript to JavaScript
• Create executable in ../bin/flowpayra
• Run tests to verify the build

Option 2: Manual build

cd flowpayra-cli
npm install
npm run build

This compiles TypeScript to the dist/ directory but doesn't create the executable wrapper.

Running the CLI

After building:

# Run from project root
./bin/flowpayra --help

# Or add to PATH
export PATH="$PWD/../bin:$PATH"
flowpayra --help

# Or install globally
sudo ln -sf $PWD/../bin/flowpayra /usr/local/bin/flowpayra
flowpayra --help

Testing

npm test              # Run all tests
npm run test:watch    # Run tests in watch mode

Linting

npm run lint

Technical Details

Cryptographic Specifications

HD Wallet Operations:

• Mnemonic: BIP39 with 256 bits entropy (24 words)
• Derivation: BIP32/BIP44 compatible
• Account-level xpub generation: Creates extended public keys at account level
• Private key derivation: Full BIP44 path derivation from account level
• Chains Supported:
  • Bitcoin: m/44'/0'/0' (mainnet), m/44'/1'/0' (testnet)
  • EVM/Ethereum: m/44'/60'/0'
  • TRON: m/44'/195'/0'

Address Derivation Paths:

• Bitcoin: m/44'/0'/0'/0/index (P2WPKH, bc1q format)
• Bitcoin Testnet: m/44'/1'/0'/0/index (P2WPKH, tb1q format)
• EVM: m/44'/60'/0'/0/index (EIP-55 checksummed addresses)
• TRON: m/44'/195'/0'/0/index (T-format addresses)

Key Derivation Features:

• Non-hardened derivation from account-level xpub
• Compatible with standard HD wallet implementations
• Batch processing with configurable account ranges
• CSV export for integration with external systems

RSA Operations:

• Key Size: 4096 bits
• Private Key Format: PKCS#8 PEM
• Public Key Format: X.509 SubjectPublicKeyInfo PEM
• Signature Algorithm: RSA-PSS with SHA-384
• Padding: PSS with MGF1, salt length = hash length

Command Aliases

For convenience, the following short aliases are available:

• flowpayra hd ds → flowpayra hd derived-single
• flowpayra hd db → flowpayra hd derived-batch

Security Features

• Input Security: Secure passphrase and mnemonic input with hidden echo
• Signal Handling: Graceful cleanup on interruption (SIGINT, SIGTERM, SIGHUP)
• Console Safety: Automatic console restoration on exit
• Data Protection: No storage of sensitive data (mnemonics, passphrases, private keys)
• Validation: BIP39 mnemonic validation and account index bounds checking
• Cryptographic Security: Secure random number generation for all operations
• Memory Safety: Sensitive data cleared from memory after use
• Input Validation: Comprehensive validation of all user inputs

License

MIT License - see LICENSE file for details.