agent-pay

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cypher Pay — Virtual Cards for AI Agents

Cypher Pay — 面向AI Agent的虚拟卡

Cypher Pay gives AI agents programmable virtual Visa cards. Create cards on demand, set spend limits, handle 3DS, and manage card lifecycle (single-use or reusable). All operations available via the

agent-pay

CLI — every command outputs JSON to stdout.

Cypher Pay为AI Agent提供可编程虚拟Visa卡。可按需创建卡片、设置消费限额、处理3DS验证，并管理卡片生命周期（一次性或可重复使用）。所有操作均可通过

agent-pay

CLI完成——每个命令都会向标准输出（stdout）输出JSON格式结果。

When to invoke

调用时机

Trigger when end-user needs to buy something online and lacks a payment method, OR explicitly asks for "cypher pay" / "agent card" / "virtual card for this purchase".

This is a CONSUMER automation flow. Do NOT:

ask which directory to create a project in
ask about frameworks, TypeScript vs JavaScript, or build tools
show code to the user or ask permission to run code
ask to set up a
```
package.json
```
or install dependencies into user projects

You run CLI commands yourself. The user sees only: onboarding prompts (email, OTP, personal details), funding links, and purchase confirmations. All agent-pay commands output JSON — parse it silently, surface only what matters to the user.

当终端用户需要在线购买商品但缺少支付方式，或明确要求使用"cypher pay" / "agent card" / "本次购买用虚拟卡"时触发。

这是面向消费者的自动化流程。请勿：

询问要在哪个目录创建项目
询问框架、TypeScript与JavaScript选择，或构建工具相关问题
向用户展示代码或请求运行代码的权限
要求设置
```
package.json
```
或向用户项目中安装依赖

由你自行运行CLI命令。用户仅会看到：注册提示（邮箱、OTP验证码、个人信息）、充值链接和购买确认信息。所有agent-pay命令均输出JSON——你需静默解析，仅向用户展示关键信息。

Prerequisites

前置条件

Ensure the CLI is available. Install globally once (silent, no user prompt needed):

bash

npm install -g @cypherhq/agent-pay

Or use

npx @cypherhq/agent-pay <command>

if you prefer not to install globally.

确保CLI可用。只需全局安装一次（静默安装，无需用户确认）：

bash

npm install -g @cypherhq/agent-pay

若你不想全局安装，也可使用

npx @cypherhq/agent-pay <command>

。

Session detection (run FIRST, every invocation)

会话检测（每次调用首先执行）

Start here. Every time. No exceptions.

Step 1 — Check for existing token: The CLI auto-reads tokens from

AGENT_PAY_TOKEN

env var or

~/.config/cypher-pay/token

. Just verify:

Run
```
agent-pay agent
```
. If exit code 0 → token valid, skip to purchase flow.

If exit code 2 or no token → ask user for their email, then run:

bash

agent-pay auth-status <email>

This returns

{ "enrolled": bool, "kycComplete": bool }

. No OTP sent, no auth required. Branch:

enrolled	kycComplete	Action
true	true	User has account — just needs token. Run Returning user flow below.
true	false	Account exists, KYC incomplete. Get token first (Returning user flow), then resume KYC.
false	false	Brand new user. Present Onboarding paths and let them pick.

Step 2 — Handle stale token: If

agent-pay agent

returns exit code 2 (auth error), delete the stored token and restart from Step 1:

bash

rm -f ~/.config/cypher-pay/token

从此步骤开始，每次调用都必须执行，无例外。

步骤1 — 检查现有令牌： CLI会自动从

AGENT_PAY_TOKEN

环境变量或

~/.config/cypher-pay/token

读取令牌。只需验证：

运行
```
agent-pay agent
```
。若退出码为0 → 令牌有效，直接跳转至购买流程。

若退出码为2或无令牌 → 询问用户邮箱，然后运行：

bash

agent-pay auth-status <email>

该命令返回

{ "enrolled": bool, "kycComplete": bool }

。此步骤不会发送OTP，无需验证权限。根据结果分支处理：

enrolled	kycComplete	操作
true	true	用户已有账户——仅需获取令牌。执行下方的「老用户流程」。
true	false	账户已存在，但KYC未完成。先获取令牌（老用户流程），再继续完成KYC。
false	false	新用户。展示「注册流程选项」让用户选择。

