> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet MCP 工具

> 钱包卡片与购买授权工具的参数、Scope 和返回结果。

这些工具通过用户已认证的 MCP 连接调用。业务流程见 [Wallet Service](/cn/guides/agent/wallet_service)，连接授权见 [MCP 连接与 OAuth](/cn/guides/agent/mcp_integration)。工具名和参数名区分大小写。

以下 JSON 示例均为工具参数。例如，通过 MCP `tools/call` 调用 `get_account_state`：

```json theme={null}
{
  "name": "get_account_state",
  "arguments": {}
}
```

从 `structuredContent` 读取成功的结构化结果。返回 `isError: true` 时，应处理错误，不能将其文本视为成功响应。启动流程的工具返回 [Operation 封装](/cn/api-reference/mcp/operations)，但 `start_instruction_action` 返回的是链接交接对象。

## Scope 汇总

| 工具 | 所需 Scope |
| :- | :- |
| `get_account_state` | `wallet:read` |
| `set_default_card` | `wallet:read`、`wallet:setup` |
| `start_payment_method_action` | `wallet:read` |
| `create_purchase_instruction` | `wallet:read`、`instruction:read`、`instruction:write` |
| `list_spendable_instructions` | `instruction:read`；不传 `paymentInstrumentId` 时还需要 `wallet:read` |
| `get_instruction` | `instruction:read` |
| `start_instruction_action`（`sign`） | `wallet:read`、`instruction:read` |
| `start_instruction_action`（`update`、`cancel`） | `instruction:write` |
| `start_agent_pay_registration` | `wallet:read` |
| `get_risk_rules`、`start_risk_rules_action` | `wallet:read` |

缺少权限时返回 `insufficient scope: <scope> is required`。在 OAuth Client 已登记的 Scope 范围内请求用户补充授权。`events:read` 和 `events:consume` 用于借助事件跟进流程，不能替代上表权限。

## get\_account\_state

读取当前钱包。**参数：** `{}`。

| 返回字段 | 类型 | 含义 |
| :- | :- | :- |
| `customer_id`、`email` | 可选字符串 | 可用时返回用户标识及钱包邮箱。 |
| `ready` | Boolean | 存在至少一种可用支付方式。不代表具备 Browser Pay 能力或已获得消费授权。 |
| `paymentMethods` | 数组 | 当前支付方式，字段见下表。 |
| `defaultPaymentInstrumentId` | 可选字符串 | 能确定时返回当前默认卡 ID。 |
| `blockedReason` | 可选字符串 | 没有可用支付方式时为 `NO_PAYMENT_METHOD`。 |

每个 `paymentMethods[]` 包含：

| 字段 | 含义 |
| :- | :- |
| `paymentInstrumentId` | 传给工具的卡片标识。 |
| `cardScheme`、`cardLastFour` | 可选的品牌与卡号后四位，用于展示。 |
| `isDefault` | 是否为默认卡。 |
| `agent_pay_support` | 当前提供方配置下，该卡是否具备 Agent Pay 能力。 |
| `strongAuthRegistered` | 该卡是否已完成 Agent Pay 注册。 |
| `strongAuthReady`、`authProtocol` | 可选的当前设备认证状态。 |
| `cardSchemeRegistrationEnabled` | 可选的提供方注册能力标识。 |

用户每次重新询问钱包状态或选择卡片时，重新读取。不要用旧结果识别用户当前的卡片。使用默认卡购买不需要预先调用此工具。

## set\_default\_card

仅在用户要求时修改钱包默认卡。先从新的 `get_account_state` 结果中准确匹配一张卡。

```json theme={null}
{
  "paymentInstrumentId": "payment-instrument-from-wallet"
}
```

`paymentInstrumentId` 必填，必须是非空字符串。返回 `{ changed, account }`：`account` 结构与 `get_account_state` 相同，`changed: false` 表示该卡已经是默认卡。

卡片已不可用时，重新读取钱包。修改被拒绝或无法确认时，先刷新状态再告知用户；必要时提供 `start_payment_method_action` 的 `set-default` 流程。如果只是本次购买换卡，应把卡 ID 传给购买工具，而不是修改默认卡。

## start\_payment\_method\_action

启动由用户完成的卡片添加或管理流程。

```json theme={null}
{
  "action": "add"
}
```

`action` 支持 `add`、`replace`、`set-default`、`remove`，默认值为 `add`。

