agentic-payments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agentic Payments

智能代理支付

Pay HTTP 402-protected resources on the user's behalf. InFlow speaks two payment protocols - MPP and x402 - but the flow is the same for both: shared setup (install, run, authenticate), then a router that picks the protocol from the seller's 402 header, then one Paying a 402 resource section that covers both. A per-protocol delta table at the top of that section lists the handful of real differences (header name, credential name, filters, error codes); read your row, then follow the shared steps.

代表用户支付受HTTP 402保护的资源。InFlow支持两种支付协议——MPP和x402——但两者的流程是相同的：共享设置（安装、运行、身份验证），然后是一个路由器，从卖家的402头中选择协议，接着是一个涵盖两者的支付402资源部分。该部分顶部的每个协议的差异表列出了少数实际差异（头名称、凭证名称、过滤器、错误代码）；查看对应行，然后遵循共享步骤。

Installing

安装

Install the signed native CLI through one of these channels:

Channel	Command
macOS Homebrew	`brew tap inflowpayai/tap && brew install --cask inflow`
macOS/Linux hosted installer	`curl -fsSL https://inflowcli.ai/install.sh \| bash`
Windows PowerShell installer	`irm https://inflowcli.ai/install.ps1 \| iex`
Cross-platform shell compatibility	`curl -fsSL https://inflowcli.ai/cli \| bash`

Current install instructions live at https://inflowcli.ai/.

通过以下渠道之一安装签名的原生CLI：

渠道	命令
macOS Homebrew	`brew tap inflowpayai/tap && brew install --cask inflow`
macOS/Linux 托管安装程序	`curl -fsSL https://inflowcli.ai/install.sh \| bash`
Windows PowerShell 安装程序	`irm https://inflowcli.ai/install.ps1 \| iex`
跨平台 shell 兼容性	`curl -fsSL https://inflowcli.ai/cli \| bash`

当前安装说明位于 https://inflowcli.ai/。

Running

运行

InFlow runs as a standalone CLI or an MCP server.

MCP: add an

inflow

server to your MCP client config that runs

inflow --mcp

MCP mode exposes every CLI command as a tool. Call

tools/list

on the MCP server for the authoritative inventory; arguments mirror the CLI flags one-to-one.

InFlow可以作为独立CLI或MCP服务器运行。

MCP：在你的MCP客户端配置中添加一个

inflow

服务器，运行

inflow --mcp

。

MCP模式将每个CLI命令作为工具暴露。调用MCP服务器上的

tools/list

获取权威的工具清单；参数与CLI标志一一对应。

Common commands / options

常用命令/选项

The CLI is the source of truth for exact flags, enums, and output shapes - run

inflow <command> --schema

for one command, or

inflow --llms-full

for everything. This playbook covers when and why, not exhaustive parameter lists; when you need a precise flag name, value set, or response shape, query the CLI rather than guessing.

```
inflow --llms
```
(or
```
--llms-full
```
for parameter detail) - discover all commands.
```
inflow <command> --schema
```
for a single command's JSON Schema.
```
inflow --skill
```
- print this playbook (no frontmatter) to stdout. Use it to paste into the system-prompt field of an MCP host that doesn't natively load skills:
```
inflow --skill | pbcopy
```
.
Default output is
```
toon
```
. Override with
```
--format <fmt>
```
; for programmatic parsing prefer
```
json
```
(single document) or
```
jsonl
```
(line-delimited).
Multi-step flows return
```
_next.command
```
- run it to continue.
```
--auth <path>
```
identifies a legacy plaintext credential file for deletion; it is not a credential backend.
```
--api-key <key>
```
or
```
INFLOW_API_KEY=<key>
```
is an alternative to device-flow auth.

CLI是精确标志、枚举和输出格式的权威来源——运行

inflow <command> --schema

查看单个命令的信息，或运行

inflow --llms-full

查看所有信息。本指南涵盖何时使用及原因，而非详尽的参数列表；当你需要精确的标志名称、值集或响应格式时，请查询CLI而非猜测。

```
inflow --llms
```
（或
```
--llms-full
```
获取参数详情）——发现所有命令。
```
inflow <command> --schema
```
获取单个命令的JSON Schema。
```
inflow --skill
```
——将本指南（无前缀内容）打印到标准输出。可用于粘贴到不原生加载技能的MCP主机的系统提示字段：
```
inflow --skill | pbcopy
```
。
默认输出格式为
```
toon
```
。可使用
```
--format <fmt>
```
覆盖；对于程序化解析，首选
```
json
```
（单文档）或
```
jsonl
```
（行分隔）。
多步骤流程返回
```
_next.command
```
——运行该命令继续流程。
```
--auth <path>
```
用于标识要删除的遗留明文凭证文件；它不是凭证后端。
```
--api-key <key>
```
或
```
INFLOW_API_KEY=<key>
```
是设备流身份验证的替代方案。

Authenticate

身份验证

Authentication is shared by both protocols - do it once, before either payment flow. Don't start a payment until the user is authenticated.

Credential-bearing commands require the encrypted local vault. If the CLI reports that the vault is uninitialized or locked, tell the user to run

inflow vault unlock

themselves in a terminal, then retry. Never ask for or accept the vault PIN or passphrase through chat, an MCP tool, a command-line flag, or an environment variable.

Check the current state first - the user may already be logged in:

bash

inflow auth status

A successful

auth status

returns

authenticated: true

plus

auth_method

(

device_token

api_key

), a truncated

access_token

preview (never the full token),

credentials_path

connection

, and possibly an

update

field. Run the command to see the full shape.

If the response includes an

update

field, a newer version of

inflow

is published.

Surface and defer. Tell the user a newer version is available and share the install instructions at https://inflowcli.ai/. Then proceed with the current version. Only block on the upgrade if a subsequent command fails with

VERSION_UNSUPPORTED

(or an HTTP 426 from the API), at which point the upgrade is mandatory and you should not retry until it lands.

authenticated

false

, start the device flow:

bash

inflow auth login --client-name "<your-agent-name>"

Replace

<your-agent-name>

with the name of your agent or application (for example

"Personal Assistant"

"Shopping Bot"

). The device-authorization page in the user's browser displays this name when they approve the connection. Use a clear, unique, identifiable name.

The response includes a

verification_url

(present this to the user), a

phrase

, and a

_next.command

