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

# Set up and use Agent Wallet

> Connect PayBox, view delegated balances, fund a wallet, and use PayBox tools.

This guide takes you from an empty Agent Wallet page to a connected wallet you
can view, fund, and use with your AI agent.

## Before you begin

You need:

* A Mermail workspace and mailbox.
* The **workspace owner** role to connect/reauthorize PayBox or use legacy
  Agent Wallet and CLI wallet commands. Current workspace members can use live
  model-visible `paybox_*` through the owner's active connection in a
  full-profile MCP host.
* A PayBox account with a wallet you can delegate.

## Connect PayBox

<Steps>
  <Step title="Open your mailbox">
    Sign in at [console.mermail.app](https://console.mermail.app), then select
    the mailbox that should use the wallet.
  </Step>

  <Step title="Open Agent Wallet">
    Select **Agent Wallet** in the mailbox sidebar.
  </Step>

  <Step title="Start the connection">
    In **PayBox connection**, select **Connect**. Mermail sends you to PayBox
    through a secure OAuth flow.
  </Step>

  <Step title="Authorize PayBox">
    Sign in to PayBox and review the wallets and permissions you want to
    delegate. Approve the connection to return to Mermail.
  </Step>

  <Step title="Confirm the connection">
    Check that **PayBox connection** shows **ACTIVE**. Your delegated wallets
    and balances appear under **Portfolio** and sync automatically.

    A brief **PAYBOX\_UNAVAILABLE** badge means PayBox did not answer that
    refresh. The connection is still active and the page keeps the balances it
    last loaded, so wait for the next refresh instead of reconnecting.
  </Step>
</Steps>

<Info>
  Mermail stores PayBox OAuth tokens encrypted on the server. It does not expose
  those tokens, private keys, or wallet secrets to your AI agent.
</Info>

### Connect or reauth from an AI host or the CLI

PayBox Connect and reauth always happen **inside Mermail**, not in Claude /
ChatGPT / Codex connector settings.

* `get_paybox_connection` and `get_agent_wallet` return `connect_handoff` when
  PayBox was never connected, and `reauth_handoff` when status is
  `REAUTH_REQUIRED`. Paste the `console_url` so the user can open Agent Wallet
  and select **Connect** / reconnect.
* A non-owner member receives `OWNER_ACTION_REQUIRED` with no handoff when the
  shared connection needs repair. Ask the workspace owner to complete the
  first-party Mermail flow; do not construct a URL or reconnect the host MCP
  connector.
* From the CLI:

```bash theme={null}
mermail wallet connect-url --mailbox-id MAILBOX_PUBLIC_ID
mermail wallet reauth-url --mailbox-id MAILBOX_PUBLIC_ID
```

Both print the Agent Wallet page URL. Do not reconnect the host Mermail MCP
connector for PayBox authorization — that only refreshes Mermail OAuth scopes.

## Fund a delegated wallet

The console can open a supported funding checkout for an eligible delegated
Base wallet.

<Steps>
  <Step title="Select Funding">
    On the **Agent Wallet** page, select **Funding**.
  </Step>

  <Step title="Open the handoff">
    Mermail opens the PayBox checkout directly. If the browser blocks automatic
    navigation, select the single **Open PayBox** fallback link.
  </Step>

  <Step title="Complete checkout">
    Follow the provider's steps to choose an amount and complete the purchase.
    The provider, currently MoonPay, handles the checkout and its eligibility
    requirements.
  </Step>

  <Step title="Check your portfolio">
    Return to Mermail and wait for the provider to finish processing. Agent
    Wallet refreshes balances automatically.
  </Step>
</Steps>

<Tip>
  If **Funding** is unavailable, check that PayBox delegated an active Base
  wallet and that the secure portfolio view loaded successfully.
</Tip>

### Funding from an AI host or the CLI

Secret checkout and approval URLs stay **browser-only**. MCP never returns them
to the model. Compatible hosts render the PayBox UI inline; other hosts use the
authenticated Mermail console deep link, which opens **Funding** automatically:

```text theme={null}
https://console.mermail.app/mailbox/{public_id}/agent-wallet?fund=1&amount={n}
```

`get_agent_wallet` and `paybox_get_buy_link` also return `funding_handoff`.
Prefer `get_agent_wallet` so `console_url` is bound to the correct mailbox. If
`needs_mailbox` is true, call `get_agent_wallet` with `mailboxId`; Mermail never
guesses a mailbox. Open `console_url` in a browser to complete MoonPay, then
refresh balances with `get_agent_wallet` or `get_agent_wallet_portfolio`.

From the CLI, `mermail wallet fund-url --mailbox-id {public_id} --amount 1`
prints the deep link without calling MoonPay.

<Warning>
  Funding is not spending authority. A link with `amount=1` pre-fills 1 USD of
  fiat; it does not guarantee 1 USDC and does not authorize a later transfer,
  swap, or x402 payment. After checkout, read the actual balance once and treat
  every spending request as a separate action.
</Warning>

## Make a transfer with your agent

Agent Wallet exposes PayBox's live tools. PayBox decides which assets, networks,
and actions are available under the wallets and standing grants you delegated.
Every new transfer, including Circle USDC, uses `paybox_request_transfer`.
Legacy USDC proposal tools are not a fallback for an ordinary send.

<Steps>
  <Step title="Ask for a transfer">
    In Agent Chat or a connected wallet-capable assistant, state the amount,
    network, and complete destination. For example:

    ```text theme={null}
    Transfer 5 USDC on Base to 0xRecipientAddress using PayBox.
    ```
  </Step>

  <Step title="Review in PayBox when requested">
    If PayBox requires interaction, verify the amount, network, and full
    destination in its inline signing UI or authenticated browser handoff.
  </Step>

  <Step title="Complete PayBox signing">
    Complete any passkey, signing-key, or approval step that PayBox requires.
    If the assistant pastes a `signing_handoff.console_url`, open that link on
    Agent Wallet to sign in PayBox. An existing standing grant may allow the
    action to continue without a fresh click.
  </Step>

  <Step title="Verify the result">
    Wait for a provider-confirmed success or transaction hash. `pending` and
    `SUBMISSION_UNKNOWN` are not success.
  </Step>
</Steps>

### Transfer tool and signing handoff

Your AI reads the live `paybox_request_transfer` schema, resolves the exact
credential and portfolio asset, and sends the human-authorized amount without
inventing omitted fields. See
[catalog token transfers](/agent-wallet/catalog-transfers) for the full contract.

When signing is required, prefer the PayBox MCP App displayed in the
conversation. If the frame does not appear or remains on **Waiting** without a
signing action, open the single invocation-scoped
`signing_handoff.console_url` returned by the tool. Do not derive it from a
mailbox or invocation id; `mermail wallet sign-url` is retired.

After you confirm signing, the assistant may read the known provider request
once with `paybox_get_request`. `get_paybox_invocation` is audit state and does
not prove settlement.

<Warning>
  Do not retry an uncertain transfer automatically. Check the request status and
  destination wallet first to avoid sending the same payment twice. If PayBox
  rejected the send outright — for example a nonce that is too low or a signing
  plan that went stale — ask for a **new** transfer rather than reusing the old
  request.
</Warning>

## Disconnect PayBox

To remove wallet access, open **Agent Wallet** and select **Disconnect** in the
**PayBox connection** section. Your Mermail mailbox remains active, but Agent
Wallet can no longer read delegated balances or prepare PayBox actions until
you reconnect.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The connection was cancelled or expired">
    Return to **Agent Wallet**, select **Connect**, and complete the PayBox flow
    in the same browser session. If an AI pasted `reauth_handoff.console_url` or
    `connect_handoff.console_url`, open that Mermail link — do not reconnect the
    Claude, ChatGPT, or Codex Mermail connector for PayBox.
  </Accordion>

  <Accordion title="My balance has not updated">
    Allow the funding provider time to finish processing, then reload the Agent
    Wallet page. Do not treat an open or pending checkout as a completed
    deposit.
  </Accordion>

  <Accordion title="My AI client cannot see wallet tools">
    Reconnect the default full `/mcp` endpoint with OAuth and grant core
    `mcp:tools`. Current workspace members can see live tools only while the
    owner's PayBox connection is active; owner-only legacy tools additionally
    require the owner role. Legacy `wallet:read` and `wallet:transact` labels
    are not required. API keys and the agent-inbox profile cannot expose wallet
    tools.
  </Accordion>

  <Accordion title="A transfer is still pending">
    Reconcile the known request once instead of submitting it again. A clearly
    distinct new transfer is a separate action with a new request id; repeating
    identical terms requires an explicit “another” instruction.
  </Accordion>

  <Accordion title="PayBox rejected the transfer">
    A rejected send is different from a pending one. Verify that nothing left
    the wallet, then ask for a new transfer; the previous request cannot be
    resumed. See [errors and recovery](/agent-wallet/errors-and-recovery).
  </Accordion>

  <Accordion title="My agent keeps retrying the amount">
    Mermail rejects a base-unit amount for assets it can price and asks for
    `amount_decimal`. Restate the amount in plain units, such as `1 USDC`, and
    see [catalog token transfers](/agent-wallet/catalog-transfers).
  </Accordion>

  <Accordion title="The connection badge shows PAYBOX_UNAVAILABLE">
    PayBox did not answer that refresh. The delegated connection is still
    active, so wait for the next refresh instead of disconnecting.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Connect Agent Wallet to your AI" icon="sparkles" href="/agent-wallet/use-with-ai">
    Choose Agent Chat, MCP, an Agent Skill, or the CLI.
  </Card>

  <Card title="Swap assets or use x402" icon="arrows-rotate" href="/agent-wallet/swaps-and-x402">
    Keep swaps, Funding, and paid-service authority separate.
  </Card>
</CardGroup>