StableCard Developer Docs — USDC Virtual Cards for AI Agents

01

Installation

Install the StableCard CLI globally using the private install link sent to you via email after joining the waitlist.

🔒 Early Access Only — The repository is currently private. Request access on the homepage to receive your personal install link by email.

bash — install from your access link

npm install -g github:Polsia-Inc/stablecard

Verify the install:

bash

$ stablecard --help
Usage: stablecard [options] [command]
StableCard CLI — USDC-backed virtual cards via x402

ℹ Requires Node.js 18+. Install via nodejs.org or brew install node.

02

Configuration

StableCard uses EIP-3009 (USDC transferWithAuthorization) to pull funds from your wallet atomically. You need a funded USDC wallet — no account creation required.

Get a wallet

Any EVM wallet works: MetaMask, Coinbase Wallet, Rainbow. For agents, use Coinbase AgentKit to create a programmable wallet.

Fund with USDC on Base

Bridge USDC to Base network. Near-zero gas fees. bridge.base.org or buy directly in Coinbase.

Point the CLI at your wallet

Run stablecard config to set your wallet address. The CLI connects to your wallet for signing via WalletConnect or a local private key.

bash

$ stablecard config
# Interactive setup — sets endpoint, chain, wallet address
endpoint: https://stablecard.polsia.app
chain: base
wallet: 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

💡 The CLI config is stored at ~/.stablecard/config.json. Edit it directly for scripted environments.

03

Your First Card

Three commands: fund a card, check it, hand it to your agent. The whole loop takes under a minute.

bash

# Step 1: Fund a new card with 50 USDC on Base
$ stablecard fund --amount 50 --chain base
✓ Card funded.  id: sc_card_7x9k3m2p  tx: 0x8f2a...c41d

# Step 2: List your cards
$ stablecard list
sc_card_7x9k3m2p  $50.00 USDC  active  Base

# Step 3: Reveal credentials for your agent
$ stablecard reveal sc_card_7x9k3m2p
PAN  4242 8888 1234 5678
CVV  492
EXP  03/27
BAL  $50.00 USDC

🔒 Credentials are revealed once and cached locally. Never log PAN/CVV — pass them directly to your agent's secure context.

04

MCP Integration

Add StableCard to your Claude Desktop, Cursor, or any MCP client. Your agent gains native tools to create cards, check balances, and spend USDC.

Claude Desktop

~/.claude/claude_desktop_config.json

Cursor / VS Code

.cursor/mcp.json or .mcp/config.json

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stablecard": {
      "url": "https://stablecard.polsia.app/mcp"
    }
  }
}

.cursor/mcp.json

{
  "mcpServers": {
    "stablecard": {
      "url": "https://stablecard.polsia.app/mcp"
    }
  }
}

Once connected, your agent has access to these tools:

Tool	Description
fund_card	Create a new virtual card funded with USDC on any supported chain
get_card	Retrieve card details — balance, status, and full PAN/CVV for purchases
list_cards	List all cards with balances and statuses, optionally filtered
freeze_card	Temporarily disable spending on a card
close_card	Close a card and auto-refund remaining USDC to your wallet

ℹ The MCP server is hosted at https://stablecard.polsia.app/mcp. No auth token required for read operations. Funding requires a signed USDC authorization from your wallet.

05

x402 Protocol

StableCard natively supports the x402 open payment protocol — HTTP 402 responses that agents handle autonomously. When a server returns 402 Payment Required, your agent pays with USDC on-chain and retries the request automatically.

bash — pay_402

# Your agent hits a 402-protected endpoint
$ stablecard pay --card sc_card_7x9k3m2p --url https://api.example.com/premium
402 Payment Required  amount: 0.50 USDC
✓ Paid.  tx: 0x3a91...b4f2
✓ Request retried — 200 OK

In your agent code, use the MCP pay_402 tool. The agent sees the resource, pays, and proceeds — no human in the loop.

agent prompt (Claude)

// Claude Desktop prompt after MCP is connected:
"Use the stablecard MCP to fund a $10 card,
 then call pay_402 to access https://api.example.com/data"

// Claude calls: fund_card(amount=10, chain="base")
// Claude calls: pay_402(card_id="sc_card_...", url="https://...")
// Payment happens. Request succeeds. Done.

06

API Reference

All endpoints are REST over HTTPS. Base URL: https://stablecard.polsia.app

Method	Path	Description
GET	/api/config	Supported chains, treasury address, current mode
GET	/api/signing-payload	EIP-712 typed data ready for `eth_signTypedData_v4`
POST	/api/cards/fund	Create a virtual card, pull USDC atomically on-chain
GET	/api/cards	List cards (filter by wallet_address or status)
GET	/api/cards/:id	Get card details — add `?reveal=true` for PAN/CVV
POST	/api/cards/:id/freeze	Freeze an active card
POST	/api/cards/:id/unfreeze	Unfreeze a frozen card
POST	/api/cards/:id/close	Close card, auto-refund remaining USDC to wallet

Full request/response examples with curl:

GET /api/config

curl https://stablecard.polsia.app/api/config

// Response
{
  "success": true,
  "config": {
    "mode": "live",
    "card_provider": "laso_finance",
    "payment_protocol": "x402",
    "supported_networks": [
      { "id": "base", "chain_id": 8453 },
      { "id": "polygon", "chain_id": 137 },
      ...
    ]
  }
}

POST /api/cards/fund — mock mode (no signing required)

curl -X POST https://stablecard.polsia.app/api/cards/fund \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": "base",
    "label": "agent-research-budget"
  }'

// Response (201)
{
  "success": true,
  "mode": "mock",
  "card": {
    "id": "sc_card_7x9k3m2p",
    "pan_masked": "**** **** **** 5678",
    "balance_usdc": 50,
    "status": "active"
  }
}

07

CLI Commands

Full reference for the stablecard CLI tool.

stablecard config	Interactive setup — endpoint, chain, wallet address
stablecard fund --amount <n>	Create a virtual card funded with USDC. `--chain base\|polygon\|arbitrum\|optimism`
stablecard list	List all cards with balances and statuses
stablecard reveal <id>	Reveal full PAN, CVV, expiry for a card
stablecard freeze <id>	Freeze an active card
stablecard unfreeze <id>	Unfreeze a frozen card
stablecard close <id>	Close card and refund remaining USDC
stablecard pay --url <url>	Handle an x402 HTTP 402 payment automatically
stablecard mcp-server	Start the local MCP server (stdio transport)