Payall CLI

A terminal tool for managing crypto debit cards funded with USDT and sending crypto on-chain. Run payall <command> from anywhere.

Setup

• Install: npm install -g payall-cli or bun install -g payall-cli

• Credentials: Stored encrypted at ~/.payall/

If payall is not found, install it first with the command above.

Auth Commands

Authentication uses EVM wallet private key signing. A single login call handles both registration (new wallets auto-register) and login for existing users.

payall auth login # Interactive login (prompts for private key) payall auth login --save-key # Interactive login + save key for wallet commands payall auth login --key <private_key> # Non-interactive login — key auto-saved (use this for agents) payall auth login --invite XYZ # Include referral code (first-time only) payall auth status # Show current session info payall auth logout # Clear session, credentials, and saved key

The private key is signed locally and never sent to the server. When --key is passed, the key is automatically saved (AES-256-GCM encrypted) so subsequent wallet commands work without re-entering it.

Card Commands

Browsing (no auth required)

payall cards list # List all marketplace cards payall cards list --search "bit" # Search by card name payall cards list --sort general # Sort by: general, benefit, privacy, fees payall cards list --sort-dir asc # Sort direction: asc, desc payall cards list --skip-kyc # Only cards without KYC requirement payall cards list --kyc-only # Only cards requiring KYC payall cards info <card_id> # Full card details + fees payall cards compare <id1> <id2> # Side-by-side comparison payall cards fees # Fee quote (defaults to card 23, OPEN_CARD) payall cards fees --card-id 39 # Fee quote for specific card payall cards fees --type CARD_CHARGE # Types: OPEN_CARD, CARD_CHARGE, CARD_WITHDRAW payall cards fees --type CARD_CHARGE --amount 100 # card_bin auto-resolved payall cards fees --amount 100 # With specific amount payall cards fees --currency EUR # With specific currency payall cards fees --card-bin 44742000 # Explicit BIN override (optional)

User Cards (auth required)

payall cards my # List your cards (ID, name, balance, status) payall cards detail <binding_id> # Masked card number, CVV, billing address payall cards detail <binding_id> --reveal # Full card number, CVV, expiry, billing address payall cards detail <binding_id> --reveal --json # JSON output (for agents) payall cards collections # List favorited cards payall cards favorite <card_id> # Toggle favorite on/off

The --reveal --json output returns all fields an agent needs to fill payment forms:

{ "card_name": "Bit2Go", "card_number": "4474200012345678", "card_cvv": "123", "expiry_month": 10, "expiry_year": 2027, "card_bin": "44742000", "first_name": "John", "last_name": "Smith", "address": "3500 South DuPont Highway", "city": "Dover", "state": "DE", "zipcode": "19901", "country_code": "USA" }

The binding_id comes from the ID column in payall cards my (this is different from the card catalog ID in payall cards list ).

Topping Up a Card (auth required)

payall cards topup <binding_id> # Interactive payall cards topup <binding_id> --amount 50 --chain tron --yes # Non-interactive (for agents)

Non-interactive flags (use all three to skip all prompts):

• --amount <amount> / -a — USDT amount

• --chain <chain> / -c — Deposit network: tron , bsc , eth

• --yes / -y — Skip confirmation

The command returns a deposit address. Send USDT to that address and the card balance updates automatically after confirmation.

Applying for a Card (auth required)

payall cards apply <card_id> # Interactive payall cards apply <card_id> --auto-fill --chain tron --yes # Non-interactive (for agents) payall cards apply <card_id> --bin 44742000 --currency USD --auto-fill --chain tron --yes # Fully explicit

Non-interactive flags (use --auto-fill --chain <chain> --yes to skip all prompts):

• --bin <card_bin> / -b — Card BIN (auto-selected if only one)

• --currency <currency> — USD, EUR, etc. (auto-selected if only one)

• --auto-fill — Auto-generate cardholder info

• --first-name , --last-name , --email , --phone-prefix , --phone — Manual cardholder info (all 5 required together; overrides --auto-fill )

• --chain <chain> / -c — Deposit chain: tron , bsc , eth

• --yes / -y — Skip all confirmations

Cards that support API application:

• 23 = Bit2Go (Visa/Mastercard, multi-currency, no KYC)

