owlp-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OwlPay Wallet Pro CLI agent skill.

Installation & First Use

安装与首次使用

Prerequisites

前置要求

Node.js ≥ 20.12.0 and npm must be available. Verify with

node -v && npm -v

需安装Node.js ≥ 20.12.0及npm。可通过以下命令验证：

bash

node -v && npm -v

Install

安装

bash

owlp -V   # check if already installed

If the command is not found:

bash

npm install -g @owlpay/owlp-cli
owlp -V   # should print "OwlPay Wallet Pro CLI v0.5.13" or later

bash

owlp -V   # 检查是否已安装

若命令未找到：

bash

npm install -g @owlpay/owlp-cli
owlp -V   # 应显示 "OwlPay Wallet Pro CLI v0.5.13" 或更高版本

First-Run Checklist

首次运行检查清单

After installation, check readiness (capture the output — see § Output Discipline below):

bash

RESULT=$(owlp status --json 2>/dev/null) && echo "$RESULT" | jq '.data | {account: .account.ready, wallets: .wallets.ready, kyc: .kyc.ready}'

Then follow this decision tree:

Condition	Action	Agent-automatable?
`account.ready == false`	Two-step flow: (1) run `owlp onboard --json` to get a `loginUrl` , (2) display the URL and ask the user to open it, complete login, and read the passcode shown in the browser, (3) run `owlp onboard --json --auth-code <CODE>` to claim the passcode and continue.	Partially — agent runs the commands; human opens browser and reads the passcode
`wallets.ready == false`	Security-sensitive. Strongly recommend the user run `owlp wallet create` or `owlp wallet import` themselves in a TTY — mnemonic phrases must not pass through AI context or network. If the user explicitly consents to agent-driven setup, `owlp wallet create --json` is safer (addresses only returned; mnemonic shown locally). Never run `owlp wallet import --mnemonic ...` as an agent unless the user explicitly accepts the risk of the mnemonic entering AI context.	Requires explicit user consent
`kyc.ready == false`	Only needed for fiat withdrawal (off-ramp). Crypto transfers work without KYC. If needed: (1) run `owlp kyc submit --json` to get a `url` , (2) display the URL and ask the user to open it and complete identity verification, (3) when the user confirms they are done, run `owlp kyc wait --json` to poll until verified.	Partially — agent runs the commands; human completes verification in browser

After resolving all

false

states, re-run the status check above — all sections should show

ready: true

Important: For account setup, use the two-step

owlp onboard --json

flow above instead of

owlp auth login

. For KYC, use the two-step

kyc submit --json

kyc wait --json

flow instead of asking the user to run

owlp kyc submit

manually.

安装完成后，检查就绪状态（捕获输出——见下文「输出规范」章节）：

bash

RESULT=$(owlp status --json 2>/dev/null) && echo "$RESULT" | jq '.data | {account: .account.ready, wallets: .wallets.ready, kyc: .kyc.ready}'

随后按照以下决策树操作：

条件	操作	可由Agent自动完成？
`account.ready == false`	两步流程：(1) 运行 `owlp onboard --json` 获取 `loginUrl` ；(2) 展示该URL，要求用户打开并完成登录，读取浏览器中显示的验证码；(3) 运行 `owlp onboard --json --auth-code <CODE>` 提交验证码并继续。	部分可自动完成——Agent执行命令，用户需打开浏览器并读取验证码
`wallets.ready == false`	安全敏感操作。强烈建议用户在TTY环境中自行运行 `owlp wallet create` 或 `owlp wallet import` ——助记词绝不能传入AI上下文或通过网络传输。若用户明确同意由Agent驱动设置， `owlp wallet create --json` 相对更安全（仅返回地址；助记词仅在本地显示）。除非用户明确接受助记词进入AI上下文的风险，否则Agent绝不能执行 `owlp wallet import --mnemonic ...` 命令。	需用户明确同意
`kyc.ready == false`	仅法币提现（离场）时需要。加密货币转账无需KYC。若需完成：(1) 运行 `owlp kyc submit --json` 获取 `url` ；(2) 展示该URL，要求用户打开并完成身份验证；(3) 用户确认完成后，运行 `owlp kyc wait --json` 轮询直至验证通过。	部分可自动完成——Agent执行命令，用户需在浏览器中完成验证

