Add it as a tool

One tool in the model loop you already run.

If your agent already runs a model against a tools array, the integration is two calls. payman.tool() puts the served definition in the array; handleToolUse() runs the action when the model calls it.

Node

import Anthropic from "@anthropic-ai/sdk";
import { PaymanConnect } from "@paymanai/connect";

const anthropic = new Anthropic();
const payman = new PaymanConnect();

const reply = await anthropic.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  tools: [payman.tool()],          // sync, no await
  messages,
});

messages.push({ role: "assistant", content: reply.content });

for (const block of reply.content) {
  if (block.type === "tool_use" && block.name === "payman_money_task") {
    const turn = await payman.forUser(userId).handleToolUse(
      { id: block.id, input: block.input },
      { onEvent: (e) => e.type === "progress" && show(e.progress.label) },
    );
    messages.push({ role: "user", content: [turn.toolResult] });  // model-visible
    render(turn.ui);                                              // app-visible
  }
}

The two calls

payman.tool() is synchronous. It returns the definition the platform serves: name payman_money_task, one required input field, instruction, and one optional one, provider. Never transcribe the definition into your code; the SDK caches the served copy and ships a bundled snapshot for the first call.

payman.toolDefinitionVersion() names the contract date you are running against, and await payman.doctor() reports drift.

handleToolUse() takes the block’s id and input, runs the action, and resolves a ToolTurn with two fields:

Field	Who reads it	What it carries
toolResult	The model	A ready tool_result block: a JSON status envelope carrying status and guidance, plus the answer text on success.
ui	Your app	The full result, the same four kinds run() returns: ok, needs_connection, approval, error.

Push toolResult back to the model unchanged. Render from ui: switch on kind and show the connect or approval button exactly as you would after run(). toolResult structurally cannot carry connectUrl, approvalUrl, or a ref; URLs exist only on ui.

Progress while it runs

handleToolUse() accepts the same options as run(). Passing onEvent switches the call to the streaming route and delivers frames while the result is still pending.

Each progress frame carries a phase (started, completed, waiting) and a label written for the customer. Render the label and replace it on the next frame rather than stacking lines.

What the schema takes

Two fields, and nothing else. No amount, no payee, no credential, no session id.

Field	Required	Holds
instruction	yes	The customer’s request in their own words, as one self-contained sentence.
provider	no	Which connected account to use, when that is already decided.

Pass the request as the customer said it. Do not split it into structured fields, and do not rule requests out by institution type in your prompt: capability varies with what the customer connected, so call the tool and let the result answer.

The served description already carries the ground rules for relaying and attributing answers, so they arrive with the tool rather than depending on your prompt.

When the Wallet asks back

A customer can connect several accounts. Two statuses are the Wallet asking, not failing:

Status	Means	What the model does
needs_provider	Several accounts could do this	Asks which, then sends the same instruction again naming it
no_capable_provider	None of them can	Says so plainly, and does not retry

The served description tells the model both, so this needs nothing from your prompt. On your side the same value arrives on ui.agentStatus. See the Wallet.

Connecting an account is not a money task. If the model calls this tool to link or remove one, the platform hands back the link to the customer’s Payman page instead.