The Wallet

One customer, one or more connected accounts.

A customer’s Wallet is the set of accounts they connected to your app. It might be one. It might be a bank, a corporate card and a crypto account side by side.

You never choose between them. Send the instruction; the Wallet routes it to the account that can do the job.

How routing reads

The customer asks	What happens
”Pay Acme $120 from Brex”	Names the account. Goes straight there.
”What’s my balance?”	Every account answers, each under its own name, in one reply.
”Pay Acme $120”, and two accounts could	Payman asks which one.
”Buy $50 of bitcoin”, and none can	Payman says so.

Naming the account in the instruction is enough. “from Brex”, “with my Coinbase”, “my Link wallet” all route without anyone being asked.

Two more answers

Both arrive as kind: "ok". They are questions, not failures, so keep them off your error path.

Which account?

agentStatus: "needs_provider". More than one account could do this, and the Wallet will not guess.

if (result.agentStatus === "needs_provider") {
  show(result.message);        // the question, ready to render
  offer(result.candidates);    // the accounts to pick from
}

Each candidate:

Field	Holds
provider	The account type, such as "BREX"
institutionName	The institution, such as "Brex"
accountLabel	Display name. Tells two accounts at one bank apart.
capabilities	One line on what this account can do.

Answer by sending the same instruction again with the account named:

await payman.forUser(userId).run(text, { provider: "BREX" });

Restating it in words (“Pay Acme $120 from Brex”) works too. What does not work is resending the identical instruction unchanged and expecting a different answer.

None of them can

agentStatus: "no_capable_provider". None of the customer’s accounts supports what was asked.

Show result.message. Do not retry, and do not quietly try a different account.

Both carry howToProceed: one plain line saying what to do next.

Adding an account

Two ways, both on Payman’s side:

• At consent. The customer ticks every account this app should reach, in one approval.
• Later. Connected apps in their Payman account, then Add a provider on your app’s row.

Nothing changes in your code either way. The connection you already hold reaches one more account on its next request.

Connecting is not a money task. If your agent asks run() to link or remove an account, Payman hands back the link to that page rather than doing it.

With a model in the loop

The tool already knows all of this. Its description tells the model how to read both answers, and its schema carries the optional provider field for naming an account. Nothing to add to your prompt.

Providers

What a customer can connect, and what each one does.

Actions

run(), the results, streaming.