解决所有

false

状态后，重新运行上述状态检查命令——所有部分应显示

ready: true

。

重要提示：账户设置请使用上述两步式

owlp onboard --json

流程，而非

owlp auth login

。KYC请使用两步式

kyc submit --json

kyc wait --json

流程，而非要求用户手动运行

owlp kyc submit

。

Environment

环境配置

Two environments: prod (default) and stage. Resolution precedence:

```
--stage
```
flag (per-command override)
```
~/.owlpay-wallet-pro/config.json
```
(persistent)
Default (
```
prod
```
)

bash

RESULT=$(owlp env get --json 2>/dev/null) && echo "$RESULT" | jq '.data | {env, source}'   # Show current env
owlp env set stage               # Persist env to config.json
owlp env set prod                # Switch back to prod
RESULT=$(owlp balance --stage --json 2>/dev/null) && echo "$RESULT" | jq -r '.data[] | "\(.symbol): \(.balance)"'   # One-off stage override

When running in

stage

, a 3-line banner is emitted to stderr on first output (suppressed for

env

subcommands and

--json

mode, which instead prepends a

{"type":"meta.env",...}

NDJSON line).

Global flags available on every command:

```
--json
```
— machine-readable output (always use when parsing programmatically)
```
--stage
```
— use stage environment instead of the persisted / default env
```
--wallet <name>
```
— use a specific wallet instead of the default
```
--debug
```
— verbose logging to stderr

支持两种环境：prod（默认）和stage。优先级顺序：

```
--stage
```
标志（单命令覆盖）
```
~/.owlpay-wallet-pro/config.json
```
（持久化配置）
默认值（
```
prod
```
）

bash

RESULT=$(owlp env get --json 2>/dev/null) && echo "$RESULT" | jq '.data | {env, source}'   # 查看当前环境
owlp env set stage               # 将环境持久化到config.json
owlp env set prod                # 切换回prod环境
RESULT=$(owlp balance --stage --json 2>/dev/null) && echo "$RESULT" | jq -r '.data[] | "\(.symbol): \(.balance)"'   # 单次临时切换到stage环境

在

stage

环境运行时，首次输出会向stderr发送3行横幅（

env

子命令和

--json

模式下会被抑制，改为前置

{"type":"meta.env",...}

格式的NDJSON行）。

所有命令均支持全局标志：

```
--json
```
—— 机器可读输出（程序化解析时必须使用）
```
--stage
```
—— 使用stage环境而非持久化/默认环境
```
--wallet <name>
```
—— 使用指定钱包而非默认钱包
```
--debug
```
—— 向stderr输出详细日志

Network Requirements

网络要求

Commands fall into two categories based on whether they need to reach the OwlPay API:

Offline (local file I/O only — work in any environment):

-V

env get

env set

auth logout

wallet create

wallet import

wallet list

wallet rename

wallet switch

wallet export-key

wallet reset

Online (hits OwlPay API — fails with

NETWORK_ERROR

/ exit code 4 when unreachable):

auth login

auth status

status

balance

send

tx list

tx detail

chains

tokens

countries

verify

kyc status

kyc submit

If your execution environment restricts outbound network access (sandboxed CI, air-gapped containers, etc.), only offline commands will succeed. Online commands that cannot resolve

wallet-pro.owlting.com

will throw

NetworkError

with exit code 4.

命令根据是否需要连接OwlPay API分为两类：

离线命令（仅本地文件I/O操作——可在任何环境下运行）：

