status: pending with a request_id is the normal result, not an execution failure. A human approves or denies from the dashboard and receives an email notification.
request_wallet_payment is the default way to pay. Use submit_approval_request only when you deliberately want a human to review before anything is spent, even below the auto-approve threshold. This needs only the approval:request scope. Budget and policy limits still apply; the tool cannot request an exception to them.
Both tools apply the same network-selection rules before requesting a human decision. For a new EVM recipient, ask for the network and supply caip2; do not guess. A CHAIN_REQUIRED refusal is not a queued approval: ask, then retry with the confirmed network and the same idempotency key. The approval card shows the selected network and whether it came from an explicit choice, this agent’s settled history, or Solana address format.
Decision and execution are separate
1
Human decision
The default decision window is 72 hours.
expires_at gives its deadline while the request is
pending. If nobody decides in time, the request becomes expired.2
Automatic execution
Approval starts the wallet payment automatically. The agent does not submit it again: it polls
the same
request_id while the status is executing.3
Settlement or failure
A payment becomes
settled only after confirmed finality on chain. It normally includes
on_chain_tx_hash. Rarely, confirmation is recorded but the provider’s hash could not be
captured: the hash is null, the payment is still final, and the agent must stop polling. An
execution failure becomes failed and includes failure_code and failure_reason.Track the request
Callget_payment_status with purpose and the returned request_id. Honor retry_after_seconds while pending or executing; it is null once the request is terminal. expires_at is null outside the pending decision window.
The delay is about 10 seconds for a new executing payment, then 30 seconds; pending starts at 30 seconds and backs off to 300 seconds as it waits. Add wait_seconds (integer 0–60, default 0) to long-poll for a status or step change; terminal results return immediately. A read timeout is not a payment outcome: retry with the same request_id.
The seven wallet-poll statuses are pending, executing, settled, failed, denied, expired, and not_found. The two write tools use the same statuses except not_found.
While executing, step can be funding_from_treasury, converting, submitting, confirming_on_chain, or awaiting_owner_signature. These are phases, not a strict sequence: submitting can appear before converting, and a step may repeat. Keep polling the same request_id, honoring retry_after_seconds or using wait_seconds. At awaiting_owner_signature, the owner must sign the next hop with their passkey; the agent cannot advance it. The step and its step_since timestamp reflect recorded progress; null means no recorded detail. Conversion and submission are still execution, not confirmed settlement.
See Payment Workflow for the complete status and field tables.
Denials teach the agent
The human can attach feedback to a denial. Readdenial_feedback on the poll response or call get_denial_feedback before changing the request. Automatic policy denials include an actionable denial_reason too.
limited_by and remaining_cents. Historical denials without that context return null for both. A denial does not permit the agent to bypass its spending limits.
Notifications
Approval requests notify the owner immediately through the dashboard feed and email. Mobile push and SMS arrive with the mobile app rollout. For your backend, developer webhooks are today’s push option:approval.completed reports an approval decision, but expired approvals produce no such webhook. Approval does not itself establish settlement; the agent keeps tracking execution through get_payment_status. Transaction webhooks currently lack payment request_id correlation and omit failure, expiry, and reversal outcomes, so they cannot replace that agent-side reconciliation; see webhook limits. Long-poll is the agent-side option. MCP resource subscriptions are a later design path with no promised date.