Wallet MCP tools

These tools run on the user’s authenticated MCP connection. See Wallet Service for the workflow and MCP connection and OAuth 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:

{
  "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, 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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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 Documentation

Clink MCP

Checkout Session

Payment

Payment Instrument

Order

Agent Payment Session

Refund

Product

Price

Coupon

Promotion Code

Subscription

Test Clock

Customer Portal

Webhook Endpoint Management

Webhooks

Scope summary

get_account_state

set_default_card

start_payment_method_action

create_purchase_instruction

list_spendable_instructions

get_instruction

start_instruction_action

start_agent_pay_registration

Risk settings

​Scope summary

​get_account_state

​set_default_card

​start_payment_method_action

​create_purchase_instruction

​list_spendable_instructions

​get_instruction

​start_instruction_action

​start_agent_pay_registration

​Risk settings

Scope summary

get_account_state

set_default_card

start_payment_method_action

create_purchase_instruction

list_spendable_instructions

get_instruction

start_instruction_action

start_agent_pay_registration

Risk settings