步骤2 — 处理过期令牌： 若

agent-pay agent

返回退出码2（认证错误），删除存储的令牌并重新从步骤1开始：

bash

rm -f ~/.config/cypher-pay/token

Returning user flow

老用户流程

User is enrolled but has no local token. Get one via OTP:

bash

agent-pay request-token <email>

Tell user: "Check your email for a verification code."

bash

agent-pay verify-otp <email> <otp>

Token is stored automatically by the CLI. No manual persistence needed. If

kycComplete

was false, continue to KYC steps in Path B below.

用户已注册但本地无令牌。通过OTP获取：

bash

agent-pay request-token <email>

告知用户："请检查你的邮箱获取验证码。"

bash

agent-pay verify-otp <email> <otp>

令牌会由CLI自动存储，无需手动持久化。若之前

kycComplete

为false，继续执行下方路径B中的KYC步骤。

Onboarding paths

注册流程选项

First-run only (enrolled=false). Present BOTH options — do not pick for the user:

First-time setup — pick one: A) Web signup — sign up at https://agentpay.cypherhq.io in your browser. Easiest option. B) Right here — I'll walk you through it step by step. You'll only need your browser once for identity verification.

仅首次运行时执行（enrolled=false）。需同时展示两个选项——不要替用户选择：

首次设置——请选择一项： A) 网页注册 — 在浏览器中访问https://agentpay.cypherhq.io完成注册。最简单的选项。 B) 在此完成 — 我会逐步引导你完成。仅需在浏览器中完成一次身份验证。

Path A — Webapp onboarding

路径A — 网页端注册

Tell user: "Open https://agentpay.cypherhq.io and complete signup + identity verification."
Once done, user returns and the agent runs the Returning user flow (request-token → verify-otp) to authenticate locally.
Verify with
```
agent-pay agent
```
.

告知用户："打开**https://agentpay.cypherhq.io**并完成注册+身份验证。"
用户完成后返回，agent执行「老用户流程」（request-token → verify-otp）完成本地认证。
运行
```
agent-pay agent
```
验证。

Path B — Native (CLI) onboarding

路径B — 原生（CLI）注册

All commands run by you. User provides info conversationally — never show them raw commands or JSON.

B1. Send OTP:

bash

agent-pay request-token <email>

Tell user: "I've sent a verification code to your email."

B2. Verify OTP: Ask user for the code they received.

bash

agent-pay verify-otp <email> <code>

Token is stored automatically by the CLI.

B3. Submit KYC application: Collect from user conversationally: first name, last name, phone, date of birth, address (line1, city, state, country, postal code). Then:

bash

agent-pay submit-application \
  --firstName "Alice" --lastName "Smith" \
  --email "alice@example.com" --phone "+14155551234" \
  --dob "1990-01-15" \
  --line1 "123 Main St" --city "San Francisco" \
  --state "CA" --country "US" --postalCode "94105"

If response contains

kycUrl

→ tell user: "Open this link to complete identity verification: <kycUrl>" If

kycAlreadyComplete

is true → skip to B4.

B4. Wait for KYC approval:

bash

agent-pay kyc-status

Poll this every 15–30 seconds. When status indicates approval, confirm to user: "You're all set."

B5. Verify:

bash

agent-pay agent

Both paths produce same result. Subsequent invocations skip onboarding entirely (Step 1 finds stored token).

所有命令由你运行。用户以对话形式提供信息——绝不向用户展示原始命令或JSON结果。

B1. 发送OTP：

bash

agent-pay request-token <email>

告知用户："我已向你的邮箱发送了验证码。"

B2. 验证OTP： 询问用户收到的验证码。

bash

agent-pay verify-otp <email> <code>

令牌会由CLI自动存储。

B3. 提交KYC申请： 以对话形式向用户收集：名、姓、电话、出生日期、地址（街道、城市、州/省、国家、邮政编码）。然后运行：

bash

agent-pay submit-application \
  --firstName "Alice" --lastName "Smith" \
  --email "alice@example.com" --phone "+14155551234" \
  --dob "1990-01-15" \
  --line1 "123 Main St" --city "San Francisco" \
  --state "CA" --country "US" --postalCode "94105"

若响应包含

kycUrl