. Run that command immediately to poll until authenticated. Do not wait for the user to respond before starting the poll.

If your environment can't relay the verification phrase to the user while a separate polling command blocks I/O, use inline polling instead:

bash

inflow auth login --client-name "<name>" --interval 5 --timeout 300

API key alternative: if the user provides an API key, set

INFLOW_API_KEY=<key>

in the environment (or pass

--api-key <key>

to any command) instead of running

auth login

. The API key takes precedence over a saved device token.

auth status

returns

VAULT_LOCKED

, authentication status is unavailable rather than unauthenticated. Tell the user to run

inflow vault unlock

themselves in a terminal, then retry

auth status

两种协议共享身份验证流程——只需执行一次，在任一支付流程之前。在用户完成身份验证前不要启动支付。

需要凭证的命令需要加密的本地密钥库。如果CLI报告密钥库未初始化或已锁定，请告知用户在终端中自行运行

inflow vault unlock

，然后重试。切勿通过聊天、MCP工具、命令行标志或环境变量询问或接受密钥库PIN或密码。

首先检查当前状态——用户可能已登录：

bash

inflow auth status

成功的

auth status

authenticated: true

以及

auth_method

（

device_token

或

api_key

）、截断的

access_token

预览（永远不会是完整令牌）、

credentials_path

、

connection

，可能还有

update

字段。运行该命令查看完整格式。

如果响应包含

update

字段，则表示有更新版本的

inflow

已发布。

**告知用户并继续。**告诉用户有新版本可用，并分享https://inflowcli.ai/上的安装说明。然后**继续使用当前版本**。只有当后续命令因`VERSION_UNSUPPORTED`（或API返回HTTP 426）失败时，才需要强制升级，此时在升级完成前不应重试。

如果

authenticated

为

false

，启动设备流：

bash

inflow auth login --client-name "<your-agent-name>"

将

<your-agent-name>

替换为你的代理或应用程序名称（例如

"Personal Assistant"

、

"Shopping Bot"

）。用户浏览器中的设备授权页面会在他们批准连接时显示此名称。请使用清晰、唯一、可识别的名称。

响应包含

verification_url

（展示给用户）、

phrase

和

_next.command

。立即运行该命令进行轮询，直到完成身份验证。不要等待用户响应再启动轮询。

如果你的环境无法在单独的轮询命令阻塞I/O时向用户传递验证短语，请使用内联轮询：

bash

inflow auth login --client-name "<name>" --interval 5 --timeout 300

API密钥替代方案：如果用户提供API密钥，在环境中设置

INFLOW_API_KEY=<key>

（或向任何命令传递

--api-key <key>

），而非运行

auth login

。API密钥优先于已保存的设备令牌。

如果

auth status

VAULT_LOCKED

，则身份验证状态不可用，而非未验证。告知用户在终端中自行运行

inflow vault unlock

，然后重试

auth status

。

Which protocol? - start here

使用哪种协议？——从此开始

Before paying, decide which protocol the resource uses. You do not choose it - the seller's 402 challenge decides. Run one read-only, no-auth command and let it detect both:

bash

inflow inspect <url>

inflow inspect

probes the URL once and decodes both MPP and x402 challenges from the same 402. Read its

detected

array to pick the pay rail:

detected

includes

aep

and also reveals a payment protocol, continue with the matching

mpp pay

x402 pay

; the payment commands perform AEP authentication before creating the payment transaction. If

aep.blocked

is true, AEP authentication is required before payment terms can be inspected; use

inflow aep fetch <url>

for access-only requests or ask whether to authenticate before attempting payment.

`detected`	Pay with
`["mpp"]`	`inflow mpp pay <url>`
`["x402"]`	`inflow x402 pay <url>`
`["mpp", "x402"]`	`inflow mpp pay <url>` - MPP wins when both are present
`[]` (seller still returned 402)	Not InFlow-payable on this account. Stop and tell the user; check `warnings` for why.

inspect

returns

outcome: "no-payment-required"

, the URL isn't paywalled - there's nothing to pay.

支付前，确定资源使用的协议。**你无需选择——卖家的402质询会决定。**运行一个只读、无需身份验证的命令，让它自动检测：

bash

inflow inspect <url>

inflow inspect

会一次探测URL，并从同一个402头解码MPP和x402质询。查看其

detected

数组以选择支付渠道：

如果

detected

包含

aep

且显示支付协议，请继续使用匹配的

mpp pay

或

x402 pay

；支付命令会在创建支付交易前执行AEP身份验证。如果

aep.blocked

为true，则在检查支付条款前需要AEP身份验证；对于仅访问请求，使用

inflow aep fetch <url>

，或询问用户是否要在尝试支付前进行身份验证。

`detected`	使用以下命令支付
`["mpp"]`	`inflow mpp pay <url>`
`["x402"]`	`inflow x402 pay <url>`
`["mpp", "x402"]`	`inflow mpp pay <url>` ——当两者都存在时，MPP优先
`[]` （卖家仍返回402）	此账户无法通过InFlow支付。停止操作并告知用户；查看 `warnings` 了解原因。

如果

inspect

outcome: "no-payment-required"

，则该URL没有付费墙——无需支付。

Paying a 402 resource

支付402资源

One flow for both protocols. Prerequisite: you are authenticated (see Authenticate). First find your protocol's row in the Protocol deltas table below - it names the 402 header that selected it, the matching model, the filter flags, and the Fetch command that completes the seller request. Everything else in this section applies to both protocols.

Sequencing. Run pre-flight before pay -

pay

fails or double-charges if the pre-flight checks didn't clear.

inspect

and

decode

are read-only and need no auth, so they may run before you authenticate if useful (e.g. sizing up a paywall first). If the seller requires AEP before payment,

pay

authenticates with the Service first, then creates the payment only after the legitimate 402 is available. Do not run a separate

aep grant

just to continue payment.

两种协议共用一个流程。前提：已完成身份验证（参见身份验证）。首先查看下方协议差异表中对应协议的行——它会指明选择该协议的402头、匹配模型、过滤器标志以及完成卖家请求的Fetch命令。本节其余内容适用于两种协议。

流程顺序。在支付前运行预检——如果预检未通过，

pay

会失败或重复收费。

inspect

和

decode

是只读的，无需身份验证，因此如果有用（例如先评估付费墙），可以在身份验证前运行。如果卖家要求在支付前进行AEP，

