> ## Documentation Index
> Fetch the complete documentation index at: https://paymanai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tabs>
  <Tab title="Which account?">
    `agentStatus: "needs_provider"`. More than one account could do this, and the Wallet will not guess.

    ```ts theme={null}
    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:

    ```ts theme={null}
    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.
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

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.

<Note>
  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.
</Note>

## With a model in the loop

The [tool](/build/tool-integration) 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.

<CardGroup cols={2}>
  <Card title="Providers" icon="building-columns" href="/reference/providers">
    What a customer can connect, and what each one does.
  </Card>

  <Card title="Actions" icon="bolt" href="/build/actions">
    run(), the results, streaming.
  </Card>
</CardGroup>