→ 告知用户："打开此链接完成身份验证：<kycUrl>" 若

kycAlreadyComplete

为true → 跳过至B4。

B4. 等待KYC审核通过：

bash

agent-pay kyc-status

每隔15–30秒轮询一次。当状态显示审核通过时，告知用户："你已准备就绪。"

B5. 验证：

bash

agent-pay agent

两种路径最终结果一致。后续调用将完全跳过注册流程（步骤1会检测到存储的令牌）。

Card mode selection

卡片模式选择

After onboarding completes (first run only), ask the user which card mode they prefer:

How would you like cards handled for purchases? A) Single-use cards (recommended) — a new card is created for each purchase and destroyed afterward. More secure: each purchase is isolated, card details can't be reused. B) Reusable card — one card is created and reused across purchases. Frozen between uses, unfrozen when needed. Simpler to manage if you make frequent purchases.

Persist the choice to

~/.config/cypher-pay/card-mode

(value:

single-use

reusable

). Default to

single-use

if user doesn't pick. On subsequent runs, read from file — don't re-ask.

注册完成后（仅首次运行），询问用户偏好的卡片模式：

你希望如何处理购买所用的卡片？ A) 一次性卡片（推荐）——每次购买创建一张新卡片，购买完成后销毁。安全性更高：每次购买相互隔离，卡片信息无法重复使用。 B) 可重复使用卡片——创建一张卡片并在多次购买中重复使用。非使用状态下冻结，需要时解冻。若你频繁购买，管理更简单。

将选择结果保存至

~/.config/cypher-pay/card-mode

（值为：

single-use

或

reusable

）。若用户未选择，默认使用

single-use

。后续运行时读取该文件——无需再次询问。

Purchase flow

购买流程

This is the core loop. User wants to buy something → you handle payment.

1. Check balance:

bash

agent-pay balance

Returns

$X.XX

(e.g.

$12.50

). If balance < purchase amount:

bash

agent-pay fund <amountUsd>

Returns

{ "redirectUrl": "...", ... }

. Tell user: "Open this link to add funds: <redirectUrl>". Poll

agent-pay balance

until funds arrive.

这是核心流程。用户需要购买商品→由你处理付款。

1. 检查余额：

bash

agent-pay balance

$X.XX

（例如

$12.50

）。若余额小于购买金额：

bash

agent-pay fund <amountUsd>

{ "redirectUrl": "...", ... }

。告知用户："打开此链接充值：<redirectUrl>"。轮询

agent-pay balance

直至到账。

Mode A — Single-use cards

模式A — 一次性卡片

2. Create card sized to purchase:

bash

agent-pay create-card --tag "purchase-$(date +%s)" --purpose "Buy headphones" --limit 50

```
--tag
```
must be unique per agent. Use timestamp or order ID.
```
--limit
```
= max per-transaction in USD. Set to expected charge amount.

Output shows tag, masked card number, and expiry.

3. Get card details for checkout:

bash

agent-pay get-card --tag "purchase-$(date +%s)" --reveal

Returns full PAN/CVV/expiry. Use to fill checkout form silently.

To display the card to the user:

bash

agent-pay get-card --tag "purchase-tag" --pretty

Shows an ASCII art card with masked PAN (last 4 only) and expiry. Show this to the user after card creation.

If user explicitly asks for full PAN or CVV:

bash

agent-pay get-card --tag "purchase-tag" --reveal --pretty

Shows full PAN and CVV in the ASCII art card. Warn once: "Card details will be visible in your conversation history."

SECURITY: Default output is masked — last 4 + expiry only. Full PAN/CVV only with
--reveal
when user explicitly asks. Use
--reveal
without
--pretty
to fill checkout forms, then discard.

4. Handle 3DS if triggered:

bash

agent-pay 3ds-poll <cardId> --timeout 30000

Two possible outcomes:

```
{ "approved": true, "requestId": "..." }
```
— 3DS auto-approved. No user action needed.
```
{ "approved": false, "requiresUserOtp": true, "message": "..." }
```
— 3DS OTP was sent to the user's email by the card provider. Tell the user: "A verification code was sent to your email for this purchase. Please enter it on the merchant's checkout page." The agent cannot approve this automatically — the user must complete it themselves in the browser.

5. Wait for charge to land:

