Catalog token transfers

Every new Agent Wallet transfer uses paybox_request_transfer, including Circle USDC, native ETH/SOL, and reviewed catalog tokens. Read the current tool schema and portfolio before every request; do not reuse a stale schema or invent a fallback path. On full-profile OAuth, a current workspace member can use this live tool through the workspace owner’s active PayBox connection. The member remains the audited actor. This does not expose owner-only legacy proposal tools or connection management and does not broaden the exact transfer the member authorized.

Path	Tool	Amount field
New transfer, including USDC/native/catalog tokens	`paybox_request_transfer`	Exact live-schema amount field, commonly human `amount_decimal`
Explicit legacy USDC proposal management	`create_agent_wallet_transfer_proposal` then `submit_agent_wallet_transfer`	Human USDC `amount`; never use as a fallback for a normal send

Arguments for paybox_request_transfer

Field	Required	What to send
`chain`	Yes	CAIP-2 chain id, for example `eip155:8453` for Base
`token`	Yes	The asset’s contract address, or `native` for the chain asset. Read it from `paybox_get_portfolio` or `get_agent_wallet_portfolio`; the `token` field is visible to the model
`to`	Yes	The complete destination address
`amount_decimal`	Yes in practice	The human amount exactly as the user stated it, for example `1` or `0.000053389889845`
`amount`	Only as a fallback	Base units, accepted only when Mermail cannot resolve the asset’s decimals

{
  "chain": "eip155:8453",
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "to": "0xRecipientAddress",
  "amount_decimal": "1"
}

Never convert the amount to base units yourself. Mermail refuses an integer amount for any asset whose decimals it can resolve and answers paybox_amount_requires_decimal, because the same request has produced both the intended value and a 1000x-short one.

How Mermail reads the amount

Mermail resolves the asset’s decimals, converts amount_decimal to the smallest unit, and sends that to PayBox.

Circle USDC and chain native assets come from a built-in table.
Any other token is resolved through the pricing source (the DefiLlama coins API), cached briefly, and memoized once known.
If the lookup fails, Mermail falls back to the built-in table.
If no source can prove the decimals, Mermail rejects amount_decimal and asks for base units in amount instead. That is the only case where amount is the right field.

Value guards

The same resolved price protects against a scale mistake reaching the chain.

Guard	Effect
Dust floor	When Mermail has a trusted unit price, a transfer implying less than about $0.01 is rejected with `paybox_amount_below_dust_floor`. Ask the user for an amount worth at least$ 0.01, then retry with that `amount_decimal`
Declared value cross-check	If you also send `value_cents` and the implied USD value differs by more than 3x, Mermail rejects with `paybox_amount_value_mismatch`
Conflicting amounts	Sending `amount` and `amount_decimal` that disagree is rejected with `paybox_amount_scale_mismatch`. Send `amount_decimal` alone

The dust floor only fail-closes on a trusted quote (DefiLlama, including a recent memoized price, or a proven portfolio price). An ambiguous portfolio balance, or no price at all, fails open — so the amount still has to be correct.

Finishing the signature

paybox_request_transfer and an explicitly requested legacy submit_agent_wallet_transfer can both require PayBox interaction. Neither returns a signing plan or approval URL to a model. Those stay browser-only.

Through MCP, prefer the host-rendered PayBox MCP App. If it is unavailable or remains on Waiting without a usable action, paste one returned invocation-scoped signing_handoff.console_url. Never ask the user to paste a key or signature and never construct the URL from mailbox/invocation ids.
In Agent Chat, the response carries next_step: "finish_signing_in_paybox_transfer_widget" and the user signs in the PayBox widget shown in the conversation.

After the user signs, read provider status once with paybox_get_request. get_paybox_invocation is MCP audit state, not settlement evidence. Do not poll in a loop or restart the transfer to check status.

Errors and recovery

What each transfer error code means and the safe way to recover.

​Arguments for paybox_request_transfer

​How Mermail reads the amount

​Value guards

​Finishing the signature

Errors and recovery

Arguments for paybox_request_transfer

How Mermail reads the amount

Value guards

Finishing the signature