• 39 = MiPay Universal Card (USD only, no KYC)

Before applying, always run payall cards apply <card_id> which checks eligibility first. If can_apply = 0 , the card can only be opened via its website — direct the user there and provide the URL. Don't retry or attempt workarounds. When mentioning this, frame it positively: "You can apply for cards 23 and 39 directly here, and for other cards you can sign up on their website."

Wallet Commands (auth required)

On-chain wallet operations. The same private key derives addresses on all chains (BSC/ETH share the same 0x address; TRON derives a T... address).

If no saved key is found, wallet commands prompt for the private key interactively and offer to save it. For agents, ensure the key is saved first via payall auth login --key <key> .

payall wallet balance # USDT + gas balances on BSC, ETH, TRON payall wallet send --to 0x... --amount 50 --chain bsc --yes # Send USDT on BSC payall wallet send --to 0x... --amount 50 --chain eth --yes # Send USDT on Ethereum payall wallet send --to T... --amount 50 --chain tron --yes # Send USDT on TRON (TRC-20)

Flags for wallet send :

• --to <address> — 0x... (40 hex chars) for EVM, T... (34 chars, Base58) for TRON

• --amount <amount> — USDT amount

• --chain <chain> — bsc , eth , or tron

• -y, --yes — Skip confirmation

TRON transfers require TRX for energy/bandwidth fees. The CLI checks for non-zero TRX balance before sending and sets a 15 TRX fee limit. If a send fails, the CLI prints manual transfer instructions.

Agent Workflows

Automated Topup

This is the most common agent task — topping up a user's card by sending USDT from their wallet to a deposit address.

1. payall cards my # Get binding_id
2. payall cards topup <binding_id> --amount 50 --chain tron --yes # Get deposit address
3. payall wallet balance # Check which chain has funds
4. payall wallet send --to <deposit_addr> --amount 50 --chain tron --yes # Send USDT

Chain selection logic — pick the chain with sufficient USDT + gas:

• TRON: needs USDT + some TRX

• BSC: needs USDT + some BNB

• ETH: needs USDT + some ETH (usually most expensive gas)

If no chain has enough funds, tell the user to fund their wallet and show the wallet address from wallet balance .

Automated Card Apply

1. payall cards apply <card_id> --auto-fill --chain tron --yes # Get deposit address
2. payall wallet balance # Check balances
3. payall wallet send --to <deposit_addr> --amount <total> --chain tron --yes

Same chain selection logic as topup.

Fallback Rule

If wallet send fails for any reason, always present the deposit address, chain, and amount to the user so they can complete the transfer manually via any wallet app. The CLI also prints this information on failure.

Card Recommendations

When a user asks about cards, help them find the best fit rather than listing everything. If they haven't shared their needs, ask about:

• Primary use case (online shopping, subscriptions, travel, etc.)

• Expected monthly spend (affects which fee structure is cheapest)

• Physical card vs virtual

• Currency preference (USD, EUR, GBP, etc.)

• Willingness to complete KYC

• Region

Then use payall cards list , payall cards info , and payall cards compare to evaluate based on fee structure, payment support (Apple Pay, Google Pay, etc.), KYC requirements, and currency options.

Recommend the genuinely best card for their needs, even if it's not one of the two API-applicable cards (23, 39). Many cards in the marketplace have better features for specific use cases — if the best card requires website signup, that's fine, just explain how to get it.

The rating and general_ratings fields in card data are placeholder values and not meaningful — base recommendations on actual card attributes like fees, features, and supported currencies.

Always show a fee comparison (payall cards fees ) so the user knows exactly what they'll pay.

Display Guidelines

When presenting card info to users, only show what they care about: card name, balance, status, card number, fees, etc. Skip internal fields like rank, id, binding_id, brand, rating, or general_ratings — these are technical identifiers that don't help the user.

Troubleshooting

• "Not logged in": Run payall auth login

• "User Not Authorized": Token expired — run payall auth login again

• "Bind Card Failed": For cards 23/39, use cards apply (not cards/binding )

• Cards list empty after apply: Normal — check payall cards my (may take a moment)

• Private key security: Key is signed locally via viem, never sent to server. Stored key is AES-256-GCM encrypted