bash

agent-pay wait-for-txn <cardId> --timeout 30000

Polls until a transaction appears on the card. Do NOT cancel before this confirms — cancelling during an in-flight auth will decline the charge.

6. Cancel card:

bash

agent-pay cancel-card <cardId>

Destroys the card. Frees the slot (max 5 active cards). If

wait-for-txn

times out with

settled: false

, freeze instead of cancel and tell user the charge may still be processing.

2. 创建与购买金额匹配的卡片：

bash

agent-pay create-card --tag "purchase-$(date +%s)" --purpose "Buy headphones" --limit 50

```
--tag
```
必须每个agent唯一。可使用时间戳或订单ID。
```
--limit
```
= 每笔交易的最大美元金额。设置为预期扣款金额。

输出包含标签、掩码卡号和有效期。

3. 获取用于结账的卡片详情：

bash

agent-pay get-card --tag "purchase-$(date +%s)" --reveal

返回完整卡号（PAN）/CVV码/有效期。静默填写结账表单。

若要向用户展示卡片：

bash

agent-pay get-card --tag "purchase-tag" --pretty

展示带有掩码卡号（仅后4位）和有效期的ASCII艺术卡片。卡片创建后向用户展示此内容。

若用户明确要求查看完整卡号或CVV：

bash

agent-pay get-card --tag "purchase-tag" --reveal --pretty

在ASCII艺术卡片中展示完整卡号和CVV。需提醒一次："卡片详情将显示在你的对话历史中。"

安全规则：默认输出为掩码格式——仅显示后4位+有效期。仅当用户明确要求时，使用
--reveal
展示完整卡号/CVV。填写结账表单时，使用不带
--pretty
的
--reveal
，之后立即丢弃信息。

4. 处理触发的3DS验证：

bash

agent-pay 3ds-poll <cardId> --timeout 30000

两种可能结果：

```
{ "approved": true, "requestId": "..." }
```
— 3DS自动验证通过。无需用户操作。
```
{ "approved": false, "requiresUserOtp": true, "message": "..." }
```
— 发卡方向用户邮箱发送了3DS验证码。告知用户："本次购买的验证码已发送至你的邮箱，请在商家结账页面输入。"agent无法自动完成此验证——用户必须在浏览器中自行完成。

5. 等待扣款到账：

bash

agent-pay wait-for-txn <cardId> --timeout 30000

轮询直至卡片上出现交易记录。在此确认完成前请勿取消——在认证进行中取消会导致扣款失败。

6. 注销卡片：

bash

agent-pay cancel-card <cardId>

销毁卡片。释放卡片名额（最多5张活跃卡片）。若

wait-for-txn

超时且

settled: false

，则冻结卡片而非注销，并告知用户扣款可能仍在处理中。

Mode B — Reusable card

模式B — 可重复使用卡片

2. Get or create the reusable card: Check for an existing reusable card first:

bash

agent-pay list-cards

Look for a card with tag

reusable-default

(or whatever tag was used). If found and status is frozen/inactive → unfreeze it:

bash

agent-pay get-card --tag "reusable-default"

2. 获取或创建可重复使用卡片： 首先检查是否已有可重复使用卡片：

bash

agent-pay list-cards

查找带有

reusable-default

标签（或所用的其他标签）的卡片。若找到且状态为冻结/未激活 → 解冻：

bash

agent-pay get-card --tag "reusable-default"

If status is inactive:

若状态为未激活：

agent-pay unfreeze --tag "reusable-default"


If no reusable card exists, create one:
```bash
agent-pay create-card --tag "reusable-default" --purpose "Reusable purchase card" --limit 500

3–4. Get card and 3DS: Same as Mode A steps 3–4 (use

--tag "reusable-default"

5. Wait for charge to land:

bash

agent-pay wait-for-txn <cardId> --timeout 30000

6. Freeze card (do NOT cancel):

bash

agent-pay freeze <cardId>

Card stays in your active slots but is blocked from new charges until next purchase.

agent-pay unfreeze --tag "reusable-default"


若不存在可重复使用卡片，创建一张：
```bash
agent-pay create-card --tag "reusable-default" --purpose "Reusable purchase card" --limit 500

3–4. 获取卡片与3DS验证： 与模式A的步骤3–4相同（使用