返回带有 `REDIRECT_USER` 动作的 Operation。向用户展示 `next_action.params.redirect_url`；`actor: "USER_DEVICE_ONLY"` 表示用户必须在自己的设备上打开，Agent 不应预览该链接。此调用本身不会变更卡片。用户完成后读取同一个 Operation，再刷新 `get_account_state`。

## create\_purchase\_instruction

创建购买授权草稿并启动激活流程，用于用户明确提出的授权管理。Browser Pay 应直接按结账事实调用 `get_credential`，由其处理授权匹配与创建。

```json theme={null}
{
  "requestId": "wallet-budget-example-001",
  "title": "Office supplies budget",
  "isRecurring": false,
  "mandates": [
    {
      "description": "Purchase office supplies within the approved budget",
      "amountLimit": "25.00",
      "currencyCode": "USD"
    }
  ]
}
```

| 参数 | 必填 | 说明 |
| :- | :- | :- |
| `requestId` | 是 | 8–128 字符。每个用户意图生成一次，继续或重试时使用相同 ID 和完全一致的参数。 |
| `title` | 是 | 非空授权标题。 |
| `mandates` | 是 | 非空 Mandate 数组，结构见下表。 |
| `paymentInstrumentId` | 否 | 用户明确选定的卡，必须来自新的钱包结果且 `agent_pay_support: true`。不传时使用默认卡，不会修改默认卡。 |
| `description` | 否 | 授权说明。 |
| `effectiveUntilTime` | 否 | UTC 格式 `yyyy-MM-dd HH:mm:ss`。服务会应用有效期规则，实际值需重新读取确认。 |
| `isRecurring` | 否 | 是否为周期授权。为 `true` 时，每条 Mandate 都必须有 `recurringFrequency`。 |
| `email` | 否 | 用于预填授权页面的有效邮箱。 |
| `shippingAddress` | 否 | 需要配送的实物商品的美国地址。服务、数字商品和预订不传。 |

每条 Mandate 包含：

| 字段 | 必填 | 说明 |
| :- | :- | :- |
| `description` | 是 | 非空的授权消费用途。 |
| `amountLimit` | 是 | **主货币单位的正十进制字符串**，最多 18 位整数、2 位小数。`"25.00"` 表示 USD 25.00。 |
| `currencyCode` | 是 | 三字母币种代码。同一 Instruction 内的所有 Mandate 必须使用同一币种。 |
| `recurringFrequency` | 周期授权必填 | `WEEKLY`、`MONTHLY` 或 `YEARLY`。 |
| `merchantCategoryCode` | 否 | 适用时填写商户品类限制。 |
| `preferredMerchantName` | 否 | 偏好商户名称。 |
| `effectiveUntilTime` | 否 | UTC 格式 `yyyy-MM-dd HH:mm:ss`；不传时使用 Instruction 的到期时间。 |

传入 `shippingAddress` 时，必填 `name`、`line1`、`city`、`state`、`zip` 和 `countryCode: "US"`。可选字段为 `line2`、`line3` 和对象类型的 `deliveryContactDetails`。

常规结果是 Operation。支持相应能力的 Host 也可能收到用于链接交互的 MCP `input_required`；保留协议请求状态，并以完全一致的原始参数继续。接受或打开链接不代表激活成功。

| 结果或情况 | 如何处理 |
| :- | :- |
| `REDIRECT_USER` | 展示返回的链接；读取同一个 Operation 和 Instruction 核验完成状态。 |
| `SETUP_REQUIRED` / `DEFAULT_CARD` | 让用户选择支持的卡。仅用于本项授权时，用新 `requestId` 和该卡的 `paymentInstrumentId` 再次调用；用户修改默认卡后，则复用原 ID 与原参数。 |
| `SETUP_REQUIRED` / `PURCHASE_INSTRUCTION` 且 `resumable: true` | 完成所需准备后，用原 ID 和原参数重试。 |
| 未绑卡的 `PENDING` Instruction | 绑卡和授权过程保持同一项 Instruction，不要创建替代项。 |
| 同一 `requestId` 携带不同参数 | 恢复原始参数；只有新的用户意图才使用新 ID。 |
| 所选卡不可用或不具备 Agent Pay 能力 | 刷新钱包，请用户选择支持的卡。 |
| `CONTACT_SUPPORT` | 按返回的支持指引处理，不要创建重复授权来绕过未确认结果。 |

只有同一 ID、状态为 `ACTIVE`、已绑定卡片并包含适用 Mandate 的 Instruction 才能授权消费。Operation 完成不代表商户付款已经发生。