-V

env get

env set

auth logout

wallet create

wallet import

wallet list

wallet rename

wallet switch

wallet export-key

wallet reset

在线命令（需调用OwlPay API——无法连接时会返回

NETWORK_ERROR

错误/退出码4）：

auth login

auth status

status

balance

send

tx list

tx detail

chains

tokens

countries

verify

kyc status

kyc submit

若执行环境限制出站网络访问（如沙箱CI、离线容器等），仅离线命令可成功执行。无法解析

wallet-pro.owlting.com

的在线命令会抛出

NetworkError

错误，退出码为4。

Output Discipline (MANDATORY)

输出规范（强制执行）

NEVER run
owlp ... --json
as a standalone Bash command. This is the single most common agent mistake with this CLI. When you run it bare, the full JSON envelope (often 30–80 lines) floods the conversation as unreadable noise.

Every
owlp ... --json
invocation MUST use this pattern:

bash

RESULT=$(owlp <command> --json 2>/dev/null) && echo "$RESULT" | jq '<filter>'

Examples of correct usage:

bash

undefined

绝不能直接运行
owlp ... --json
作为独立Bash命令。这是Agent使用该CLI时最常见的错误。直接运行会导致完整JSON包（通常30-80行）以不可读的形式充斥对话。

所有
owlp ... --json
调用必须遵循以下模式：

bash

RESULT=$(owlp <command> --json 2>/dev/null) && echo "$RESULT" | jq '<filter>'

正确用法示例：

bash

undefined

✓ Correct — only the parsed summary appears in the conversation

✓ 正确——仅解析后的摘要会出现在对话中

RESULT=$(owlp status --json 2>/dev/null) && echo "$RESULT" | jq '.data | {account: .account.ready, kyc: .kyc.ready, wallets: .wallets.ready}' RESULT=$(owlp balance --json 2>/dev/null) && echo "$RESULT" | jq -r '.data[] | "(.chain) (.symbol): (.balance)"' RESULT=$(owlp wallet list --json 2>/dev/null) && echo "$RESULT" | jq -r '.data.wallets[] | .name'


**All of these are WRONG — do not use:**

```bash


**以下用法均错误——请勿使用：**

```bash

✗ WRONG — bare command, JSON floods conversation

✗ 错误——直接运行命令，JSON内容充斥对话

owlp status --json owlp status --json 2>/dev/null owlp balance --json owlp balance --json 2>/dev/null owlp wallet list --json


Rules:
1. **Capture to a variable** — `RESULT=$(owlp ... --json 2>/dev/null)` (stderr silenced to suppress banners / debug noise).
2. **Parse with jq in the same Bash call** — `echo "$RESULT" | jq -r '...'` to extract only the fields you need.
3. **Present as natural language** — after parsing, summarize the result conversationally per § Agent Output Guidelines. Never paste raw JSON in your reply.

owlp status --json owlp status --json 2>/dev/null owlp balance --json owlp balance --json 2>/dev/null owlp wallet list --json


规则：
1. **捕获到变量中** —— `RESULT=$(owlp ... --json 2>/dev/null)`（抑制stderr输出以屏蔽横幅/调试信息）。
2. **在同一Bash调用中用jq解析** —— `echo "$RESULT" | jq -r '...'`仅提取所需字段。
3. **以自然语言呈现** —— 解析后，根据「Agent输出指南」以对话式语言总结结果。绝不要在回复中粘贴原始JSON。

JSON Response Envelope

JSON响应格式

All regular

--json

responses are wrapped:

json

{
  "success": true,
  "env": "prod",
  "data": { ... }
}

When parsing, access fields via

.data.<field>

bash

RESULT=$(owlp balance --json 2>/dev/null) && echo "$RESULT" | jq -r '.data[] | "\(.chain) \(.symbol): \(.balance)"'

Event-stream commands (

send

kyc submit

onboard

registration) emit NDJSON instead: one