pay

会先与服务进行身份验证，然后仅在合法的402可用时创建支付交易。不要单独运行

aep grant

来继续支付流程。

Protocol deltas

协议差异

Aspect	MPP	x402
Selected when the 402 carries	`WWW-Authenticate: Payment`	`PAYMENT-REQUIRED` (and no `WWW-Authenticate: Payment` )
Command prefix	`inflow mpp …`	`inflow x402 …`
Matching model	The seller's challenge pins the rail - the buyer does not choose scheme/network/asset	Pay where the x402 `accepts` ∩ `supported.kinds` is non-empty
Filter flags	`--payment-method` , `--intent` , `--currency` , `--rail` , `--instrument-id`	`--scheme` , `--network` , `--asset` , `--asset-name`
Resource completion command	`inflow mpp fetch <transaction_id> <url>`	`inflow x402 fetch <transaction_id> <url>`
Replay header used by Fetch	`Authorization: Payment <credential>` plus a non-colliding AEP credential when required	`PAYMENT-SIGNATURE: <encoded_payload>` plus a non-colliding AEP credential when required
Diagnostic credential file flag	`--credential-file <path>` on `status`	`--payload-file <path>` on `status`
Idempotency	-	`--payment-id` (see Step 2)
Cancel uses	`approval_id`	`approval_id`
Protocol-specific error codes	`PAYMENT_FAILED` , `PAYMENT_EXPIRED` , `PAYMENT_NOT_ACCEPTED`	`APPROVAL_TIMEOUT` , `APPROVAL_FAILED` , `APPROVAL_CANCELLED`

Throughout this section

<mpp|x402>

means "use your protocol's prefix." For the exact parameters and output shape of any command below, run

inflow <command> --schema

方面	MPP	x402
当402头包含以下内容时选择	`WWW-Authenticate: Payment`	`PAYMENT-REQUIRED` （且无 `WWW-Authenticate: Payment` ）
命令前缀	`inflow mpp …`	`inflow x402 …`
匹配模型	卖家的质询固定支付渠道——买家无法选择方案/网络/资产	在x402的 `accepts` ∩ `supported.kinds` 非空的渠道支付
过滤器标志	`--payment-method` , `--intent` , `--currency` , `--rail` , `--instrument-id`	`--scheme` , `--network` , `--asset` , `--asset-name`
资源完成命令	`inflow mpp fetch <transaction_id> <url>`	`inflow x402 fetch <transaction_id> <url>`
Fetch使用的重放头	`Authorization: Payment <credential>` ，必要时加上非冲突的AEP凭证	`PAYMENT-SIGNATURE: <encoded_payload>` ，必要时加上非冲突的AEP凭证
诊断凭证文件标志	`status` 命令使用 `--credential-file <path>`	`status` 命令使用 `--payload-file <path>`
幂等性	-	`--payment-id` （参见步骤2）
取消使用	`approval_id`	`approval_id`
协议特定错误代码	`PAYMENT_FAILED` , `PAYMENT_EXPIRED` , `PAYMENT_NOT_ACCEPTED`	`APPROVAL_TIMEOUT` , `APPROVAL_FAILED` , `APPROVAL_CANCELLED`

本节中

<mpp|x402>

表示“使用对应协议的前缀”。如需以下任何命令的确切参数和输出格式，请运行

inflow <command> --schema

。

Step 1: Pre-flight evaluation

步骤1：预检评估

bash

undefined

bash

undefined

1. Parse what the seller will accept - read-only, no auth (both protocols in one probe)

1. 解析卖家接受的支付方式——只读，无需身份验证（一次探测两种协议）

inflow inspect <url>

(Already have the raw 402 header from a prior response? Decode it directly instead of re-probing:)

（已有之前响应中的原始402头？直接解码它，无需重新探测：）

inflow <mpp|x402> decode '<402 header value>'

2. List what the buyer's account can pay with (use the protocol from

detected

)

2. 列出买家账户可使用的支付方式（使用

detected

中的协议）

inflow <mpp|x402> supported

3. Check balances for the candidate currency/asset(s)

3. 检查候选货币/资产的余额

inflow balances list


`inflow inspect` returns what the seller accepts under its `mpp` and `x402` keys - the price is each challenge's `amount` field (raw atomic units for x402; the asset is the on-chain contract address, not a symbol). `decode` parses a single raw header you already hold (and also accepts a base64url credential / receipt). `supported` returns what the account can pay with; `balances list` returns `available` per currency. Run the commands to see the exact shapes.

