> ## 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 tools

> Tool inputs, scopes, and results for wallet cards and purchase instructions.

These tools run on the user's authenticated MCP connection. See [Wallet Service](/guides/agent/wallet_service) for the workflow and [MCP connection and OAuth](/guides/agent/mcp_integration) for authorization. Tool names and argument names are case-sensitive.

The JSON examples below are tool arguments. For example, invoke `get_account_state` through MCP `tools/call` as follows:

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

Read successful structured results from `structuredContent`. If a result has `isError: true`, handle the error instead of treating its text as a successful response. Tools that start a workflow return an [Operation envelope](/api-reference/mcp/operations), except `start_instruction_action`, which returns a URL handoff.

## Scope summary

| Tool | Required scopes |
| :- | :- |
| `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`; also `wallet:read` when `paymentInstrumentId` is omitted |
| `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` |

A missing scope is reported as `insufficient scope: <scope> is required`. Request additional user consent within the OAuth client's registered scopes. `events:read` and `events:consume` support event-assisted workflow tracking; they do not replace the scopes above.

## get\_account\_state

Read the current wallet. **Input:** `{}`.

| Result field | Type | Meaning |
| :- | :- | :- |
| `customer_id`, `email` | Optional strings | User identity and wallet email, when available. |
| `ready` | Boolean | At least one usable payment method exists. Not proof of Browser Pay eligibility or spending authorization. |
| `paymentMethods` | Array | Current payment methods, with the fields below. |
| `defaultPaymentInstrumentId` | Optional string | Current default card ID, when resolved. |
| `blockedReason` | Optional string | `NO_PAYMENT_METHOD` when no usable payment method exists. |

Each `paymentMethods[]` entry includes:

| Field | Meaning |
| :- | :- |
| `paymentInstrumentId` | Card identifier to pass to tools. |
| `cardScheme`, `cardLastFour` | Optional display brand and last four digits. |
| `isDefault` | Whether this is the default card. |
| `agent_pay_support` | Whether this card is eligible for Agent Pay under the current provider configuration. |
| `strongAuthRegistered` | Whether this card has completed Agent Pay registration. |
| `strongAuthReady`, `authProtocol` | Optional current-device authentication state. |
| `cardSchemeRegistrationEnabled` | Optional provider registration capability flag. |

Read again for every new user question about wallet state or card selection. Do not reuse old results to identify the user's cards. A purchase using the default card does not require this call first.

## set\_default\_card

Change the wallet default only when the user requests it. First identify exactly one card from a fresh `get_account_state` response.

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

`paymentInstrumentId` is required and must be a non-empty string. Returns `{ changed, account }`: `account` has the `get_account_state` shape, and `changed: false` means the card was already the default.

If the card is no longer available, refresh the wallet. If the change was rejected or could not be confirmed, refresh before reporting the result; offer `start_payment_method_action` with `set-default` if needed. For a single purchase on a different card, pass its ID to the purchase tool instead of changing the default.

## start\_payment\_method\_action

Start user-managed card setup or management.

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

`action` accepts `add`, `replace`, `set-default`, or `remove`; it defaults to `add`.

Returns an Operation with a `REDIRECT_USER` action. Present `next_action.params.redirect_url` to the user; its `actor: "USER_DEVICE_ONLY"` means the user must open it on their device. The agent must not preview it. This call alone does not change a card. Read the same Operation after completion, then refresh `get_account_state`.

## create\_purchase\_instruction

Create a spending authorization draft and start its activation flow. Use this for explicit authorization management. For Browser Pay, call `get_credential` directly with the checkout facts; it handles authorization matching and creation.

```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"
    }
  ]
}
```

| Argument | Required | Description |
| :- | :- | :- |
| `requestId` | Yes | String, 8–128 characters. Generate once per user intent; reuse with identical arguments when continuing or retrying. |
| `title` | Yes | Non-empty authorization title. |
| `mandates` | Yes | Non-empty array of the mandate objects below. |
| `paymentInstrumentId` | No | A card explicitly chosen by the user, from a fresh wallet response with `agent_pay_support: true`. Omit to use the default. Does not change the default. |
| `description` | No | Authorization description. |
| `effectiveUntilTime` | No | UTC `yyyy-MM-dd HH:mm:ss`. The service applies its validity policy; read back the effective value. |
| `isRecurring` | No | Whether the authorization is recurring. When `true`, every mandate must include `recurringFrequency`. |
| `email` | No | Valid email address used to prefill the authorization page. |
| `shippingAddress` | No | US delivery address for physical goods that ship. Omit for services, digital goods, and bookings. |

Each mandate contains:

| Field | Required | Description |
| :- | :- | :- |
| `description` | Yes | Non-empty purpose of the authorized spending. |
| `amountLimit` | Yes | Positive decimal **string in major units**, at most 18 integer digits and 2 decimal places. `"25.00"` means USD 25.00. |
| `currencyCode` | Yes | Three-letter currency code. All mandates in one instruction must use the same currency. |
| `recurringFrequency` | For recurring instructions | `WEEKLY`, `MONTHLY`, or `YEARLY`. |
| `merchantCategoryCode` | No | Merchant category restriction, when applicable. |
| `preferredMerchantName` | No | Preferred merchant name. |
| `effectiveUntilTime` | No | UTC `yyyy-MM-dd HH:mm:ss`; defaults to the instruction expiry when omitted. |