--tag "reusable-default"

）。

5. 等待扣款到账：

bash

agent-pay wait-for-txn <cardId> --timeout 30000

6. 冻结卡片（请勿注销）：

bash

agent-pay freeze <cardId>

卡片保留在活跃名额中，但在下次购买前会被阻止新的扣款。

Both modes — Report to user

两种模式通用 — 向用户反馈

Confirm purchase succeeded. Show last-4 digits of card if useful (from

get-card

). Never reveal PAN/CVV/expiry/token.

确认购买成功。若有用可展示卡片后4位（来自

get-card

）。绝不泄露卡号（PAN）/CVV/有效期/令牌。

Operations reference

操作参考

All commands require

AGENT_PAY_TOKEN

in env unless noted. Output is human-readable by default; add

--json

to any command for machine-parseable JSON.

除非另有说明，所有命令均需环境变量中的

AGENT_PAY_TOKEN

。默认输出为人类可读格式；向任意命令添加

--json

可获取机器可解析的JSON格式。

Auth (no token required)

认证（无需令牌）

bash

agent-pay auth-status <email>          # Check enrollment + KYC status
agent-pay request-token <email>        # Send OTP to email
agent-pay verify-otp <email> <otp>     # Verify OTP → get bot token

bash

agent-pay auth-status <email>          # 检查注册状态+KYC完成情况
agent-pay request-token <email>        # 向邮箱发送OTP
agent-pay verify-otp <email> <otp>     # 验证OTP → 获取bot令牌

Account

账户

bash

agent-pay agent                        # Get agent account info
agent-pay kyc-status                   # Check KYC status
agent-pay balance                      # Balance in USD cents
agent-pay fund <amountUsd>             # Get funding redirect URL

bash

agent-pay agent                        # 获取agent账户信息
agent-pay kyc-status                   # 检查KYC状态
agent-pay balance                      # 账户余额（美元分）
agent-pay fund <amountUsd>             # 获取充值跳转URL

Cards

卡片

bash

agent-pay create-card --tag "x" [--purpose "..."] [--limit N] [--daily-limit N] [--monthly-limit N] [--reveal] [--pretty]
agent-pay get-card --tag "x"           # Card info (masked)
agent-pay get-card --tag "x" --reveal  # Full PAN/CVV/expiry — SENSITIVE
agent-pay get-card --tag "x" --pretty  # ASCII art card (masked)
agent-pay get-card --tag "x" --reveal --pretty  # ASCII art card (full PAN+CVV)
agent-pay freeze --tag "x"             # Deactivate card
agent-pay unfreeze --tag "x"           # Reactivate frozen card
agent-pay cancel-card --tag "x" [--reason "..."]  # Permanent, irreversible
agent-pay list-cards                   # Active cards (--all includes cancelled)

bash

agent-pay create-card --tag "x" [--purpose "..."] [--limit N] [--daily-limit N] [--monthly-limit N] [--reveal] [--pretty]
agent-pay get-card --tag "x"           # 卡片信息（掩码格式）
agent-pay get-card --tag "x" --reveal  # 完整卡号/CVV/有效期 — 敏感信息
agent-pay get-card --tag "x" --pretty  # ASCII艺术卡片（掩码格式）
agent-pay get-card --tag "x" --reveal --pretty  # ASCII艺术卡片（完整卡号+CVV）
agent-pay freeze --tag "x"             # 停用卡片
agent-pay unfreeze --tag "x"           # 重新激活冻结的卡片
agent-pay cancel-card --tag "x" [--reason "..."]  # 永久注销，不可恢复
agent-pay list-cards                   # 活跃卡片（--all包含已注销卡片）

Transactions & analytics

交易与分析

bash

agent-pay wait-for-txn <cardId> [--timeout 30000] [--interval 3000]  # Poll until charge lands
agent-pay transactions                 # Cross-card transaction history
agent-pay spend-stats [--start "2025-01-01"] [--end "2025-01-31"]

bash

agent-pay wait-for-txn <cardId> [--timeout 30000] [--interval 3000]  # 轮询直至扣款到账
agent-pay transactions                 # 跨卡片交易历史
agent-pay spend-stats [--start "2025-01-01"] [--end "2025-01-31"]

3DS

3DS验证

bash