Decide whether you can pay (apply your protocol's matching model from the delta table):

| Condition | Meaning | Action |
| --- | --- | --- |
| No payable match between the seller and the buyer's `supported` methods | No payable rail | Stop → `NO_INFLOW_MATCH`. Tell the user the seller's rails aren't supported by their account. |
| A match exists, but `balances.available < amount` for every match | Right rail, not enough funds | Stop → run `inflow deposit-addresses list`, surface the address(es) in full, ask the user to fund a matching network. |
| A match exists **and** ≥1 match has `balances.available ≥ amount` | Payable | Proceed to Step 2. |

**Optional filters** narrow *which* offer to fulfil - optional, AND-combined, applied on `pay`, and an empty result fails with `NO_FILTERED_MATCH` (it does not fall through to a default order). One non-obvious case: MPP's `--instrument-id` picks *how* to fund (an instrument-rail / fiat challenge), not which challenge. For the exact filter flags and accepted values per protocol, run `inflow <mpp|x402> pay --schema`.

**Decimal precision.** `balances.available` and the challenge/`amount` value are decimal strings preserving BigDecimal precision. **Never parse them to a JS `Number`** - that drops precision. Compare as strings, or use a `BigInt` / `decimal.js`-style library.

inflow balances list


`inflow inspect`在其`mpp`和`x402`键下返回卖家接受的内容——价格是每个质询的`amount`字段（x402为原始原子单位；资产是链上合约地址，而非符号）。`decode`解析你已持有的单个原始头（也接受base64url凭证/收据）。`supported`返回账户可使用的支付方式；`balances list`返回每种货币的`available`余额。运行命令查看精确格式。

根据协议差异表中的匹配模型，判断是否可以支付：

| 条件 | 含义 | 操作 |
| --- | --- | --- |
| 卖家接受的方式与买家`supported`方式之间无匹配项 | 无可用支付渠道 | 停止 → `NO_INFLOW_MATCH`。告知用户卖家的支付渠道不受其账户支持。 |
| 存在匹配项，但所有匹配项的`balances.available < amount` | 渠道正确，但资金不足 | 停止 → 运行`inflow deposit-addresses list`，完整显示地址，要求用户向匹配的网络充值。 |
| 存在匹配项**且**至少一个匹配项的`balances.available ≥ amount` | 可支付 | 继续步骤2。 |

**可选过滤器**用于缩小要执行的报价范围——可选，组合使用，在`pay`命令上应用，若结果为空则失败并返回`NO_FILTERED_MATCH`（不会回退到默认顺序）。一个不明显的情况：MPP的`--instrument-id`选择**资金来源**（工具渠道/法定货币质询），而非选择哪个质询。如需每个协议的确切过滤器标志和接受的值，请运行`inflow <mpp|x402> pay --schema`。

**小数精度**。`balances.available`和质询/`amount`值是保留BigDecimal精度的十进制字符串。**永远不要将它们解析为JS `Number`**——这会丢失精度。作为字符串比较，或使用`BigInt` / `decimal.js`类库。

Step 2: Pay

步骤2：支付

Before initiating the call, summarize the intent to the user in chat: amount, currency, resource URL, and the method/rail (MPP) or scheme/network (x402). The user verifies the canonical details on the approval screen; the chat summary is what they read first. Example:

"I'm about to pay 0.10 USDC to api.foo.dev for /dataset.csv. Requesting approval next."

Fast path (recommended). When the agent can block until the payment finishes, set

--interval N

and let the CLI run the whole flow in one call - probe, decode, prepare, await approval, replay against the seller, return the body:

bash

inflow <mpp|x402> pay <url> --interval 5 --max-attempts 180

The result includes

outcome

transaction_id

response_status

settled

, the seller body inline (or

output_saved_to

--output-file

is set), and the now-consumed credential (

credential

for MPP,

encoded_payload

for x402). On the fast path the CLI has already replayed that credential to fetch the body - it appears in the result for reference only; do not replay it yourself. To surface

approval_url

before the call returns, add

--format jsonl

- frames stream line-by-line. With the default

json

(or

toon

), the agent only sees the final buffered result.

outcome
values. A completed

pay

returns one of three terminal outcomes - branch on it, don't assume

paid

`outcome`	Meaning	What to do
`paid`	Settled and the seller returned 2xx	Deliver the body to the user
`no-payment-required`	The resource wasn't paywalled, or was already paid	Tell the user nothing was charged; return the body
`replay-rejected`	Payment was approved (funds in transit) but the seller replied non-2xx on the replay	Do NOT report success. Tell the user the seller's response failed; because the payment didn't complete, the in-transit funds are reverted to their InFlow balance. Offer to retry

Two-step path. Use this when the agent's host can't block I/O long enough for the user to approve (chat UIs that yield between turns). Drop

--interval

; the first call returns

transaction_id

approval_id

approval_url

+ a

_next

Fetch command/tool input. Fetch owns polling and seller replay.

bash

inflow <mpp|x402> pay <url>

发起调用前，在聊天中向用户总结支付意图：金额、货币、资源URL以及支付方式/渠道（MPP）或方案/网络（x402）。用户会在批准屏幕上验证标准详情；聊天摘要他们会首先看到。示例：

"我即将向api.foo.dev支付0.10 USDC以获取/dataset.csv。接下来请求批准。"

快速路径（推荐）。当代理可以阻塞直到支付完成时，设置

--interval N

，让CLI在一次调用中运行整个流程——探测、解码、准备、等待批准、向卖家重放、返回内容：

bash

inflow <mpp|x402> pay <url> --interval 5 --max-attempts 180

结果包含

outcome

、

transaction_id

、

response_status

、

settled

、内联的卖家内容（如果设置了

--output-file

则为

output_saved_to

）以及已消耗的凭证（MPP为

credential

，x402为

encoded_payload

）。在快速路径下，CLI已重放该凭证以获取内容——结果中仅作为参考显示；请勿自行重放。要在调用返回前显示

approval_url

，添加

--format jsonl

——帧会逐行流式传输。使用默认的

json

（或

toon

）时，代理仅会看到最终的缓冲结果。

outcome
值。完成的

pay

返回三种终端结果之一——根据结果分支，不要假设是

paid

：

`outcome`	含义	操作
`paid`	已结算，卖家返回2xx	将内容交付给用户
`no-payment-required`	资源没有付费墙，或已支付	告知用户未产生费用；返回内容
`replay-rejected`	支付已批准（资金在途），但卖家在重放时返回非2xx	不要报告成功。告知用户卖家响应失败；由于支付未完成，在途资金会退回至用户的InFlow余额。提供重试选项

两步路径。当代理主机无法长时间阻塞I/O以等待用户批准时（聊天UI在轮次之间会切换），使用此路径。去掉

--interval

；第一次调用返回

transaction_id

approval_id

approval_url

_next

Fetch命令/工具输入。Fetch负责轮询和卖家重放。

bash

inflow <mpp|x402> pay <url>

-> { "transaction_id": "txn_abc", "approval_id": "appr_xyz", "approval_url": "https://app.inflowpay.ai/approvals/appr_xyz", "_next": { "command": "<mpp|x402> fetch txn_abc <url> --interval 5 --max-attempts 180", "tool": "<mpp|x402>_fetch", "input": { "transactionId": "txn_abc", "resourceUrl": "<url>" } } }


Mind the two distinct ids: poll, replay, and resume all use `transaction_id`; **cancel uses `approval_id`** (`inflow <mpp|x402> cancel <approval_id>`). Both are returned by `pay`.

For non-GET requests, pass `--method`, `--data`, `--header` (repeatable):

```bash
inflow <mpp|x402> pay https://seller.example.com/api/widgets --method POST --data '{"sku":"widget-1"}' --header "X-Custom: value" --interval 5 --max-attempts 180

Idempotency (x402 only). Set

--payment-id <id>

whenever a retry on transport failure is possible - the server treats two requests with the same id as the same logical payment, so a retry after a network blip won't double-charge. Use a stable random opaque value generated once per intent; reuse the same id on transport retry; regenerate only when the user explicitly wants a fresh charge. Don't tie the id to wall-clock time - a date-based id silently double-charges on next-day "buy this again" requests. Without

--payment-id

, the server generates one each call - fine for one-shots, unsafe for retries. (Format constraints:

inflow x402 pay --schema

bash

inflow x402 pay <url> --payment-id "<stable-opaque-id>"

Sensitive / binary output. Fetch never exposes the one-time bearer credential (

credential

for MPP,

encoded_payload

for x402). For the seller's response body,

--output-file <path>

writes bytes to disk and replaces

body

body_base64

with

output_saved_to: <path>

- pair with

--no-show-body

for binary content (PDFs, images, audio, datasets) so bytes never appear inline as base64:

bash

inflow <mpp|x402> pay https://api.foo.dev/dataset.csv --interval 5 --max-attempts 180 --output-file /tmp/dataset.csv --no-show-body

Polling discipline. Persist

transaction_id

as soon as

pay

returns it. Then:

Run
```
_next.command
```
, or call
```
_next.tool
```
with
```
_next.input
```
, immediately. Don't wait for the user to confirm before polling starts.
If polling is interrupted - network drop, session bounce, user kills the agent - resume with
```
inflow <mpp|x402> fetch <transaction_id> <url> --interval 5 --max-attempts 180
```
. Only create a new transaction if the original expired (
```
PAYMENT_EXPIRED
```
for MPP,
```
APPROVAL_TIMEOUT
```
for x402), was denied/cancelled, or its credential is already consumed.
If
```
POLLING_TIMEOUT
```
fires before approval, ask the user whether to keep waiting or cancel - don't silently restart the poll.
If >12 minutes elapsed without a user response (≈3 min before the 15-minute approval window closes), surface that explicitly so they can act before the window closes.
If the user aborts ("nevermind", "cancel that"), call
```
inflow <mpp|x402> cancel <approval_id>
```
before exiting. Otherwise the approval sits pending for 15 minutes and triggers phantom notifications in the user's InFlow app.

Fetch sends a ready payment credential to the seller at most once per invocation. If Fetch returns

PAYMENT_REPLAY_OUTCOME_UNKNOWN

, tell the user the seller might have received or consumed the credential and do not automatically replay it.

When AEP is required, Fetch still sends the payment credential at most once. The final seller request carries both credentials without exposing either one in JSON output, logs, cache keys, or chat.


注意两个不同的ID：轮询、重放和恢复都使用`transaction_id`；**取消使用`approval_id`**（`inflow <mpp|x402> cancel <approval_id>`）。两者都由`pay`返回。

对于非GET请求，传递`--method`、`--data`、`--header`（可重复）：

```bash
inflow <mpp|x402> pay https://seller.example.com/api/widgets --method POST --data '{"sku":"widget-1"}' --header "X-Custom: value" --interval 5 --max-attempts 180

幂等性（仅x402）。当可能因传输失败需要重试时，设置

--payment-id <id>

——服务器会将具有相同ID的两个请求视为同一逻辑支付，因此网络故障后的重试不会重复收费。使用每个意图生成一次的稳定随机不透明值；传输重试时重用相同ID；仅当用户明确要求重新收费时才重新生成。不要将ID与挂钟时间绑定——基于日期的ID会在次日“再次购买”请求时静默重复收费。如果没有

--payment-id

，服务器会为每次调用生成一个——单次请求没问题，但重试不安全。（格式约束：

inflow x402 pay --schema

。）

bash

inflow x402 pay <url> --payment-id "<stable-opaque-id>"

敏感/二进制输出。Fetch永远不会暴露一次性承载凭证（MPP为

credential

，x402为

encoded_payload

）。对于卖家响应内容，

--output-file <path>

会将字节写入磁盘，并将

body

body_base64

替换为

output_saved_to: <path>

——对于二进制内容（PDF、图片、音频、数据集），搭配

--no-show-body

使用，这样字节永远不会以base64形式内联显示：

bash

inflow <mpp|x402> pay https://api.foo.dev/dataset.csv --interval 5 --max-attempts 180 --output-file /tmp/dataset.csv --no-show-body

轮询规则。

pay

transaction_id

后立即保存它。然后：

立即运行
```
_next.command
```
，或使用
```
_next.input
```
调用
```
_next.tool
```
。不要等待用户确认再启动轮询。
如果轮询被中断——网络断开、会话中断、用户终止代理——使用
```
inflow <mpp|x402> fetch <transaction_id> <url> --interval 5 --max-attempts 180
```
恢复。仅当原始交易过期（MPP为
```
PAYMENT_EXPIRED
```
，x402为
```
APPROVAL_TIMEOUT
```
）、被拒绝/取消或其凭证已消耗时，才创建新交易。
如果
```
POLLING_TIMEOUT
```
在批准前触发，询问用户是否继续轮询或取消——不要静默重启轮询。
如果超过12分钟未收到用户响应（≈15分钟批准窗口关闭前3分钟），明确告知用户，以便他们在窗口关闭前采取行动。
如果用户中止（“算了”、“取消”），退出前调用
```
inflow <mpp|x402> cancel <approval_id>
```
。否则批准会处于待处理状态15分钟，并在用户的InFlow应用中触发虚假通知。

Fetch每次调用最多向卖家发送一次就绪支付凭证。如果Fetch返回

PAYMENT_REPLAY_OUTCOME_UNKNOWN

，告知用户卖家可能已收到或消耗凭证，不要自动重放。

当需要AEP时，Fetch仍最多发送一次支付凭证。最终的卖家请求会携带两个凭证，但不会在JSON输出、日志、缓存键或聊天中暴露任何一个。

Limits

限制

Limit	Value
Approval window	15 minutes from `pay` creating the transaction ( `--timeout` overrides the polling deadline)
Polling stop condition	Polling ends at whichever fires first: `--max-attempts` (count, default `0` = unlimited) or `--timeout` (seconds, default `900` = the full 15-min window). The examples use `--interval 5 --max-attempts 180` (= 900 s) so a copied command covers the whole window - `--interval 5 --max-attempts 60` (= 300 s) would stop polling at 5 min, well before approval can land
Credential reuse	One-time. Fetch consumes the credential on the first seller replay - not reusable; a failed seller call requires a new `pay`

限制	值
批准窗口	从 `pay` 创建交易起15分钟（ `--timeout` 会覆盖轮询截止时间）
轮询停止条件	以下任一情况触发时轮询结束： `--max-attempts` （次数，默认 `0` =无限制）或 `--timeout` （秒，默认 `900` =完整15分钟窗口）。示例中使用 `--interval 5 --max-attempts 180` （=900秒），因此复制的命令覆盖整个窗口—— `--interval 5 --max-attempts 60` （=300秒）会在5分钟时停止轮询，远早于批准可能完成的时间
凭证重用	一次性。Fetch在第一次卖家重放时消耗凭证——不可重用；卖家调用失败需要新的 `pay`

Worked example (MPP)

示例（MPP）

A user asks the agent to fetch a paywalled dataset at

https://api.foo.dev/dataset.csv

Pre-flight:

inflow inspect <url>

reports

detected: ["mpp"]

with the seller's challenges; then

inflow mpp supported

(methods the buyer can pay with) and

inflow balances list

. The seller offers the

inflow

method in USDC; the user's 100.5 USDC balance covers the 0.10 USDC price. Summarize intent, then pay:

bash

inflow mpp pay https://api.foo.dev/dataset.csv --interval 5 --max-attempts 180 --output-file /tmp/dataset.csv --no-show-body

用户要求代理获取位于

https://api.foo.dev/dataset.csv

的付费数据集。

预检：

inflow inspect <url>

报告

detected: ["mpp"]

及卖家的质询；然后运行

inflow mpp supported

（买家可使用的支付方式）和

inflow balances list

。卖家提供USDC的

inflow

支付方式；用户的100.5 USDC余额足以覆盖0.10 USDC的价格。总结意图，然后支付：

bash

inflow mpp pay https://api.foo.dev/dataset.csv --interval 5 --max-attempts 180 --output-file /tmp/dataset.csv --no-show-body

Persist transaction_id from the response in case polling is interrupted.

保存响应中的transaction_id，以防轮询中断。

Returns outcome "paid" with output_saved_to /tmp/dataset.csv.

返回结果outcome为"paid"，output_saved_to为/tmp/dataset.csv。


> "Approval requested - confirm in the InFlow app: https://app.inflowpay.ai/approvals/appr_xyz
> I'll keep polling. 15-min window."

Once the result arrives:

> "Paid 0.10 USDC. Transaction txn_abc. Saved the dataset to /tmp/dataset.csv."

**Two-step variant** (host can't block): follow Step 2's two-step path; `mpp fetch` polls, attaches `Authorization: Payment`, and returns the resource body without exposing the credential.


> "已请求批准——请在InFlow应用中确认：https://app.inflowpay.ai/approvals/appr_xyz
> 我会持续轮询。15分钟窗口。"

结果返回后：

> "已支付0.10 USDC。交易ID txn_abc。数据集已保存到/tmp/dataset.csv。"

**两步变体**（主机无法阻塞）：遵循步骤2的两步路径；`mpp fetch`进行轮询，附加`Authorization: Payment`头，并返回资源内容，不暴露凭证。

Worked example (x402)

示例（x402）

A user asks the agent to fetch a paywalled article at

https://api.foo.dev/article-3

Pre-flight:

inflow inspect <url>

reports

detected: ["x402"]

; the intersection lands on

exact

solana:mainnet

, and the user's 100.5 USDC balance easily covers the 0.10 USDC the seller requires. Proceed.

"I'm about to pay 0.10 USDC on Solana mainnet to api.foo.dev for /article-3. Your balance is 100.5 USDC - plenty. Requesting approval next."

bash

inflow x402 pay https://api.foo.dev/article-3 --payment-id "<stable-opaque-id>" --interval 5 --max-attempts 180

用户要求代理获取位于

https://api.foo.dev/article-3

的付费文章。

预检：

inflow inspect <url>

报告

detected: ["x402"]

；交集为

exact

solana:mainnet

，用户的100.5 USDC余额轻松覆盖卖家要求的0.10 USDC。继续操作。

"我即将在Solana主网向api.foo.dev支付0.10 USDC以获取/article-3。你的余额为100.5 USDC——足够支付。接下来请求批准。"

bash

inflow x402 pay https://api.foo.dev/article-3 --payment-id "<stable-opaque-id>" --interval 5 --max-attempts 180

Persist transaction_id from the response in case polling gets interrupted.

保存响应中的transaction_id，以防轮询中断。

Returns outcome "paid"; body contains the article JSON.

返回结果outcome为"paid"；body包含文章JSON。


> "Approval requested - confirm in the InFlow app: https://app.inflowpay.ai/approvals/appr_xyz
> I'll keep polling. 15-min window."

Once the result arrives:

> "Paid 0.10 USDC. Transaction txn_abc. Server returned: 'How to brew coffee - ...'"

**Two-step variant** (host can't block): follow Step 2's two-step path; `x402 fetch` polls, attaches `PAYMENT-SIGNATURE`, and returns the resource body without exposing the encoded payload.


> "已请求批准——请在InFlow应用中确认：https://app.inflowpay.ai/approvals/appr_xyz
> 我会持续轮询。15分钟窗口。"

结果返回后：

> "已支付0.10 USDC。交易ID txn_abc。服务器返回：'How to brew coffee - ...'"

**两步变体**（主机无法阻塞）：遵循步骤2的两步路径；`x402 fetch`进行轮询，附加`PAYMENT-SIGNATURE`头，并返回资源内容，不暴露编码负载。

MPP errors

MPP错误

All errors in agent mode are JSON with

code

and

message

fields and exit code 1. MPP-specific codes (shared codes are in § Shared errors). "What to tell the user" is the prompt to surface - don't dump the raw error:

Error code	Recovery	What to tell the user
`PAYMENT_FAILED`	`inflow mpp status <transaction_id>` for the precise state, then create a new transaction with `inflow mpp pay` . (Terminal `failed` state, or no credential produced.)	"The payment didn't go through - it was declined, underfunded, or the transaction failed. Want me to try again, switch funding, or stop?"
`PAYMENT_EXPIRED`	Start a new `inflow mpp pay` .	"The payment window expired before it was ready to settle. Want me to start a new one, or stop here?"
`PAYMENT_NOT_ACCEPTED`	`inflow inspect <url>` to re-check the challenge; adjust and retry.	-

代理模式下的所有错误都是包含

code

和

message

字段的JSON，退出代码为1。MPP特定代码（共享代码见§ 共享错误）。“告知用户内容”是要展示的提示——不要转储原始错误：

错误代码	恢复方法	告知用户内容
`PAYMENT_FAILED`	运行 `inflow mpp status <transaction_id>` 获取精确状态，然后使用 `inflow mpp pay` 创建新交易。（终端 `failed` 状态，或未生成凭证。）	"支付未成功——被拒绝、资金不足或交易失败。要我重试、切换资金来源还是停止？"
`PAYMENT_EXPIRED`	启动新的 `inflow mpp pay` 。	"支付窗口在准备结算前已过期。要我启动新的支付还是在此停止？"
`PAYMENT_NOT_ACCEPTED`	运行 `inflow inspect <url>` 重新检查质询；调整后重试。	-

x402 errors

x402错误

All errors in agent mode are JSON with

code

and

message

fields and exit code 1. x402-specific codes (shared codes are in § Shared errors). "What to tell the user" is the prompt to surface - don't dump the raw error:

Error code	Recovery	What to tell the user
`APPROVAL_TIMEOUT`	`inflow x402 status <transaction_id>` for the precise reason, then create a new transaction.	"You didn't approve within 15 minutes, so the request expired. Want me to start a new payment, or stop here?"
`APPROVAL_FAILED`	Same recovery as `APPROVAL_TIMEOUT` (declined / insufficient funds in the matched asset / generic).	"Approval didn't go through (declined or insufficient funds in the matched asset). Want me to try a different funding source, top up, or stop?"
`APPROVAL_CANCELLED`	Same recovery (cancelled via `x402 cancel` or server-side).	"You cancelled the approval. Stopping here unless you want to start a new payment."
`INVALID_PAYMENT_ID`	`--payment-id` violated the format (see `inflow x402 pay --schema` ). Adjust or omit the payment id.	-

代理模式下的所有错误都是包含

code

和

message

字段的JSON，退出代码为1。x402特定代码（共享代码见§ 共享错误）。“告知用户内容”是要展示的提示——不要转储原始错误：

错误代码	恢复方法	告知用户内容
`APPROVAL_TIMEOUT`	运行 `inflow x402 status <transaction_id>` 获取精确原因，然后创建新交易。	"你未在15分钟内批准，请求已过期。要我启动新的支付还是在此停止？"
`APPROVAL_FAILED`	与 `APPROVAL_TIMEOUT` 恢复方法相同（被拒绝/匹配资产资金不足/通用错误）。	"批准未成功（被拒绝或匹配资产资金不足）。要我尝试其他资金来源、充值还是停止？"
`APPROVAL_CANCELLED`	恢复方法相同（通过 `x402 cancel` 或服务器端取消）。	"你已取消批准。在此停止，除非你要启动新的支付。"
`INVALID_PAYMENT_ID`	`--payment-id` 违反格式（参见 `inflow x402 pay --schema` ）。调整或省略支付ID。	-

Security & data handling

安全与数据处理

Applies to both protocols.

Treat OAuth tokens and API keys as secrets - never echo them. Use Fetch for approved payments so one-time payment credentials are attached to the seller request without being pasted back to the user.
Respect
```
/agents.txt
```
and
```
/llm.txt
```
on sites you browse.
Avoid suspicious 402 endpoints - if the domain doesn't match what the user asked to pay, or the price is different from expectation, stop and ask.
When displaying deposit addresses to the user, print the full address (don't truncate). Truncating breaks copy-paste.

适用于两种协议。

将OAuth令牌和API密钥视为机密——永远不要回显它们。使用Fetch处理已批准的支付，这样一次性支付凭证会附加到卖家请求中，而不会返回给用户。
尊重你浏览的网站上的
```
/agents.txt
```
和
```
/llm.txt
```
。
避免可疑的402端点——如果域名与用户要求支付的不符，或价格与预期不同，请停止并询问用户。
向用户显示存款地址时，打印完整地址（不要截断）。截断会破坏复制粘贴功能。

Shared errors

共享错误

These apply to both protocols (in addition to each section's protocol-specific codes). All are JSON with

code

and

message

and exit code 1. Where a command is protocol-specific, use your prefix (

<mpp|x402>

). "What to tell the user" is the prompt to surface - don't dump the raw error:

Error code	Recovery	What to tell the user
`VAULT_LOCKED`	Stored authentication status is unavailable. Ask the user to run `inflow vault unlock` themselves in a terminal, then retry.	"Your InFlow vault is locked. Please unlock it in your terminal, then I can check authentication again."
`NOT_AUTHENTICATED`	No saved device token and no `--api-key` / `INFLOW_API_KEY` configured. Run `inflow auth login` or set the API key env var.	-
`NO_INFLOW_MATCH`	Seller's rails aren't supported by the account. Fund a matching method/chain, or use a different seller.	"The seller wants `<method/rail or scheme×network>` , but your account can't pay on that rail. Either fund a matching method, or pick a different seller."
`NO_FILTERED_MATCH`	A `pay` filter emptied the candidate list. Loosen the filter (flags per the delta table), or re-check the seller's unfiltered options with `inflow inspect <url>` .	"Your filter removed every option the seller accepts. Loosen it or re-check the seller's options with `inflow inspect` ."
`INVALID_402` / `DECODE_FAILED`	Seller returned 402 but the protocol's header was missing ( `INVALID_402` ) or unparseable ( `DECODE_FAILED` ). Verify the URL is payable; pass the raw header to `inflow <mpp	x402> decode` for the detailed parse error.
`POLLING_TIMEOUT`	`--interval` polling reached its max-attempts or timeout. Retryable - resume with `inflow <mpp	x402> fetch <transaction_id> <url> --interval 5 --max-attempts 180`.
`PAYMENT_REPLAY_OUTCOME_UNKNOWN`	A credential-bearing seller request had an indeterminate transport failure. Do not automatically replay.	"The seller request may have received the payment credential, but the connection failed before we got a reliable response. I won't retry automatically because the credential may be consumed."
`api_error`	Non-2xx from the InFlow API on the plain data calls ( `balances` , `deposit-addresses` ); discriminate on `httpStatus` . `401` - saved auth rejected, re-run `inflow auth login` . `426` ( `VERSION_UNSUPPORTED` ) - upgrade and retry. `5xx` - server-side; wait and retry. (Note: `pay` / `status` rejections instead surface the server's own code, e.g. `INSUFFICIENT_FUNDS` , or the protocol's terminal code - not `api_error` .)	-
`VERSION_UNSUPPORTED` / HTTP 426	Installed `inflow` CLI is below the minimum supported version. Install the current release from https://inflowcli.ai/, then retry; don't retry on the old version.	-
`transport_error`	Network failure - check connectivity; retry.	-

这些适用于两种协议（除各部分的协议特定代码外）。所有错误都是包含

code

和

message

的JSON，退出代码为1。如果命令是协议特定的，请使用对应前缀（

<mpp|x402>

）。“告知用户内容”是要展示的提示——不要转储原始错误：

错误代码	恢复方法	告知用户内容
`VAULT_LOCKED`	存储的身份验证状态不可用。要求用户在终端中自行运行 `inflow vault unlock` ，然后重试。	"你的InFlow密钥库已锁定。请在终端中解锁，然后我可以重新检查身份验证状态。"
`NOT_AUTHENTICATED`	无已保存的设备令牌，且未配置 `--api-key` / `INFLOW_API_KEY` 。运行 `inflow auth login` 或设置API密钥环境变量。	-
`NO_INFLOW_MATCH`	卖家的支付渠道不受账户支持。向匹配的方法/链充值，或选择其他卖家。	"卖家要求 `<method/rail or scheme×network>` ，但你的账户无法在该渠道支付。请向匹配的方法充值，或选择其他卖家。"
`NO_FILTERED_MATCH`	`pay` 过滤器清空了候选列表。放宽过滤器（差异表中的标志），或使用 `inflow inspect <url>` 重新检查卖家的未过滤选项。	"你的过滤器移除了卖家接受的所有选项。请放宽过滤器或使用 `inflow inspect` 重新检查卖家的选项。"
`INVALID_402` / `DECODE_FAILED`	卖家返回402，但协议头缺失（ `INVALID_402` ）或无法解析（ `DECODE_FAILED` ）。验证URL是否可支付；将原始头传递给`inflow <mpp	x402> decode`获取详细解析错误。
`POLLING_TIMEOUT`	`--interval` 轮询达到最大尝试次数或超时。可重试——使用`inflow <mpp	x402> fetch <transaction_id> <url> --interval 5 --max-attempts 180`恢复。
`PAYMENT_REPLAY_OUTCOME_UNKNOWN`	携带凭证的卖家请求出现不确定的传输失败。不要自动重放。	"卖家请求可能已收到支付凭证，但在我们获得可靠响应前连接失败。我不会自动重试，因为凭证可能已被消耗。"
`api_error`	普通数据调用（ `balances` 、 `deposit-addresses` ）从InFlow API收到非2xx响应；根据 `httpStatus` 区分。 `401` ——已保存的身份验证被拒绝，重新运行 `inflow auth login` 。 `426` （ `VERSION_UNSUPPORTED` ）——升级后重试。 `5xx` ——服务器端错误；等待后重试。（注意： `pay` / `status` 拒绝会显示服务器自身的代码，例如 `INSUFFICIENT_FUNDS` ，或协议的终端代码——而非 `api_error` 。）	-
`VERSION_UNSUPPORTED` / HTTP 426	安装的 `inflow` CLI版本低于最低支持版本。从https://inflowcli.ai/安装当前版本，然后重试；不要使用旧版本重试。	-
`transport_error`	网络故障——检查连接；重试。	-

Out of scope

超出范围

This skill covers programmatic HTTP 402 payments (MPP and x402) only. It does NOT handle:

Traditional merchant checkouts No PANs (credit card forms, hosted checkouts).
Card issuance or wallet management beyond
```
balances list
```
and
```
deposit-addresses list
```
.
Refunds, disputes, chargebacks - handled out of band via support.
Peer-to-peer transfers between users or wallets.
FX / currency conversion. Buyer logic matches the seller's accepted rails against the account's supported assets.
Subscriptions / recurring payments. Each
```
pay
```
is one-shot.

For any of the above, point the user to https://app.inflowpay.ai or support.

本技能仅涵盖程序化HTTP 402支付（MPP和x402）。它不处理：

传统商家结账 无PAN（信用卡表单、托管结账）。
发卡或超出
```
balances list
```
和
```
deposit-addresses list
```
的钱包管理。
退款、争议、拒付——通过支持渠道处理。
用户或钱包间的点对点转账。
外汇/货币兑换。买家逻辑将卖家接受的渠道与账户支持的资产进行匹配。
订阅/定期支付。每个
```
pay
```
都是单次支付。

如需上述任何服务，请引导用户访问https://app.inflowpay.ai或联系支持。

agentic-payments

Original

Translation

Agentic Payments

智能代理支付

Installing

安装

Running

运行

Common commands / options

常用命令/选项

Authenticate

身份验证

Which protocol? - start here

使用哪种协议？——从此开始

Paying a 402 resource

支付402资源

Protocol deltas

协议差异

Step 1: Pre-flight evaluation

步骤1：预检评估

1. Parse what the seller will accept - read-only, no auth (both protocols in one probe)

1. 解析卖家接受的支付方式——只读，无需身份验证（一次探测两种协议）

(Already have the raw 402 header from a prior response? Decode it directly instead of re-probing:)

（已有之前响应中的原始402头？直接解码它，无需重新探测：）

2. List what the buyer's account can pay with (use the protocol from detected)

2. 列出买家账户可使用的支付方式（使用detected中的协议）

3. Check balances for the candidate currency/asset(s)

3. 检查候选货币/资产的余额

Step 2: Pay

步骤2：支付

Limits

限制

Worked example (MPP)

示例（MPP）

Persist transaction_id from the response in case polling is interrupted.

保存响应中的transaction_id，以防轮询中断。

Returns outcome "paid" with output_saved_to /tmp/dataset.csv.

返回结果outcome为"paid"，output_saved_to为/tmp/dataset.csv。

Worked example (x402)

示例（x402）

Persist transaction_id from the response in case polling gets interrupted.

保存响应中的transaction_id，以防轮询中断。

Returns outcome "paid"; body contains the article JSON.

返回结果outcome为"paid"；body包含文章JSON。

MPP errors

MPP错误

x402 errors

x402错误

Security & data handling

安全与数据处理

Shared errors

共享错误

Out of scope

超出范围

Further docs

更多文档

2. List what the buyer's account can pay with (use the protocol from
`detected`
)

2. 列出买家账户可使用的支付方式（使用
`detected`
中的协议）