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

# 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

For the hackathon demo build, Stripe test mode is bundled by default on devnet. You only need to configure your Solana key.

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 | Optionally override the bundled demo Stripe 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
# optional: override bundled hackathon demo key
card-cli auth login --api-key YOUR_OWN_STRIPE_SK_TEST_KEY
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