{"type":"meta.env",...}

line, then one JSON line per event, then a

{"type":"complete","result":...}

line. Parse line-by-line, not as a single object. See

send.md

and

kyc.md

for details.

所有常规

--json

响应均包含以下外层结构：

json

{
  "success": true,
  "env": "prod",
  "data": { ... }
}

解析时通过

.data.<field>

访问字段：

bash

RESULT=$(owlp balance --json 2>/dev/null) && echo "$RESULT" | jq -r '.data[] | "\(.chain) \(.symbol): \(.balance)"'

事件流命令（

send

kyc submit

onboard

{"type":"meta.env",...}

，然后是每行一个事件的JSON，最后是一行

{"type":"complete","result":...}

。需逐行解析，而非作为单个对象。详情见

send.md

和

kyc.md

。

Authentication

身份验证

Must login before using commands that hit the API.

Agent mode (preferred): Use the two-step

owlp onboard --json

flow — see Installation & First Use → First-Run Checklist above. Do not call

owlp auth login

as an agent; it blocks on browser interaction.

Human mode:

bash

owlp auth login           # Interactive (opens browser — human only)
owlp auth logout          # Clear local session (keeps wallets)
RESULT=$(owlp auth status --json 2>/dev/null) && echo "$RESULT" | jq '.data | {loggedIn, email, workspace: .workspace.name}'

env get

chains

tokens

countries

verify

do not require auth.

使用需调用API的命令前必须登录。

Agent模式（推荐）：使用两步式

owlp onboard --json

流程——见上文「安装与首次使用 → 首次运行检查清单」。请勿以Agent身份调用

owlp auth login

；该命令会阻塞等待浏览器交互。

人工模式：

bash

owlp auth login           # 交互式（打开浏览器——仅适用于人工操作）
owlp auth logout          # 清除本地会话（保留钱包）
RESULT=$(owlp auth status --json 2>/dev/null) && echo "$RESULT" | jq '.data | {loggedIn, email, workspace: .workspace.name}'

env get

chains

tokens

countries

verify

命令无需身份验证。

Command Reference

命令参考

Read the relevant file before executing a command:

```
skills/commands/env.md
```
— Environment management (get/set, config.json)

skills/commands/auth.md

—

auth login

auth logout

auth status

```
skills/commands/onboard.md
```
— Guided setup (account + wallet + KYC)
```
skills/commands/wallet.md
```
— Wallet create, import/restore, list, rename, switch, export-key, reset
```
skills/commands/balance.md
```
— Balance queries across chains and tokens
```
skills/commands/tx.md
```
— Transaction history, filters, pagination, and detail
```
skills/commands/send.md
```
— Send tokens (preview + submit), NDJSON event stream
```
skills/commands/chains.md
```
— Supported chains and tokens
```
skills/commands/verify.md
```
— Address verification and chain auto-detection
```
skills/commands/countries.md
```
— Countries allowed for individual registration
```
skills/commands/kyc.md
```
— KYC status check and browser-assisted submission
```
skills/commands/status.md
```
— Unified readiness dashboard (account, KYC, wallets)

skills/commands/reset.md

—

owlp reset

(active env) /

owlp reset --all

(everything)

执行命令前请阅读对应文档：

```
skills/commands/env.md
```
—— 环境管理（获取/设置，config.json）

skills/commands/auth.md

——

auth login

auth logout

auth status

```
skills/commands/onboard.md
```
—— 引导式设置（账户 + 钱包 + KYC）
```
skills/commands/wallet.md
```
—— 钱包创建、导入/恢复、列表、重命名、切换、导出密钥、重置
```
skills/commands/balance.md
```
—— 跨链及多币种余额查询
```
skills/commands/tx.md
```
—— 交易历史、筛选、分页及详情
```
skills/commands/send.md
```
—— 代币转账（预览 + 提交），NDJSON事件流
```
skills/commands/chains.md
```
—— 支持的链及代币
```
skills/commands/verify.md
```
—— 地址验证及链自动检测
```
skills/commands/countries.md
```
—— 允许个人注册的国家/地区
```
skills/commands/kyc.md
```
—— KYC状态检查及浏览器辅助提交
```
skills/commands/status.md
```
—— 统一就绪仪表盘（账户、KYC、钱包）

