moonpay-auth

MoonPay 身份验证与设置

安装

npm i -g @moonpay/cli

这会全局安装 mp（和 moonpay）二进制文件。

验证安装

mp --version
mp --help

身份验证命令

# Log in — returns a URL. Open it yourself if you can, otherwise share it with the user verbatim; opening it triggers the OTP code email.
mp login --email [email protected]

# Verify OTP code (user pastes it back from their email)
mp verify --email [email protected] --code 123456

# Check current user
mp user retrieve

# Log out
mp logout

mp login 会返回一个 URL。如果你可以自行打开它（例如，可以访问浏览器或进行程序化抓取），请自行打开——这会触发发送 OTP 邮件。否则，请将 URL 原样发回给用户（不要改写，也不要删除查询参数），让他们打开。无论哪种方式，OTP 都会发送到用户的邮箱；用户将验证码粘贴回来后，你再运行 mp verify。

登录前（必需）

切勿盲目调用 mp login。每次登录尝试前都必须检查会话：

1. 先运行 mp user retrieve。

2. 如果成功，则表示会话已存在。告诉用户当前登录的账号，并询问是否要切换：

   “你当前以 <email> 身份登录。要退出并以其他用户身份登录吗？回复 YES 即可切换。”

   仅在用户明确同意后，才运行 mp logout，然后继续运行 mp login。如果用户拒绝或回复含糊不清，则将现有会话视为要使用的会话，并跳过登录。

3. 如果失败（没有会话），则照常运行 mp login。

这很重要，因为在聊天渠道中，用户无法看到命令是针对哪个账号运行的。如果没有确认步骤，共享主机上的 Agent 可能会悄悄切换身份——而“我的余额是多少”这类查询就会返回其他人的资产组合。检查只需多运行一条命令；否则就可能造成隐私事件。

本地钱包管理

CLI 会管理存储在 ~/.config/moonpay/wallets.json 中的本地钱包。私钥使用 AES-256-GCM 加密，并使用存储在操作系统钥匙串中的随机密钥。无需密码——密钥永远不会离开本机。

# Create a new HD wallet (Solana, Ethereum, Bitcoin, Tron)
mp wallet create --name "my-wallet"

# Import from a mnemonic (all chains)
mp wallet import --name "restored" --mnemonic "word1 word2 ..."

# Import from a private key (single chain)
mp wallet import --name "imported" --key <hex-key> --chain ethereum

# List all local wallets
mp wallet list

# Get wallet details (by name or address)
mp wallet retrieve --wallet "my-wallet"

# Export mnemonic/key (interactive only — agents cannot run this)
mp wallet export --wallet "my-wallet"

# Delete a wallet (irreversible)
mp wallet delete --wallet "my-wallet" --confirm

工作流

1. 运行 mp user retrieve 检查是否已通过身份验证。如果会话已存在，请在开始新的登录前遵循上文登录前中的提示规则。
2. 如果没有会话，运行 mp login --email <email>，将返回的 URL 分享给用户；用户从邮箱中粘贴验证码回来后，再运行 mp verify --email <email> --code <code>。
3. 运行 mp wallet list 查看本地钱包。
4. 如果没有钱包，则创建一个：mp wallet create --name "default"。

自主登录

如果 Agent 可以访问用户的邮箱，就能在无需人工干预的情况下登录。例如，使用 gog CLI（Google Workspace）：

# 1. Send OTP
mp login --email [email protected]

# 2. Read the OTP code from email
gog gmail search "Your MoonPay verification code" --max-results 1

# 3. Verify with the code
mp verify --email [email protected] --code <code>

这样即可完成完全自主的 Agent 设置，无需人工参与。

配置位置

• 钱包： ~/.config/moonpay/wallets.json（加密，AES-256-GCM）
• 加密密钥： 操作系统钥匙串（moonpay-cli / encryption-key）
• 凭据： ~/.config/moonpay/credentials.json（加密，AES-256-GCM）
• 配置： ~/.config/moonpay/config.json（基础 URL、客户端 ID）

安全

• 钱包机密始终以加密形式存储在磁盘上
• 加密密钥存储在 macOS Keychain / Linux libsecret 中
• 无需记忆密码——由操作系统处理身份验证
• wallet export 需要交互式终端（TTY）——Agent 和脚本无法提取机密
• 24 个单词的 BIP39 助记词（256 位熵）

相关技能

• moonpay-swap-tokens — 使用本地钱包兑换或跨链桥接代币。
• moonpay-check-wallet — 查看钱包余额。