Skip to main content
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

1

Open your mailbox

Sign in at console.mermail.app, then select the mailbox that should use the wallet.
2

Open Agent Wallet

Select Agent Wallet in the mailbox sidebar.
3

Start the connection

In PayBox connection, select Connect. Mermail sends you to PayBox through a secure OAuth flow.
4

Authorize PayBox

Sign in to PayBox and review the wallets and permissions you want to delegate. Approve the connection to return to Mermail.
5

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.
Mermail stores PayBox OAuth tokens encrypted on the server. It does not expose those tokens, private keys, or wallet secrets to your AI agent.

​
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:
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.
1

Select Funding

On the Agent Wallet page, select Funding.
2

Open the handoff

Mermail opens the PayBox checkout directly. If the browser blocks automatic navigation, select the single Open PayBox fallback link.
3

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

Check your portfolio

Return to Mermail and wait for the provider to finish processing. Agent Wallet refreshes balances automatically.
If Funding is unavailable, check that PayBox delegated an active Base wallet and that the secure portfolio view loaded successfully.

​
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:
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.
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.

​
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.
1

Ask for a transfer

In Agent Chat or a connected wallet-capable assistant, state the amount, network, and complete destination. For example:
2

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

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

Verify the result

Wait for a provider-confirmed success or transaction hash. pending and SUBMISSION_UNKNOWN are not success.

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

​
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

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.
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.
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.
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.
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.
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.
PayBox did not answer that refresh. The delegated connection is still active, so wait for the next refresh instead of disconnecting.

​
Next steps

Connect Agent Wallet to your AI

Choose Agent Chat, MCP, an Agent Skill, or the CLI.

Swap assets or use x402

Keep swaps, Funding, and paid-service authority separate.