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 input field, instruction. 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.

One string in

The schema has one field and nothing else: no amount, no payee, no credential, no session id. Pass the customer’s request as instruction and the platform parses it.

Do not rule requests out by institution type in your prompt. Capability varies with the customer’s own agent behind the connection, 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.