skills/commands/reset.md

——

owlp reset

（当前环境）/

owlp reset --all

（全部重置）

Onboarding Flow

引导式注册流程

See Installation & First Use → First-Run Checklist above for the agent-friendly onboarding sequence.

For a guided flow that handles account creation, wallet setup, and optionally KYC in one command, use

owlp onboard

. In TTY mode it is fully interactive; in agent mode (

--json

) it supports a two-invocation passcode flow — see

skills/commands/onboard.md

for the agent workflow. KYC can be skipped with

--skip-kyc

or by declining the interactive prompt — it is only needed for fiat deposit/withdrawal.

Agent友好型注册流程见上文「安装与首次使用 → 首次运行检查清单」。

如需通过单个命令完成账户创建、钱包设置及可选KYC的引导式流程，可使用

owlp onboard

。在TTY模式下为全交互式；在Agent模式（

--json

）下支持两步验证码流程——详情见

skills/commands/onboard.md

中的Agent工作流。可通过

--skip-kyc

或拒绝交互式提示跳过KYC——仅法币存/提时需要KYC。

Common Agent Workflows

常见Agent工作流

Reminder: every
owlp ... --json
call below must follow § Output Discipline — capture to a variable, parse with jq, never expose raw JSON.

提醒：以下所有
owlp ... --json
调用必须遵循「输出规范」——捕获到变量中，用jq解析，绝不要暴露原始JSON。

Send Token

代币转账

bash

undefined

bash

undefined

1. Verify destination address (auto-detects chain)

1. 验证目标地址（自动检测链）

RESULT=$(owlp verify <address> --json 2>/dev/null) && echo "$RESULT" | jq '.data'

2. Confirm token is supported on that chain

2. 确认该链支持对应代币

RESULT=$(owlp tokens --chain <chain> --json 2>/dev/null) && echo "$RESULT" | jq -r '.data[] | .symbol'

3. Check you have sufficient balance

3. 检查余额是否充足

RESULT=$(owlp balance --chain <chain> --json 2>/dev/null) && echo "$RESULT" | jq -r '.data[] | "(.symbol): (.balance)"'

4. Preview the transfer and estimated fees (no --confirm)

4. 预览转账及预估手续费（不加--confirm）

RESULT=$(owlp send --to <address> --amount <n> --token <symbol> --chain <chain> --json 2>/dev/null) && echo "$RESULT" | jq '.data'

5. Execute the transfer

5. 执行转账

RESULT=$(owlp send --to <address> --amount <n> --token <symbol> --chain <chain> --confirm --json 2>/dev/null) && echo "$RESULT" | jq '.data'

6. Confirm transaction appears in history

6. 确认交易已出现在历史记录中

RESULT=$(owlp tx list --type send --json 2>/dev/null) && echo "$RESULT" | jq -r '.data[] | "(.id) (.type) (.amount) (.symbol)"'

7. Poll for final state using the transaction ID (envelope: data.type, data.detail.*)

7. 使用交易ID轮询最终状态（响应格式：data.type, data.detail.*）

RESULT=$(owlp tx detail <id> --json 2>/dev/null) && echo "$RESULT" | jq '.data.detail.state'

Poll until data.detail.state === "completed" && data.detail.order.blockchain_transaction.state === "confirmed"

轮询直至data.detail.state === "completed" && data.detail.order.blockchain_transaction.state === "confirmed"

(send envelope only — see skills/commands/tx.md for per-type field tables)

