# Getting Started

# Visa CLI

Your AI agent gets a Visa card. It can buy images, music, data — anything behind a paywall. Every purchase requires your authorization before money moves.

**Your card stays safe.** Your card number is not stored on your machine — it goes straight to an encrypted vault. Default spending limits ($10/transaction, $100/day) are enforced server-side, not on your computer. You can raise or lower these limits at any time. No authorization, no charge. [Full security model](security.md)

> **Restricted Beta.** Invite-only. [Join the waitlist](https://visacli.sh) to get access.
>
> **Starting with Claude Code.** Visa CLI works with Claude Code today. Support for other MCP-enabled AI clients is rolling out.
>
> **macOS only for now.** Requires macOS with biometric or password authorization, Node.js 18+, and an MCP-compatible AI client. Linux and Windows are not yet supported.

## Set up in 60 seconds

You need **Node.js 18+** and an **MCP-compatible AI client** (such as Claude Code) installed.

> **Tip:** Not sure about Node.js? Open Terminal and type `node --version`. If you see `v18.0.0` or higher, you're good. If not, install from [nodejs.org](https://nodejs.org).

Run these in Terminal before opening Claude Code:

### 1. Install

```bash
npm install -g @visa/cli
```

> **Getting "permission denied"?** Try `sudo npm install -g @visa/cli` and enter your Mac password.

### 2. Run setup

```bash
visa-cli setup
```

A browser window will open. **Sign in with GitHub** and **enter your card** on a secure page. Your card number is sent directly to an encrypted vault — it does not touch your machine and your agent does not see it.

> **Authorization not working?** If your Mac doesn't have Touch ID, setup falls back to your system password. If the prompt doesn't appear at all, run `xcode-select --install` first, then try setup again.

### 3. Open Claude Code

If you ran install and setup in Terminal, just open Claude Code — Visa CLI is ready to use.

> **Already had Claude Code open?** Type `/mcp`, press Enter, arrow down to `visa-cli`, press Enter, arrow to `reconnect`, press Enter.

> **Having issues?** Check the [Error Reference](errors.md).

## Try it

Once you're set up, just ask your AI agent:

```
Generate me an image of a sunset over the mountains
```

An authorization prompt pops up: **"pay $0.06 to fal.ai"**. Approve and the image opens in your browser. Cancel and nothing happens — no charge.

```
Make me a lofi jazz track for studying
```

```
What is the price of Ethereum?
```

Everything costs pennies. See [all tools and pricing](tools/index.md) and [more recipes](recipes.md).

| What | Cost | Example |
|------|------|---------|
| AI image generation | $0.04 – $0.06 | "Generate a logo for my coffee shop" |
| AI video generation | ~$0.30 | "Make a video of waves on a beach" |
| Music generation | ~$0.10 | "Make me a chill beats track" |
| Token price queries | ~$0.02 | "What's the price of SOL?" |
| Batch operations | Per-item x count | "Generate 5 logo variations" |

Card management, tool use history, and spending controls are always free.

## Is my card safe?

Yes.

- **Your card number is not stored on your machine.** During setup, your card goes directly to an encrypted vault. Your computer and your agent do not see the full number — not during setup, not during payment.
- **Your agent gets a token, not your card.** The token only works through our server. It can't be used anywhere else.
- **Every purchase requires authorization.** A prompt shows the exact amount and merchant. No approval, no charge.
- **Server-side spending limits.** $10 per transaction, $100 per day by default — enforced by the server, not your machine. You can adjust these anytime with a single command.
- **Single-use authorization.** Each payment gets a one-time token. Previous approvals can't be replayed.

Read the [full security model](security.md) for the threat model and cryptographic details.

## Learn more

- **[Recipes](recipes.md)** — common workflows you can copy-paste
- **[Tools Reference](tools/index.md)** — every tool and what it costs
- **[Spending Controls](tools/spending-controls.md)** — set limits on what your agent can spend
- **[How It Works](how-it-works.md)** — architecture and payment flow
- **[Security Model](security.md)** — threat model and safeguards
- **[Error Reference](errors.md)** — something went wrong? Start here

> No access yet? [Join the waitlist](https://visacli.sh) to get into the restricted beta.

---

# How It Works

# How It Works

Your machine handles identity. The Visa CLI server handles money. Your card number does not leave the encrypted vault.

> **Looking to get started?** Head to the [setup guide](index.md) first. This page explains what's happening behind the scenes.

## What lives where

| Your machine | Visa CLI server |
|--------------|------------|
| **Session token** (stored in Keychain) | **Card tokens** (encrypted vault, via VGS) |
| **Signing key** (stored in Keychain) | **Spending limits** and enforcement |
| **Authorization prompt** | **Payment processing** |
| **CLI tools** | **Tool use history** |

## What happens when you buy something

1. **Your AI agent calls a payment tool** (like `generate_image_card`)
2. **Visa CLI asks the server** "What will this cost?"
3. **The server replies** with the amount and merchant name
4. **Authorization prompt appears:** "pay $0.06 to fal.ai"
5. **You approve** (or cancel)
6. **Visa CLI sends your signed approval** to the server
7. **The server verifies everything** — checks the signature, checks your limits, runs the payment
8. **You get the result** — the image opens in your browser, receipt shows in your agent

Cancel at step 4 and nothing happens. No charge.

## Payment methods

Visa CLI supports multiple payment methods. The server picks the right one automatically — you never need to choose.

| Method | What happens |
|--------|-------------|
| **Card** | Your tokenized card is charged through the card network |

The merchant says "this costs X," you approve via the authorization prompt, payment executes. Behind the scenes, the gateway may settle with merchants using stablecoins on-chain, but you always pay by card.

## Why this design is safe

Even if someone fully compromises your machine, they cannot:

- **Spend more than your limits** — limits are enforced on the server, not your machine
- **See your card number** — it is not stored on your machine
- **Get around rate limits** — the server tracks these independently
- **Reuse a previous payment** — each approval is single-use

The server enforces its own rules independently — it does not rely on your machine to enforce limits. See [Security Model](security.md) for the full threat model.

## For merchants

> During the restricted beta, Visa CLI works with approved merchants only. Interested in accepting payments? [Contact us](https://visacli.sh).

Merchants accept payments by returning HTTP `402 Payment Required`. Three protocols are supported: [MPP card](https://paymentauth.org/draft-card-charge-00.txt), MPP tempo (stablecoin on Tempo chain), and [x402](https://www.x402.org/) (USDC on Base).

---

> Ready to try it? Go back to [setup](index.md#set-up-in-60-seconds) or explore [recipes](recipes.md). No access yet? [Join the waitlist](https://visacli.sh).

---

# Security

# Security Model

Visa CLI is designed so that even a fully compromised machine cannot drain your card. The server enforces all spending limits, your card number does not leave the encrypted vault, and every payment requires a cryptographic signature tied to your authorization.

**Your maximum exposure is bounded by limits you control:** $10/purchase and $100/day by default. Even in the worst case, an attacker cannot exceed these limits or access your card number. You can adjust them anytime with `update_spending_controls`.

> **Just getting started?** You don't need to read this to use Visa CLI. Head to the [setup guide](index.md) instead. This page is for people who want to understand the security architecture.

## How payments are authorized

During setup, Visa CLI creates a P-256 signing key and stores it in your macOS Keychain (not the Secure Enclave). The matching public key is registered with the server.

For every payment:

1. **Visa CLI requests a one-time token** from the server
2. **A challenge is built** from the token, amount, merchant, and context
3. **The authorization prompt appears** with the amount and merchant name
4. **If you approve,** the key signs the challenge
5. **The signature is sent to the server,** which checks it against your registered key

If you cancel, no signature is produced and the payment stops immediately.

## What's stored on your machine

| What | Where | Purpose |
|------|-------|---------|
| **Session token** | macOS Keychain | Identifies your account to the server |
| **Signing key** | macOS Keychain | Signs payment approvals |

Nothing else. No card numbers, no API keys, no wallet keys.

## Server-side enforcement

Even with a valid session, the server independently enforces:

| Protection | What it does |
|------------|-------------|
| **Spending limits** | $10/purchase, $100/day (you can change these) |
| **Rate limiting** | 1 payment per 3 seconds, throttled reads and auth requests |
| **Signature verification** | Every payment must have a valid cryptographic signature |
| **Single-use tokens** | Each approval uses a one-time nonce that expires in 60 seconds |
| **Amount verification** | Charged amount must be within 10% of the approved amount |

## What a compromised machine cannot do

- **Spend without a valid signature** — the server rejects unsigned or badly signed requests
- **Exceed your limits** — limits are enforced on the server, not your machine
- **Access your card number** — card data exists only in the encrypted vault
- **Replay a previous payment** — each approval uses a single-use token

---

> Want to adjust your limits? See [Spending Controls](tools/spending-controls.md). Ready to get started? [Set up in 60 seconds](index.md#set-up-in-60-seconds). No access yet? [Join the waitlist](https://visacli.sh).

---

# Recipes

# Recipes

Copy any of these prompts straight into your AI agent. Each one shows what it costs and how many approvals to expect.

> **Not set up yet?** [Install in 60 seconds](index.md#set-up-in-60-seconds) and come back here.

## Generate a batch of images

```
Generate 5 logo concepts for a coffee shop called "Terminal Brew"
```

**Cost:** ~$0.30 for Ultra, ~$0.20 for Pro. **Approval:** One authorization prompt for the whole batch. All images open in your browser.

## Create a song with album art

```
Make me a lofi jazz track for studying, then generate album art for it
```

**Cost:** ~$0.10 for the track + ~$0.06 for the image. **Approval:** Two authorization prompts (one per purchase).

## Generate a video

```
Make a 6-second video of a cat knocking things off a desk
```

**Cost:** ~$0.30. **Approval:** One prompt.

## Multi-step creative project

```
Design a brand for a surf shop called "Salt & Sand": generate a logo, a banner image, and a 6-second promo video
```

**Cost:** ~$0.42 (two images + one video). **Approval:** Three prompts, one per asset.

## Song with a specific model

```
Generate an instrumental synthwave track using the V5 model
```

**Cost:** ~$0.10. **Approval:** One prompt. See [music models](tools/generate-music.md#model-versions) for all options.

## Chain creative tools together

```
Generate an image of my logo, then make a video of it spinning
```

**Cost:** ~$0.36 (one image + one video). **Approval:** Two prompts.

## Check token prices

```
What are the current prices of ETH, SOL, and MATIC?
```

**Cost:** ~$0.02 per lookup. **Tip:** Use batch for a single approval across multiple tokens.

## Historical price check

```
What was the price of ETH every day last week?
```

**Cost:** ~$0.02. Uses the `start_timestamp` and `end_timestamp` parameters automatically.

## Batch different prompts

```
Generate these 4 images: a spring meadow, a summer beach, an autumn forest, and a winter snowscape
```

**Cost:** ~$0.24 for Ultra. **Approval:** One prompt for all four.

## Lock down spending for a demo

```
Set my max transaction to $1 and daily limit to $5
```

**Approval:** Requires authorization. Reset to defaults later:

```
Set my max transaction to $10 and daily limit to $100
```

## Check your spending

```
Show my tool use history
```

**Cost:** Free. Returns amounts, merchants, dates, and links to any generated media.

## Start fresh

```
Reset my Visa CLI
```

**Approval:** Requires authorization. After reset, run `visa-cli setup` to set up again.

---

> Need more detail on a specific tool? See the [Tools Reference](tools/index.md). Having trouble? Check the [Error Reference](errors.md). No access yet? [Join the waitlist](https://visacli.sh).

---

# Errors

# Fix an Error

Every error message, what it means, and how to fix it. Each section includes a prompt you can paste into your AI agent.

**Most common fixes:**

1. **"Not logged in"** — Run `visa-cli setup`
2. **"Amount exceeds limit"** — Raise your limits with `update_spending_controls`
3. **"No cards enrolled"** — Add a card with `add_card`
4. **Claude won't run a command** — Prefix it with `!` (see below)

---

## Claude won't run a Visa CLI command

Claude Code may warn you or refuse to run certain commands (like `npm install -g @visa/cli`) because it's being cautious about unfamiliar packages.

**Fix:** Prefix the command with `!` in Claude Code to run it directly in your terminal, bypassing the agent:

```
! npm install -g @visa/cli
```

```
! visa-cli setup
```

The `!` prefix runs the command as a regular terminal command. Claude doesn't need to approve it.

---

## Sign-in and session errors

### "Not logged in. Use the login tool to authenticate."

Your session is missing. Either you haven't set up yet, or your saved login was cleared (after running `reset` or a system update that cleared your Keychain).

**Fix:** Run `visa-cli setup`, or ask your agent to log you in.

```
I'm getting "Not logged in" in Visa CLI. Can you run visa-cli setup for me and walk me through it?
```

### "Your session has expired. Use the login tool to re-authenticate."

Your login session is no longer valid on the server. Sessions expire after a week of inactivity.

**Fix:** Ask your agent to log you in again, or run `visa-cli setup`.

```
My Visa CLI session expired. Can you log me back in?
```

---

## Spending limit errors

### "Amount $X.XX exceeds per-transaction limit of $Y.YY"

This single purchase costs more than your per-purchase limit allows.

**Fix:** Raise your limit or make a smaller purchase.

```
My per-purchase limit is too low. Can you raise it to $200?
```

### "Amount $X.XX would exceed daily limit of $Y.YY (spent today: $Z.ZZ)"

This purchase would push you over your daily spending cap. Limits reset at midnight UTC.

**Fix:** Wait until tomorrow, or raise your daily limit.

```
I hit my daily spending limit. Can you raise it to $1000? Or show me how much I've spent today.
```

---

## Payment errors

### "Could not determine payment amount and merchant. Try again."

Visa CLI couldn't get pricing info from the merchant's URL. The merchant's server may be down, or the URL may be wrong.

**Fix:** Double-check the URL. If it looks right, try again in a minute.

```
Visa CLI can't get the price for this URL: [paste URL]. Can you check if it's working?
```

### "Invalid payment amount: $X. Payment rejected for safety."

The merchant returned a price that looks wrong (negative, not a number, or absurdly high).

**Fix:** This is a safety check. Try again — if it persists, the merchant may have an issue.

```
Visa CLI rejected the payment amount as invalid. Can you try again?
```

### "Merchant price exceeds approved amount"

The merchant changed its price between when you previewed it and when the payment was sent.

**Fix:** Retry to get the current price.

```
The price changed since I last checked. Can you retry?
```

### "Music generation timed out. You were charged $X.XX. Your track may still complete — check back later."

Music generation took longer than expected. You were charged because generation started, but the track may still finish.

**Fix:** Wait a few minutes and check the status.

```
My music timed out but I was charged. Can you check the status with check_music_status_tempo_card?
```

---

## Network errors

### "Cannot reach the Visa CLI server. Check your internet connection and try again."

Your machine can't connect to the Visa CLI server. Your internet may be down, or a VPN/firewall may be blocking the connection.

**Fix:** Check your internet connection. If you're behind a VPN or corporate firewall, make sure `auth.visacli.sh` is reachable.

```
Visa CLI can't reach the server. Can you check if auth.visacli.sh is reachable from my machine?
```

### "The request timed out. The server may be under heavy load. Please try again."

The server didn't respond in time (30 seconds for most requests, 6 minutes for music).

**Fix:** Try again. Music generation can genuinely take a couple of minutes.

---

## Batch errors

### "Batch request failed" / "Merchant server error"

One or more items in your batch failed. The upstream service may be overloaded or temporarily down.

**Fix:** Wait a minute and retry with a smaller batch.

```
My batch request failed. Can you retry with a smaller batch — maybe 3 at a time instead?
```

---

## Card errors

### "No cards enrolled. Use the add_card tool to add a payment card."

You're trying to make a purchase but you haven't added a card yet. You may have skipped the card step during setup, or you ran `reset`.

**Fix:** Add a card before making payments.

```
I don't have a card set up yet. Can you help me add one?
```

---

## Setup errors

### "Xcode Command Line Tools required. Install: xcode-select --install"

Setup can't build the authorization component because Xcode Command Line Tools aren't installed. Most Macs don't have them by default.

**Fix:**

```bash
xcode-select --install
```

A system dialog will appear. Click "Install" and wait for it to finish (a few minutes). Then run `visa-cli setup` again.

### "Attestation key not found. Run setup to generate a new key."

The key that signs your payment approvals is missing from your Keychain. This can happen after a macOS migration, restoring from backup, or manually deleting Keychain items.

**Fix:** Run `visa-cli setup` to create a new key.

```
My signing key is missing. Can you run visa-cli setup to fix it?
```

---

## General troubleshooting

If none of the above matches:

**Check if everything is connected:**

```
Can you check my Visa CLI status? Run get_status and tell me if everything looks good.
```

**Start fresh:**

```
Something is broken with my Visa CLI setup. Can you reset it and walk me through setting it up again from scratch?
```

---

## Add a debug command to Claude Code

Copy this into `.claude/commands/debug-visa-cli.md` in any project to get a `/debug-visa-cli` slash command:

```
You are a Visa CLI debugger. Help the user diagnose and fix their issue.

Step 1: Ask for the exact error message (skip if already provided).

Step 2: Match and fix:

Authentication:
- "Not logged in" → visa-cli setup or login tool
- "Session expired" → Re-authenticate via login tool
- "Attestation key not found" → visa-cli setup

Payments:
- "Could not determine payment amount" → Check the merchant URL
- "Invalid payment amount" → Retry, may be a merchant issue
- "Merchant price exceeds approved amount" → Retry to get current price

Limits:
- "Amount exceeds per-transaction limit" → update_spending_controls
- "Would exceed daily limit" → Wait for midnight UTC reset or raise dailyLimit

Rate limiting:
- "Rate limited" -> Wait 3 seconds between payments
- "Too many requests" → Wait, or use batch tool

Batch:
- "Batch request failed" / "Merchant server error" → Wait, retry with smaller batch

Network:
- "Request timed out" → Retry (music takes up to 6 minutes)
- "Cannot reach the Visa CLI server" → Check internet, ensure auth.visacli.sh is reachable
- "Service temporarily unavailable" → Wait a few minutes

Cards:
- "No cards enrolled" → add_card tool or visa-cli setup

Setup:
- "Xcode Command Line Tools required" → xcode-select --install, then visa-cli setup

Server:
- "Something went wrong on our end" → Retry, check github.com/Visa-Crypto-Labs/Visa-CLI/issues

Step 3: Verify the fix worked (get_status for auth/limits, retry for payments).

Step 4: Still stuck? Check /mcp in your AI client, visa-cli --version, or GitHub issues.
```

---

> Still stuck? [Contact us](https://visacli.sh). Want to start over? Run `visa-cli setup` or see the [setup guide](index.md#set-up-in-60-seconds).

---

# Brand

# Brand

Terminal is the brand. Dark only. No light mode. Monospace everything. Black and white.

## The cursor-card

The terminal cursor is a tall, thin rectangle that blinks. A credit card rotated 90° is the same shape. One icon, two meanings — CLI and payments fused together. The chip detail is the only thing that reveals it's a card.

## Colors

```
#000000    Background
#0a0a0a    Elevated surfaces
#111111    Terminal / code blocks
#222222    Borders, dividers
#333333    Subtle borders, hover
#888888    Secondary text, labels
#e0e0e0    Body text
#ffffff    Headings, emphasis, accent
```

Black and white only. No color accents.

## Typography

```
Menlo, 'SF Mono', Monaco, 'Courier New', monospace
14px body, 1.7 line-height
```

## Design tokens

```css
--bg:            #000000
--bg-elevated:   #0a0a0a
--bg-terminal:   #111111
--border:        #222222
--border-light:  #333333
--text:          #e0e0e0
--text-dim:      #888888
--text-bright:   #ffffff
--accent:        #ffffff
--cursor:        #e0e0e0
```

## Assets

Mark, profile picture, banner, and OG image SVGs are available in `site/assets/`. All black and white.

### Marks

- `mark-v4-cursor-card.svg` — Full detail card cursor with chip and stripe
- `mark-v5-cursor-card-inline.svg` — Card cursor sitting at a `$` prompt
- `mark-v6-cursor-card-minimal.svg` — Minimal: cursor shape + one chip square

### Social

- `pfp-400-dark-v4-cursor-card.svg` — Profile picture, outlined
- `pfp-400-dark-v5-cursor-card-solid.svg` — Profile picture, solid
- `pfp-400-dark-v6-cursor-card-minimal.svg` — Profile picture, ultra minimal
- `banner-1500x500-dark.svg` — Twitter/X banner, terminal + brand
- `banner-1500x500-dark-v2.svg` — Twitter/X banner, centered minimal
- `og-default-1200x630-dark.svg` — OG image, general sharing
- `og-tagline-1200x630-dark.svg` — OG image, announcements

## Usage guidelines

- Always use the marks on a black or very dark background
- Do not add color to the marks — they are black and white only
- Do not stretch, rotate, or add effects to the cursor-card icon
- Maintain clear space around the mark equal to the width of the cursor shape
- When pairing with text, use the monospace font stack at 14px or larger
- The cursor-card is the primary brand element — do not create alternative logos

## Voice

The product speaks like a terminal. Short, declarative sentences. No marketing adjectives. State what something does, not how it makes you feel.

- "Every payment requires authorization." not "Secure, seamless payments you can trust."
- "Two commands to set up." not "Get started in minutes with our easy onboarding."
- "$0.06 per image." not "Affordable AI-powered image generation."

---

# REST API

# REST API

Build apps and agents on Visa CLI payment rails. Authenticate with an API key, discover tools from the catalog, and execute them with a single POST.

> **Employee Beta.** API keys are currently restricted to employees. External access coming soon.

## Quick Start

```bash
# 1. Discover available image tools
curl https://auth.visacli.sh/v1/catalog?category=image&available=true

# 2. Generate an image
curl -X POST https://auth.visacli.sh/v1/api/shortcuts/fal-flux-schnell \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a neon cityscape at night"}'
```

**Response:**

```json
{
  "success": true,
  "transaction_id": "e6ea48b8-...",
  "amount": 0.01,
  "tool": "fal-flux-schnell",
  "category": "image",
  "content": "https://v3b.fal.media/files/.../image.jpg",
  "urls": ["https://v3b.fal.media/files/.../image.jpg"],
  "data": null
}
```

Read `content` for the primary result. It's always a URL for media tools and text for LLM tools.

---

## Authentication

Every tool call requires an API key in the `X-Api-Key` header. Catalog discovery is unauthenticated.

```
X-Api-Key: vk_YOUR_KEY
```

API keys are scoped with `allowed_tools` (which tools the key can call) and `daily_cap_cents` (max daily spend).

---

## Endpoints

### Discover Tools

```
GET /v1/catalog
```

No auth required. Returns tools with pricing, input schemas, and availability.

| Param | Description |
|-------|-------------|
| `q` | Search query (name, description, tags) |
| `category` | Filter: `image`, `video`, `audio`, `llm`, `3d`, `tts`, `transcription` |
| `limit` | Max results, 1-50 (default 10) |
| `available` | Set to `true` to hide unavailable tools |

Each tool includes `status: "available"` or `"unavailable"` so your agent knows what's callable before spending a request.

### Tool Details

```
GET /v1/catalog/:id
```

Full details for one tool, including `inputSchema` (JSON Schema describing accepted parameters).

### Execute a Tool

```
POST /v1/api/shortcuts/:tool_id
```

Runs the tool and charges your account. Body is tool-specific — see `inputSchema` from the catalog.

**Reserved body fields** (not forwarded to the tool):

| Field | Description |
|-------|-------------|
| `idempotency_key` | Prevent duplicate charges on retry |
| `user_context` | Free-text note stored with the transaction |

---

## Response Format

### Success

```json
{
  "success": true,
  "transaction_id": "uuid",
  "amount": 0.04,
  "rail": "mpp",
  "tool": "fal-flux-pro",
  "category": "image",
  "content": "https://...",
  "urls": ["https://..."],
  "data": null
}
```

| Field | Description |
|-------|-------------|
| `transaction_id` | Unique charge ID for tracking and support |
| `amount` | Actual USD charged (may differ from catalog for token-priced LLMs) |
| `category` | Tool category — use this to interpret the result |
| `content` | Primary result: URL for media, text for LLMs. Read this field first. |
| `urls` | All result URLs (multiple for batch, empty for LLMs) |
| `data` | Extra metadata (LLM token counts, model info) |

### Errors

```json
{
  "success": false,
  "error": "Human-readable message",
  "error_code": "TOOL_NOT_FOUND",
  "hint": "GET /v1/catalog to list available tools."
}
```

Handle errors by branching on `error_code`:

| Code | HTTP | What to do |
|------|------|------------|
| `AUTH_REQUIRED` | 401 | Add `X-Api-Key` header |
| `AUTH_INVALID` | 401 | Check your key |
| `TOOL_NOT_FOUND` | 404 | Use `GET /v1/catalog` for valid tool IDs |
| `TOOL_NOT_PERMITTED` | 403 | Key doesn't have access to this tool |
| `ACCOUNT_NOT_APPROVED` | 403 | Contact admin |
| `RATE_LIMITED` | 429 | Daily cap reached, wait or increase |
| `SPEND_LIMIT_EXCEEDED` | 403 | Adjust spending controls |
| `GATEWAY_UNAVAILABLE` | 502 | Retry with backoff |
| `GATEWAY_ERROR` | 4xx/502 | Check error message, may be transient |
| `INTERNAL_ERROR` | 500 | Retry; report if persistent |

---

## Available Tools

### Image Generation

All accept `prompt` (required) and `aspect_ratio` (optional, e.g. `"16:9"`, `"1:1"`, `"9:16"`).

| Tool | Quality | Speed | Cost |
|------|---------|-------|------|
| `fal-flux-schnell` | Good | ~5s | $0.01 |
| `fal-flux-pro` | High | ~23s | $0.04 |
| `fal-flux-pro-ultra` | Best | ~29s | $0.06 |
| `fal-flux-dev` | Good | ~3s | $0.03 |
| `fal-ideogram-v2-turbo` | High | ~13s | $0.04 |
| `fal-fast-sdxl` | Basic | ~6s | Free |
| `generate_image_recraft_card` | High | ~28s | $0.04 |

Card-wrapper aliases: `generate_image_card` (ultra), `generate_image_fast_card` (pro), `generate_image_schnell_card` (schnell).

### Video Generation

| Tool | Cost | Notes |
|------|------|-------|
| `generate_video_tempo_card` | $0.50 | Synchronous, ~80s, returns `.mp4` URL |

### Music & Audio

| Tool | Cost | Notes |
|------|------|-------|
| `generate_music_tempo_card` | $0.25 | Via Suno. Server polls until complete. |
| `fal-tts` | $0.02 | Text-to-speech |

### LLM (Language Models)

Send an OpenAI-compatible `messages` array. Token-priced.

```bash
curl -X POST https://auth.visacli.sh/v1/api/shortcuts/or-gpt-4o \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "What is 2+2?"}]}'
```

| Tool | Input $/M | Output $/M |
|------|-----------|------------|
| `or-gpt-4o` | $2.50 | $10.00 |
| `or-gpt-4.1` | $2.00 | $8.00 |
| `or-claude-sonnet-4-6` | $3.00 | $15.00 |
| `or-gemini-2.5-flash` | $0.15 | $0.60 |
| `or-deepseek-v3` | $0.14 | $0.28 |

`content` field returns the model's text response. `data.actualTokens` has the exact token counts.

---

## Agent Integration

### Recommended Flow

```
1. GET /v1/catalog?available=true  →  cache tool list
2. Pick tool by category + price   →  read inputSchema
3. POST /v1/api/shortcuts/{id}     →  build body from schema
4. Read response.content           →  primary result in one field
5. On error: branch on error_code  →  retry, fallback, or stop
```

### Cost Control

- Check `priceCents` in catalog before calling
- `daily_cap_cents` on API keys is a hard server-side ceiling
- Monitor `amount` in responses — actual charge for LLMs depends on token usage
- Use `transaction_id` to audit spend

### Idempotency

Prevent duplicate charges on network retries:

```json
{
  "prompt": "a sunset",
  "idempotency_key": "my-unique-request-id"
}
```

---

## Rate Limits

| Endpoint | Limit |
|----------|-------|
| Catalog (`GET /v1/catalog`) | 60 req/min |
| Tool execution | Per-key daily cap + global rate limit |

---

## MCP Integration

The same tools are available through the Visa CLI MCP server for direct integration with AI agents like Claude Code:

```json
{
  "mcpServers": {
    "visa-cli": {
      "command": "visa-cli",
      "args": ["mcp"]
    }
  }
}
```

The MCP server adds convenience wrappers (e.g., `generate_image` with tier selection) on top of the same catalog tools. See the [Getting Started guide](index.md) for MCP setup.

---

# Tools Overview

# Tools Reference

Every tool available in Visa CLI and what it costs. The server picks the payment method automatically.

## Payment tools

These tools call external services and cost money. Every one shows the exact price in an authorization prompt before charging.

| Tool | What it does | Cost |
|------|-------------|------|
| **[pay](pay.md)** | Pay any merchant URL | Varies |
| **[generate_image_card](generate-image.md)** | Generate an AI image (Ultra quality) | ~$0.06 |
| **[generate_image_fast_card](generate-image.md)** | Generate an AI image (Pro quality) | ~$0.04 |
| **[generate_video_tempo_card](generate-video.md)** | Generate an AI video (~6s clip) | ~$0.30 |
| **[generate_music_tempo_card](generate-music.md)** | Generate a music track | ~$0.10 |
| **[check_music_status_tempo_card](generate-music.md#check-on-your-music)** | Check music generation progress | ~$0.01 |
| **[query_onchain_prices_card](query-prices.md)** | Get real-time token prices from 150+ chains | ~$0.02 |
| **[batch](batch.md)** | Run any paid tool multiple times, one approval | Per-item x count |

## Card management (free)

| Tool | What it does |
|------|-------------|
| **[get_status](manage-cards.md#get_status)** | See your cards, limits, and daily spending |
| **[add_card](manage-cards.md#add_card)** | Add a payment card (opens browser) |
| **[get_cards](manage-cards.md#get_cards)** | List your cards (last 4 digits only) |

## Account (free)

| Tool | What it does |
|------|-------------|
| **[login](account.md#login)** | Sign in with GitHub (opens browser) |
| **[transaction_history](account.md#transaction_history)** | See tool use history |
| **[feedback](account.md#feedback)** | Submit feedback about Visa CLI |
| **[reset](account.md#reset)** | Clear all credentials and start over |

## Settings (free)

| Tool | What it does |
|------|-------------|
| **[update_spending_controls](spending-controls.md)** | Set per-purchase and daily limits (requires authorization) |

## HUD and CLI utility (free)

| Tool | What it does |
|------|-------------|
| **[visa-cli hud enable](hud.md)** | Pin the Visa HUD below Claude Code input |
| **[visa-cli hud disable](hud.md)** | Remove the Visa HUD |
| **[visa-cli statusline](hud.md)** | Render the multi-line HUD used by Claude Code |

## What's free and what's paid?

Card management, account tools, and spending controls are always free. Only tools that call external services cost money — and every paid tool shows the exact cost before charging.

---

# Pay

# Pay a Merchant

Pay a merchant URL. The amount and payment method are detected automatically.

> During the restricted beta, `pay` works with approved merchants only.

## Cost

Varies by merchant. The exact amount is shown in the authorization prompt before you approve.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **`url`** | string | Yes | The merchant's payment URL |
| **`merchantName`** | string | No | Merchant name (detected automatically if you skip this) |
| **`description`** | string | No | Description of the purchase |
| **`method`** | string | No | `GET` or `POST` (default: `GET`) |
| **`body`** | string | No | JSON request body for POST endpoints |

## Example

```
Pay for the US spending data at https://mpp-card.up.railway.app/legacy/visa/spending/country/us
```

## What happens

1. **Visa CLI checks the merchant URL** for payment details
2. **The server figures out** the amount and payment method
3. **Authorization prompt appears:** "pay $25.00 to Example"
4. **You approve,** payment runs, result comes back to Visa CLI

```json
{
  "success": true,
  "transactionId": "txn_f8018e6e",
  "rail": "card",
  "amount": 25.00,
  "merchantName": "Example",
  "cardLast4": "4242"
}
```

## Requirements

- **Card added** — you need a card on file
- **Authorization** — you approve every purchase
- **Within your limits** — the amount must be under your per-purchase and daily caps

---

# Generate Image

# Generate an Image

Create AI images from text prompts via fal.ai. Two quality tiers are available — your agent will ask which one you want.

## Tiers

| Tool | Model | Cost | Resolution | Speed |
|------|-------|------|------------|-------|
| **`generate_image_card`** | FLUX1.1 [pro] ultra | ~$0.06 | 2K | ~30s |
| **`generate_image_fast_card`** | FLUX1.1 [pro] | ~$0.04 | 1K | ~10s |

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **`prompt`** | string | Yes | Describe the image you want |
| **`aspect_ratio`** | string | No | Output shape (default: `16:9`) |

### Aspect ratios

`21:9`, `16:9`, `3:2`, `5:4`, `1:1`, `4:5`, `2:3`, `9:16`, `9:21`

## Example

```
Generate me an image of a sunset over the mountains
```

```
Create a logo for a coffee shop called "Terminal Brew"
```

Your agent will ask whether you want Ultra ($0.06, 2K) or Pro ($0.04, 1K) before generating.

## What happens

1. **Your agent asks which tier** you want (Ultra or Pro)
2. **Authorization prompt appears:** "pay $0.06 to fal.ai" (or $0.04 for Pro)
3. **You approve** and the image generates
4. **The image opens automatically** in your browser
5. **The URL appears** in the response

> **Tip:** Be specific in your prompts. "A minimalist logo for a coffee shop with a steaming cup" works better than "coffee shop logo."

## Generate multiple images at once

Create several images with a single authorization:

```
Generate 5 images of different seasons
```

This uses the [batch](batch.md) tool. You approve the total (~$0.30 for 5 Ultra images) once.

## Requirements

- **Card added** — you need a card on file
- **Authorization** — you approve every purchase
- **Within your limits** — the total must be under your per-purchase and daily caps

---

# Generate Music

# Generate Music

Create a music track using Suno AI.

## Cost

~$0.10 per track.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **`prompt`** | string | Yes | Describe the music you want |
| **`model`** | string | No | Suno model version (see below). Default: `V4` |
| **`instrumental`** | boolean | No | Set to `true` for instrumental only, no vocals. Default: `false` |

### Model versions

| Model | Best for |
|-------|---------|
| **`V4`** | Fast generation, reliable quality (default) |
| **`V4_5`** | Improved vocals and instrumentals |
| **`V4_5ALL`** | V4.5 with all enhancements enabled |
| **`V4_5PLUS`** | V4.5 Plus — extended generation |
| **`V5`** | Latest model, highest quality |

If you don't specify a model, `V4` is used.

## Example

```
Make me a lofi jazz beat for studying
```

```
Generate an upbeat summer pop song about road trips
```

## What happens

1. **Authorization prompt appears:** "pay $0.10 to Suno via Tempo"
2. **You approve** and generation starts (~2 minutes)
3. **Your agent polls automatically** using `check_music_status_tempo_card`
4. **When it's ready,** the track page opens in your browser

## Check on your music

Music takes about 2 minutes. Your agent checks progress automatically with `check_music_status_tempo_card`:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **`taskId`** | string | Yes | The task ID from `generate_music_tempo_card` |

Each status check costs ~$0.01 and requires authorization. Your agent checks at most once per minute.

When the track is ready, audio URLs open in your browser.

## Requirements

- **Card added** — you need a card on file
- **Authorization** — you approve each check
- **Within your limits** — the total must be under your per-purchase and daily caps

---

# Generate Video

# Video Generation

Generate AI videos using Grok Imagine Video (xAI) via fal.ai.

> During the restricted beta, video generation works with approved merchants only.

## Cost

~$0.30 per video. ~6 second clip at 1280x720.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **prompt** | string | Yes | Text description of the video to generate |
| **aspect_ratio** | string | No | `16:9` (default), `9:16`, or `1:1` |

## Example

```
Generate a 6-second video of ocean waves crashing on a beach at sunset
```

An authorization prompt appears: "pay ~$0.30 to fal.ai". Approve and the video opens in your browser.

## What happens

1. **Visa CLI sends your prompt** to fal.ai via the Tempo payment network
2. **The server figures out** the amount and payment method
3. **Authorization prompt appears:** "pay ~$0.30 to fal.ai"
4. **You approve**, payment runs, video is generated (~30-60 seconds)
5. **Video URL opens** in your browser

## Requirements

- **Card added** — you need a card on file
- **Authorization** — you approve every purchase
- **Within your limits** — the amount must be under your per-purchase and daily caps

---

# Query Prices

# Look Up Token Prices

Get real-time and historical token prices from 150+ blockchains via Allium.

## Cost

~$0.02 per query.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **`chain`** | string | Yes | Blockchain network (e.g., `ethereum`, `solana`, `base`, `polygon`, `arbitrum`) |
| **`token_address`** | string | Yes | Token contract address on that chain |
| **`start_timestamp`** | string | No | Start of date range for historical prices (ISO 8601, e.g., `2025-03-01T00:00:00Z`). Skip for real-time. |
| **`end_timestamp`** | string | No | End of date range (ISO 8601). Skip for real-time. |
| **`time_granularity`** | string | No | Time interval for historical data: `1h`, `1d`, or `1w` (default: `1d`) |

## Example

**Real-time price:**

```
What's the price of ETH right now?
```

**Historical prices:**

```
Show me ETH prices for the last week
```

## What happens

1. **Authorization prompt appears:** "pay $0.02 to Allium"
2. **You approve** and the price data comes back to your agent

```json
{
  "token": "ETH",
  "chain": "ethereum",
  "price_usd": 3847.12,
  "volume_24h": 18420000000,
  "price_change_24h": 2.4,
  "last_updated": "2026-03-28T12:00:00Z"
}
```

Prices come from on-chain DEX activity across 150+ chains. Historical queries return time-series data at the interval you chose.

## Requirements

- **Card added** — you need a card on file
- **Authorization** — you approve every query
- **Within your limits** — the amount must be under your per-purchase and daily caps

---

# Batch

# Run Multiple Operations at Once

Run any paid tool multiple times in parallel with a single authorization.

## Cost

Per-item price multiplied by the number of items. The total is shown in the authorization prompt.

**Example:** 5 images at ~$0.06 each = ~$0.30 total, one approval.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **`tool`** | string | Yes | Which tool to run: `generate_image_card`, `generate_image_fast_card`, `generate_video_tempo_card`, `generate_music_tempo_card`, `query_onchain_prices_card` |
| **`count`** | number | No | How many times to run it (use with `params`) |
| **`params`** | object | No | Settings shared across all runs |
| **`requests`** | array | No | List of different settings per run (for varied inputs) |

## Same prompt, multiple runs

```json
{
  "tool": "generate_image_card",
  "count": 10,
  "params": { "prompt": "a misty mountain at dawn" }
}
```

## Different prompts per run

```json
{
  "tool": "generate_image_card",
  "requests": [
    { "prompt": "spring meadow" },
    { "prompt": "summer beach" },
    { "prompt": "autumn forest" },
    { "prompt": "winter snowscape" }
  ]
}
```

## Example

```
Generate 5 images of different cyberpunk cityscapes
```

**Authorization prompt appears:** "pay $0.30 to fal.ai (5 items, $0.06 each)"

All results open automatically in your browser.

## Limits

- **10 items max** per batch
- **Checked against your daily cap** before anything runs
- **All or nothing** — if the total would exceed your remaining balance, the entire batch is rejected. No partial charges.

## Requirements

- **Card added** — you need a card on file
- **Authorization** — one approval for the whole batch
- **Within your limits** — the total must be under your per-purchase and daily caps

---

# HUD

# Visa HUD

The Visa HUD is a free CLI surface that pins live status below Claude Code input. It shows your Visa spend line, the active Claude model, project, context usage, rate-limit usage, and recent tools.

## Enable the HUD

**Command:** `visa-cli hud enable`

**Cost:** Free, no authorization required.

```bash
visa-cli hud enable
```

This registers Visa CLI as Claude Code's `statusLine` renderer. Once enabled, the HUD appears automatically in Claude Code.

---

## Disable the HUD

**Command:** `visa-cli hud disable`

**Cost:** Free, no authorization required.

```bash
visa-cli hud disable
```

This removes the Visa HUD from Claude Code without touching unrelated settings.

---

## Render the HUD manually

**Command:** `visa-cli statusline`

**Cost:** Free, no authorization required.

```bash
visa-cli statusline
```

Claude Code runs this automatically after `hud enable`, but it is still a normal CLI command. It reads Claude Code status JSON from stdin and prints the multi-line HUD.

---

# Account

# Manage Your Account

## Sign in

**Tool:** `login`

Sign in with GitHub and set up your payment card.

**Parameters:** None

**Cost:** Free, no authorization required.

```
Log me in to Visa CLI
```

Opens a browser for GitHub sign-in. After you sign in and add a card, tell your agent you're done. It verifies with `get_status`.

---

## View your tool use history

**Tool:** `transaction_history`

See your past tool usage — amounts, merchants, dates, status, and links to any generated media.

**Parameters:** None

**Cost:** Free, no authorization required.

```
Show my recent tool usage
```

```json
{
  "transactions": [
    {
      "id": "txn_f8018e6e",
      "type": "card",
      "amount": 0.06,
      "merchantName": "fal.ai",
      "status": "completed",
      "timestamp": "2026-03-28T06:44:36.646Z",
      "rail": "card",
      "cardLast4": "4242"
    }
  ],
  "stats": {
    "totalTransactions": 15,
    "totalSpent": 23.47,
    "last30Days": 23.47
  }
}
```

---

## Submit feedback

**Tool:** `feedback`

Send feedback about Visa CLI directly from your agent.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **`message`** | string | Yes | Your feedback in your own words |
| **`transaction_id`** | string | No | Link feedback to a specific transaction |

**Cost:** Free, no authorization required.

```
Send feedback to Visa CLI: the image generation is great but I'd love higher resolution options
```

---

## Start fresh

**Tool:** `reset`

Clear all your credentials and start over. Removes your session token, signing key, and server-side session.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **`confirm`** | boolean | Yes | Must be `true` to proceed |

**Cost:** Free.

**Requires:** Authorization.

```
Reset my Visa CLI
```

After reset, run `visa-cli setup` to set up again.

---

# Manage Cards

# Manage Your Cards

## Check your status

**Tool:** `get_status`

See your cards, limits, and how much you've spent today.

**Parameters:** None

**Cost:** Free, no authorization required.

```
What's my Visa CLI status?
```

Returns your sign-in state, card count, spending limits, and today's spending.

---

## Add a card

**Tool:** `add_card`

Open a secure browser page to add a new payment card. Replaces any previously added card.

**Parameters:** None

**Cost:** Free, no authorization required.

```
I want to add a new card
```

A browser window opens with a secure card form. Your card data goes directly to an encrypted vault — it does not touch your machine or Visa CLI.

After you finish in the browser, tell your agent you're done and it will verify with `get_status`.

---

## List your cards

**Tool:** `get_cards`

See your cards on file (last 4 digits only).

**Parameters:** None

**Cost:** Free, no authorization required.

```json
{
  "cards": [
    {
      "brand": "visa",
      "last4": "4242",
      "expiryMonth": "12",
      "expiryYear": "2027",
      "isDefault": true
    }
  ]
}
```

Your full card number is not shown or stored on your machine.

---

# Spending Controls

# Set Spending Limits

**Tool:** `update_spending_controls`

Control how much your agent can spend per purchase and per day. Requires `confirm: true` and authorization.

## Cost

Free. Requires authorization.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| **`confirm`** | boolean | Yes | Must be `true` to apply changes |
| **`maxTransactionAmount`** | number | No | Maximum per purchase (USD) |
| **`dailyLimit`** | number | No | Maximum total per day (USD) |

Only include the settings you want to change.

## Defaults

| Setting | Default |
|---------|---------|
| **Max per purchase** | $10 |
| **Daily limit** | $100 |
| **Daily transaction count** | 50 |

## Example

```
Set my daily limit to $50 and max transaction to $10
```

**Authorization prompt appears:** "update spending controls"

## How limits work

Limits are enforced on the server. Your machine cannot bypass them.

- **Every payment is checked** against your remaining daily balance before it runs
- **Per-purchase limit:** if a single payment exceeds it, the payment is rejected
- **Daily limit:** if a payment would push you over, it's rejected
- **Limits reset** at midnight UTC

> **Tip:** Set low limits before demos or when someone else is using your machine. You can always raise them later.

## Check your current limits

Use `get_status` to see your limits and how much you've spent today:

```
What are my spending limits?
```

```json
{
  "spendingControls": {
    "maxTransactionAmount": 10,
    "dailyLimit": 100,
    "dailySpent": 2.34,
    "dailyRemaining": 97.66,
    "dailyTransactionsUsed": 3,
    "dailyTransactionsRemaining": 47
  }
}
```

## Requirements

- **Authorization** — you approve every limit change