## list\_spendable\_instructions

查询一张卡上包含可用 Mandate 的有效授权。

```json theme={null}
{
  "paymentInstrumentId": "payment-instrument-from-wallet"
}
```

`paymentInstrumentId` 可选，不传时使用当前默认卡；无法确定默认卡时返回空列表。结果为 `{ instructions: [...] }`，字段使用下文的 Instruction 结构。已使用或已占用的单次 Mandate 会被过滤。使用授权前仍需匹配购买用途、币种、金额、商户或品类及有效期；查询结果本身不代表用户批准一笔新购买。

## get\_instruction

读取指定授权的权威状态。

```json theme={null}
{
  "instructionId": "instruction-id-from-result"
}
```

`instructionId` 必填。主要返回字段如下：

| 字段 | 含义 |
| :- | :- |
| `instructionId` | 授权标识。 |
| `status` | 只有 `ACTIVE` 能授权消费；`CREATED`、`PENDING` 不能。 |
| `paymentInstrumentId`、`cardScheme`、`cardLastFour` | 可用时返回已绑定卡片信息。 |
| `title`、`description` | 授权用途。 |
| `totalAmountLimit`、`currencyCode` | **主货币单位**的总限额，可能返回数字或十进制字符串。 |
| `effectiveUntilTime`、`isRecurring` | 实际到期时间和周期设置。 |
| `mandates` | 各项限额，包含 `mandateId`、`amountLimit`、`currencyCode`、商户字段、有效期与 `recurringFrequency`。金额使用**主货币单位**。 |

除 `instructionId` 外，字段可能缺失或为 `null`。金额、卡 ID 或状态缺失时，不能视为有效授权。结果还可能包含提供方的其他字段。

## start\_instruction\_action

获取由用户操作的签署、修改或取消授权链接。

```json theme={null}
{
  "action": "sign",
  "instructionId": "instruction-id-from-result",
  "paymentInstrumentId": "bound-payment-instrument-id"
}
```

| 参数 | 规则 |
| :- | :- |
| `action` | 必填，支持 `sign`、`update`、`cancel`。 |
| `instructionId` | `sign` 时必填；`update`、`cancel` 不接受此字段。 |
| `paymentInstrumentId` | 仅用于 `sign`。使用授权已绑定的卡；未绑卡的 `PENDING` Instruction 可不传。 |
| `email` | 仅用于 `sign`，可选的预填邮箱。 |

修改或取消时，只传 `{ "action": "update" }` 或 `{ "action": "cancel" }`。用户在管理页面中选择授权。

返回 `{ action, actor: "USER_DEVICE_ONLY", url }`，适用时还包含 `instructionId` 和 `paymentInstrumentId`。它**不是** Operation：将 `url` 展示给用户，操作后用 `get_instruction` 核验相应授权。获取链接本身不会完成签署、修改或取消。

## start\_agent\_pay\_registration

为用户选定、且 `agent_pay_support: true` 的卡启动独立注册流程。

```json theme={null}
{
  "paymentInstrumentId": "payment-instrument-from-wallet"
}
```

`paymentInstrumentId` 必填。返回的 Operation 提供由用户在自己设备上打开的 Passkey 链接。之后读取同一个 Operation 或钱包；同一张卡的 `strongAuthRegistered: true` 才证明注册完成，`strongAuthReady` 和 `authProtocol` 不能替代它。

卡已注册时，不要重复发起注册。无法验证卡片归属或资格时，重新读取钱包。Browser Pay 和购买授权创建会在各自流程内处理准备步骤，此工具不是它们的前置条件。卡片具备 Agent Pay 能力本身不代表每一种支付场景都已可用。

## 风控设置

两个工具均以 `{}` 为参数，需要 `wallet:read`。

| 工具 | 结果与用法 |
| :- | :- |
| `get_risk_rules` | 返回 `{ riskRules: ... }`，包含提供方当前设置。按提供方数据处理，不要假定未公开的固定结构。 |
| `start_risk_rules_action` | 返回带有用户设备专用风控设置链接的 Operation，由用户在页面中修改。 |

具备事件权限时，Operation 可能确认发生过经过验证的保存。实际值始终以 `get_risk_rules` 为准，包括用户未作修改或未收到完成事件的情况。

通用等待、跳转与错误处理见 [Operation 与后续动作](/cn/api-reference/mcp/operations)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.