agent-pay 3ds-poll <cardId> [--timeout 60000] [--interval 2000]

bash

agent-pay 3ds-poll <cardId> [--timeout 60000] [--interval 2000]

Machine-readable schema

机器可读Schema

bash

agent-pay --schema                     # Full JSON schema of all commands, flags, and outputs

bash

agent-pay --schema                     # 所有命令、参数和输出的完整JSON Schema

Default limits

默认限额

$500/transaction, $500/day, $5,000/month, max 5 cards per agent.
Per-card limits set at creation (capped by agent-level rules).

每笔交易500美元，每日500美元，每月5000美元，每个agent最多5张卡片。
单卡限额在创建时设置（受agent级规则限制）。

Error handling

错误处理

Exit code	Meaning
0	Success — JSON on stdout
1	Usage error (bad command, missing flag) — message on stderr
2	API error (auth failure, server error) — message on stderr

On exit code 2 with auth message → token may be stale. Delete

~/.config/cypher-pay/token

and re-auth.

退出码	含义
0	成功 — 标准输出为JSON
1	使用错误（命令错误、缺少参数） — 标准错误输出为提示信息
2	API错误（认证失败、服务器错误） — 标准错误输出为提示信息

若退出码为2且包含认证相关信息 → 令牌可能已过期。删除

~/.config/cypher-pay/token

并重新认证。

Security rules

安全规则

Card details display: Show last 4 of PAN and expiry by default. Expiry is low-risk — show freely. If user explicitly asks for full PAN or CVV, display them but warn once: "Heads up — card details will be visible in your conversation history." Never display full PAN or CVV unprompted — they are used silently for checkout.
Always dispose of cards after use — single-use mode: wait for charge, then cancel. Reusable mode: freeze. Either way, never leave a card active and idle.
Token prefix: must start with
```
agt_
```
Token storage: handled automatically by CLI. Never echo token values in conversation — the agent should not read, display, or manipulate token strings.
Rotate tokens before 90-day expiry via agentpay.cypherhq.io

卡片详情展示：默认仅展示卡号后4位和有效期。有效期风险较低——可自由展示。若用户明确要求查看完整卡号或CVV，展示时需提醒一次："注意——卡片详情将显示在你的对话历史中。"绝不主动展示完整卡号或CVV——这些信息仅用于静默填写结账表单。
使用后务必处理卡片 — 一次性模式：等待扣款到账后注销。可重复使用模式：冻结卡片。无论哪种模式，绝不让卡片处于活跃且闲置状态。
令牌前缀：必须以
```
agt_
```
开头
令牌存储：由CLI自动处理。绝不在对话中回显令牌值——agent不应读取、展示或操作令牌字符串。
令牌轮换：在90天有效期前通过agentpay.cypherhq.io轮换令牌

SDK Reference (for programmatic consumers)

SDK参考（面向编程使用者）

The CLI wraps the

@cypherhq/agent-pay

TypeScript SDK. Developers building custom integrations can use the SDK directly:

bash

npm install @cypherhq/agent-pay

typescript

import { createClient } from '@cypherhq/agent-pay';
const ap = createClient(); // reads AGENT_PAY_TOKEN from env

Key exports:

createClient

parseExpiry

AgentPayAuthError

AgentPayApiError

. Full SDK documentation: see the package README or

agent-pay --schema

for the complete API surface.

Environment variables:

```
AGENT_PAY_TOKEN
```
— bot token (required, must start with
```
agt_
```
)
```
AGENT_PAY_BASE_URL
```
— API base URL (optional, defaults to production)

CLI封装了

@cypherhq/agent-pay

TypeScript SDK。构建自定义集成的开发者可直接使用SDK：

bash

npm install @cypherhq/agent-pay

typescript

import { createClient } from '@cypherhq/agent-pay';
const ap = createClient(); // 从环境变量读取AGENT_PAY_TOKEN

核心导出：

createClient

、

parseExpiry

、

AgentPayAuthError

、

AgentPayApiError

。完整SDK文档：查看包的README或运行

agent-pay --schema

获取完整API接口。

环境变量：

```
AGENT_PAY_TOKEN
```
— bot令牌（必填，必须以
```
agt_
```
开头）
```
AGENT_PAY_BASE_URL
```
— API基础URL（可选，默认指向生产环境）