CardCLI

Agent-first virtual card CLI funded by Solana devnet, issued through Stripe test mode.

Deposit SOL or USDC on Solana and instantly get a virtual Visa card — from a single CLI command. Designed for AI agents and developer automation with structured JSON output, idempotent commands, and machine-readable errors.

Install

npm install -g card-cli

Install the agent skill (optional)

./scripts/install-cardcli-skill.sh

This installs cardcli-agent into $CODEX_HOME/skills (default: ~/.codex/skills).

Or let an agent do the full setup

Install and use the cardcli-agent skill for this repo. Then set up CardCLI on devnet,
configure my Stripe test key and my Solana base58 private key, enable on-chain fee
collection, create a deposit address, wait for funding, buy a virtual card, and give
me the explorer links plus the card details.

Quick setup

# authenticate with Stripe test mode
card-cli auth login --api-key YOUR_STRIPE_SK_TEST_KEY

# configure your Solana devnet wallet
card-cli config set solana_private_key_base58 YOUR_BASE58_SECRET_KEY

# enable the deployed devnet fee vault
card-cli config set fee_program_id EpB6hUZUf1vvvTVAYvEN57pjUWfYswaAuKGGQDHP5iH
card-cli config set onchain_fee_collection_enabled true
card-cli config set fee_fixed_cents 10
card-cli config set fee_variable_bps 20

Usage

card-cli deposit address --asset sol
card-cli deposit status dep_xxx --wait --timeout 300
card-cli card buy --amount 5.00
card-cli card show crd_xxx

Features

• Creates Solana devnet deposit addresses for SOL and USDC (4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU)
• Tracks deposits locally
• Converts SOL to USD using live Coinbase spot price
• Creates virtual cards through Stripe Issuing test mode
• Reveals card details (PAN/CVC) with JSON-first output
• On-chain SOL fee collection via an Anchor fee-vault program

Commands

Command	Description
auth login	Authenticate with Stripe test key
auth status	Show current auth state
deposit address	Create a deposit address
deposit status <id>	Check deposit status
deposit list	List all deposits
card buy --amount <USD>	Buy a virtual card
card show <id>	Reveal card details
card list	List all cards
card freeze <id> --confirm	Freeze a card
balance	Show current balance
config set <key> <value>	Set a config value

Global flags

Flag	Description
--format json|table|plain	Output format
--network devnet|mainnet	Target network
--api-key <key>	Stripe API key
--quiet	Suppress non-essential output
--idempotency-key <key>	Idempotency key for safe retries

Config keys

card-cli config set network devnet
card-cli config set stripe_base_url https://api.stripe.com
card-cli config set coinbase_base_url https://api.coinbase.com
card-cli config set solana_private_key_base58 YOUR_BASE58_SECRET_KEY
card-cli config set fee_program_id EpB6hUZUf1vvvTVAYvEN57pjUWfYswaAuKGGQDHP5iH
card-cli config set onchain_fee_collection_enabled true
card-cli config set fee_fixed_cents 10
card-cli config set fee_variable_bps 20
card-cli config set sol_price_usd 100.00

SOL pricing uses live Coinbase spot price and falls back to sol_price_usd if the lookup fails.

Output format

All commands return structured JSON:

{
  "ok": true,
  "data": {},
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-04-04T12:00:00Z"
  }
}

On-chain fee vault (Anchor)

The repo includes an Anchor fee-vault program deployed on devnet:

• Program ID: EpB6hUZUf1vvvTVAYvEN57pjUWfYswaAuKGGQDHP5iH
• Explorer: View on Solana Explorer

Fee model:

• Fixed fee: $0.10
• Variable fee: 0.2% (20 bps)
• Collected in SOL during card buy

When enabled, the CLI auto-initializes the fee vault PDA and requires a configured/funded SOL wallet.

Project structure

card-cli/
├── src/                  # Rust CLI source
│   ├── main.rs           # Entry point
│   ├── cli.rs            # Command definitions (clap)
│   ├── app.rs            # Command handlers
│   ├── models.rs         # Data types
│   ├── providers.rs      # Stripe & Coinbase API clients
│   ├── store.rs          # Local state persistence
│   ├── fee_program.rs    # Anchor fee vault integration
│   ├── output.rs         # JSON/table/plain formatting
│   ├── error.rs          # Error types
│   └── lib.rs            # Library exports
├── programs/
│   └── cardcli-fee-vault/  # Anchor program (on-chain fee collection)
├── tests/                # Integration tests
├── scripts/              # Install & setup scripts
├── docs/                 # Documentation & UAT evidence
├── index.js              # npm wrapper for the Rust binary
├── Anchor.toml           # Anchor config
├── Cargo.toml            # Rust workspace config
└── package.json          # npm package config

Requirements

• Node.js 18+
• Rust toolchain (cargo)
• Stripe test secret key with Issuing access

Limits

• Minimum deposit / card value: $5.00
• Maximum card value: $500.00
• Devnet only (mainnet after validation)

Development

npm install              # builds the Rust binary via postinstall
cargo fmt --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
anchor build

Releases

See GitHub Releases for changelogs and prebuilt binaries.

License

MIT — Batuhan Bayazit