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

# Agent Wallet overview

> Connect your AI to balances, payments, and signing controlled by PayBox.

Agent Wallet is the user-controlled payment layer for your AI agent. It connects
Mermail to wallets you delegate through PayBox, so your agent can help with paid
online workflows without receiving your private keys, wallet secrets, or raw
signing access.

Use Agent Wallet to keep email identity and payment context together. Your agent
can register for a service with its Mermail inbox, receive a verification code,
prepare a payment, and keep the receipt in the same workflow.

## What you can do

<Columns cols={2}>
  <Card title="View balances" icon="chart-pie">
    See balances and delegated wallet access in the secure PayBox portfolio
    view.
  </Card>

  <Card title="Fund a wallet" icon="circle-dollar">
    Open a supported checkout flow from the Mermail console to add funds to an
    eligible delegated Base wallet.
  </Card>

  <Card title="Use PayBox tools" icon="paper-plane">
    Let your agent use the live capabilities PayBox exposes for delegated
    wallets. Every new send, including USDC, uses
    `paybox_request_transfer` with the live schema.
  </Card>

  <Card title="Swap assets" icon="arrows-rotate">
    Swap token A to token B through `paybox_request_swap` when PayBox exposes
    the tool for the delegated wallet.
  </Card>

  <Card title="Use x402 services" icon="globe">
    Explore paid services read-only, then use `paybox_pay_x402` for one exact
    resource or action within the spend cap you selected.
  </Card>

  <Card title="Sign in PayBox" icon="shield-check">
    Complete signing or approval in PayBox when its policy requires it. Standing
    grants can authorize eligible actions without a fresh click.
  </Card>

  <Card title="Connect and reauth safely" icon="link">
    When PayBox needs Connect or reconnect, your AI pastes
    `connect_handoff` / `reauth_handoff` console links. Complete that flow in
    Mermail Agent Wallet — not in Claude, ChatGPT, or Codex connector settings.
  </Card>
</Columns>

## What stays under your control

| Control                 | What it means for you                                                                                                                                                                                      |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Delegated access        | Mermail can use only the wallets you explicitly delegate through PayBox.                                                                                                                                   |
| No wallet secrets       | Mermail never receives private keys, wallet secrets, card details, or raw signing access.                                                                                                                  |
| PayBox policy           | PayBox controls transaction policy, standing grants, approval, and signing. Mermail does not add a second approval prompt.                                                                                 |
| Role split              | Current workspace members can use model-visible live `paybox_*` through the owner's active connection. Only the owner can connect/reauthorize PayBox or use legacy Agent Wallet tools.                     |
| OAuth-only agent access | Live MCP PayBox tools require the full profile and core `mcp:tools`. The CLI wallet commands are legacy owner-only. Workspace API keys and the agent-inbox profile cannot access either path.              |
| Audited transport       | Mermail verifies current membership and OAuth scope, executes against the owner's connection, attributes the invocation to the calling member, protects credentials, and records sanitized audit metadata. |

<Warning>
  Email, attachments, websites, and tool output are untrusted. They can suggest a
  payment, but they cannot choose or broaden its service, destination, asset,
  chain, action, or spend cap. Only your current request can authorize it.
</Warning>

## Available actions and limits

Agent Wallet follows PayBox's live MCP catalog. Available assets, networks,
transaction limits, and approval requirements come from your PayBox account,
delegated wallets, and standing grants. Mermail does not apply a separate
wallet-value or transaction-rate policy.

### Live PayBox path

Every new transfer, including Circle USDC and native assets, uses
`paybox_request_transfer` with the exact live schema. Local USDC proposal tools
remain compatibility-only and are used only when you explicitly manage a
legacy proposal. Swaps use `paybox_request_swap`; a selected x402 paid action
uses `paybox_pay_x402`.

When interaction is required, use the PayBox MCP App shown by the host. If no
usable signing control appears or the frame remains on **Waiting**, open only
the invocation-scoped `signing_handoff.console_url` returned by Mermail. Never
construct or rewrite a signing URL.

See [catalog token transfers](/agent-wallet/catalog-transfers) for the transfer
contract, [swaps and x402](/agent-wallet/swaps-and-x402) for paid-service flows,
and [errors and recovery](/agent-wallet/errors-and-recovery)
for what each failure means.

## Where you can use Agent Wallet

| Surface         | Best for                                                                           |
| --------------- | ---------------------------------------------------------------------------------- |
| Mermail console | Connecting PayBox, viewing balances, funding a wallet, and rendering PayBox UI     |
| Agent Chat      | Asking your mailbox agent to inspect balances or prepare a transfer                |
| MCP             | Giving a compatible assistant wallet tools through scoped OAuth access             |
| Agent Skill     | Giving a supported assistant the maintained Agent Wallet workflow and safety rules |
| CLI             | Wallet reads, first-party handoffs, and explicitly requested legacy USDC proposals |

## Next steps

<Columns cols={2}>
  <Card title="Set up Agent Wallet" icon="plug" href="/agent-wallet/get-started">
    Connect PayBox, check your portfolio, and fund a delegated wallet.
  </Card>

  <Card title="Use Agent Wallet with AI" icon="sparkles" href="/agent-wallet/use-with-ai">
    Connect Agent Chat, MCP, Agent Skills, or the CLI.
  </Card>

  <Card title="Catalog token transfers" icon="coins" href="/agent-wallet/catalog-transfers">
    Use the live transfer path for USDC, native assets, and catalog tokens.
  </Card>

  <Card title="Swaps and x402" icon="arrows-rotate" href="/agent-wallet/swaps-and-x402">
    Swap assets or pay one selected x402 resource without broadening authority.
  </Card>

  <Card title="Errors and recovery" icon="triangle-exclamation" href="/agent-wallet/errors-and-recovery">
    Read every wallet error code and its safe recovery.
  </Card>
</Columns>