When supplied, `shippingAddress` requires `name`, `line1`, `city`, `state`, `zip`, and `countryCode: "US"`. Optional fields are `line2`, `line3`, and `deliveryContactDetails` (an object).

The normal result is an Operation. Supporting hosts may instead receive MCP `input_required` for a URL interaction; preserve the protocol's request state and continue with the unchanged original arguments. Accepting or opening the URL is not proof of activation.

| Result or condition | What to do |
| :- | :- |
| `REDIRECT_USER` | Present the returned link. Read the same Operation and instruction to verify completion. |
| `SETUP_REQUIRED` / `DEFAULT_CARD` | Let the user choose a supported card. For this authorization only, call again with a new `requestId` and its `paymentInstrumentId`. If the user changes the default, repeat the original request with the original ID and arguments. |
| `SETUP_REQUIRED` / `PURCHASE_INSTRUCTION` with `resumable: true` | After the required setup, repeat the original request with the same ID and arguments. |
| Unbound `PENDING` instruction | Keep the same instruction through card binding and authorization. Do not create a replacement. |
| `requestId` reused with different input | Restore the original input, or use a new ID only for a new user intent. |
| Chosen card unavailable or not Agent Pay eligible | Refresh the wallet and let the user choose a supported card. |
| `CONTACT_SUPPORT` | Follow the returned support guidance; do not create duplicate authorizations to bypass an unconfirmed result. |

Only a same-ID `ACTIVE` instruction with a bound card and applicable mandate authorizes spending. An Operation completing is not evidence that a merchant payment occurred.

## list\_spendable\_instructions

List active instructions with usable mandates for one card.

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

`paymentInstrumentId` is optional. Omit it to resolve the current default card; if no default can be resolved, the result is an empty list. Returns `{ instructions: [...] }`, using the Instruction fields below. Consumed or reserved one-time mandates are filtered out. Match the intended purpose, currency, amount, merchant or category, and validity before using an authorization; the list itself does not approve a new purchase.

## get\_instruction

Read the authoritative state of one instruction.

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

`instructionId` is required. The main result fields are:

| Field | Meaning |
| :- | :- |
| `instructionId` | Instruction identifier. |
| `status` | Only `ACTIVE` authorizes spending; `CREATED` or `PENDING` does not. |
| `paymentInstrumentId`, `cardScheme`, `cardLastFour` | Bound card, when available. |
| `title`, `description` | Purpose of the authorization. |
| `totalAmountLimit`, `currencyCode` | Overall limit in **major currency units**, returned as a number or decimal string. |
| `effectiveUntilTime`, `isRecurring` | Effective expiry and recurrence setting. |
| `mandates` | Individual limits, including `mandateId`, `amountLimit`, `currencyCode`, merchant fields, expiry, and `recurringFrequency`. Amounts use **major units**. |

Fields other than `instructionId` may be absent or `null`; do not turn missing amounts, card IDs, or status into a successful authorization. Additional provider fields may be returned.

## start\_instruction\_action

Get a user-operated link to sign, update, or cancel an instruction.

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

| Argument | Rule |
| :- | :- |
| `action` | Required: `sign`, `update`, or `cancel`. |
| `instructionId` | Required for `sign`; not accepted for `update` or `cancel`. |
| `paymentInstrumentId` | For `sign` only. Use the instruction's bound card; omit for an unbound `PENDING` instruction. |
| `email` | Optional prefill email for `sign` only. |

For update or cancellation, send only `{ "action": "update" }` or `{ "action": "cancel" }`. The user selects the instruction on the management page.

Returns `{ action, actor: "USER_DEVICE_ONLY", url }`, with `instructionId` and `paymentInstrumentId` when applicable. This is **not** an Operation; present `url` to the user and verify the relevant instruction with `get_instruction` afterward. The link alone does not sign, update, or cancel anything.

## start\_agent\_pay\_registration

Start standalone registration for a user-selected card with `agent_pay_support: true`.

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

`paymentInstrumentId` is required. The returned Operation provides a Passkey link for the user's own device. Read the same Operation or wallet afterward; `strongAuthRegistered: true` for the same card proves completion. `strongAuthReady` and `authProtocol` do not.

If the card is already registered, do not start another registration. If ownership or eligibility cannot be verified, refresh the wallet. Browser Pay and instruction creation handle setup within their own flows; this tool is not a prerequisite for them. Card eligibility does not, by itself, promise availability in every payment scenario.

## Risk settings

Both tools take `{}` and require `wallet:read`.

| Tool | Result and use |
| :- | :- |
| `get_risk_rules` | `{ riskRules: ... }`, containing the provider's current settings. Treat the settings as provider data rather than assuming a fixed undocumented schema. |
| `start_risk_rules_action` | Operation with a user-only risk-settings URL. The user edits the settings on that page. |

An Operation may confirm that a verified save occurred when event permissions are available. Always read `get_risk_rules` for the current values, including when the user makes no change or no completion event arrives.

For common waiting, redirect, and error handling, see [Operations and next actions](/api-reference/mcp/operations).


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