（仅转账响应格式——见skills/commands/tx.md中的各类型字段表）

undefined

undefined

Check KYC Before Off-Ramp

法币提现前检查KYC状态

bash

RESULT=$(owlp kyc status --json 2>/dev/null) && echo "$RESULT" | jq '{status: .data.status, verified: .data.verified}'

bash

RESULT=$(owlp kyc status --json 2>/dev/null) && echo "$RESULT" | jq '{status: .data.status, verified: .data.verified}'

status == "verified" && verified == true — ready for fiat withdrawal

status == "verified" && verified == true —— 可进行法币提现

any other status — off-ramp not available

其他任何状态 —— 无法进行法币提现

undefined

undefined

Agent Output Guidelines

Agent输出指南

When presenting command results to the user, follow these principles:

Natural language first. Summarize results conversationally, as if reporting to a colleague. Do not paste raw JSON output. Use lists or tables only when data volume makes prose hard to scan — the choice is yours.
Event streams: report the outcome, not the journey. For commands that emit NDJSON event streams (
```
send
```
,
```
onboard
```
,
```
kyc submit
```
), wait for the final result and summarize it once. Do not narrate each intermediate event.
Errors: include the code and a next step. When a command fails, mention the error code (e.g.
```
INSUFFICIENT_GAS
```
) and suggest what the user can do about it. Each command's documentation describes its common errors.
Sensitive operations: warn before executing. Before running
```
wallet create
```
,
```
wallet import
```
, or
```
wallet export-key
```
, explain the risks (mnemonic loss, private key exposure) and ask the user to confirm. Do not execute the command first and warn after.
Respect the command's
## Agent Response
section. Individual command docs may include an
```
## Agent Response
```
section with specific guidance on what to highlight and how to present results. Follow those instructions; they override these general principles where they differ.

向用户展示命令结果时，请遵循以下原则：

优先使用自然语言。以对话式语言总结结果，如同向同事汇报。请勿粘贴原始JSON输出。仅当数据量过大导致 prose 难以阅读时才使用列表或表格——可自行判断。
事件流：报告最终结果，而非过程。对于输出NDJSON事件流的命令（
```
send
```
,
```
onboard
```
,
```
kyc submit
```
），等待最终结果后一次性总结。无需叙述每个中间事件。
错误：包含错误码及下一步建议。命令失败时，提及错误码（如
```
INSUFFICIENT_GAS
```
）并建议用户可采取的措施。每个命令的文档均描述了常见错误。
敏感操作：执行前警告。执行
```
wallet create
```
,
```
wallet import
```
或
```
wallet export-key
```
前，解释风险（助记词丢失、私钥暴露）并请求用户确认。请勿先执行命令再警告。
遵循命令的「Agent响应」章节。单个命令文档可能包含「Agent响应」章节，提供关于需突出显示内容及呈现方式的具体指导。请遵循这些说明；若与通用原则冲突，以章节说明为准。

Data Storage

数据存储

Local files under

~/.owlpay-wallet-pro/

```
config.json
```
— persisted env (
```
{"env":"prod"|"stage"}
```
), root level, shared across envs
```
prod/auth.json
```
,
```
stage/auth.json
```
— session tokens + workspace (env-scoped)
```
prod/wallets.json
```
,
```
stage/wallets.json
```
— addresses + mnemonics (env-scoped)

Private keys never leave the client. The API only sees signed transactions.

本地文件存储于

~/.owlpay-wallet-pro/

目录下：

```
config.json
```
—— 持久化环境配置（
```
{"env":"prod"|"stage"}
```
），根目录，跨环境共享
```
prod/auth.json
```
,
```
stage/auth.json
```
—— 会话令牌 + 工作区（按环境划分）
```
prod/wallets.json
```
,
```
stage/wallets.json
```
—— 地址 + 助记词（按环境划分）

私钥绝不会离开客户端。API仅能看到签名后的交易。