Agents
How agents recover interrupted payments.
When an agent run is interrupted in the middle of a payment — a crash, a timeout, a killed process — the finalize command is the recovery path. It re-checks whether the payment settled and completes the pending operation without charging again, so an unattended run can never double-charge by accident.
How a payment gets interrupted
Most payments happen inside the CLI, but agent setups often hand the payment to an external wallet. With --payer external or a --payer-cmd template, the CLI passes the HTTP 402 challenge to another process that signs and pays it. That handoff is where interruptions live: the external payer can crash after settling but before the CLI sees the result, or the agent itself can be stopped while waiting. The operation is left pending, and the agent cannot tell from memory whether money moved.
The --payer-cmd template makes the handoff explicit: the CLI substitutes placeholders such as {url}, {method}, {body}, {headers}, and {maxAmount} into a shell command that performs the payment. More moving parts means more places to interrupt — and more reason the recovery path has to be deterministic.
What finalize does
$ npx x402-hosting@latest finalize
The command asks the API to reconcile the pending operation. If the payment settled, the operation — a deploy, a renewal, a transfer — completes and the agent gets the result it was waiting for. If the payment never settled, nothing was spent and the operation can be retried safely. Either way, finalize never triggers a new payment. It only finishes what an earlier payment already started.
When to run it
Run finalize whenever a paid operation ended without a clear result: after a crash, a timeout, or a payer error, and before attempting the same operation again. Retrying blindly is the only way to pay twice; checking first is free. The finalize command reference covers the exact invocation, and the documentation describes the pending-operation lifecycle.
Why this makes unattended runs safe
An agent that runs overnight will eventually hit a bad network or a dead process. Deterministic recovery turns that from a billing risk into a retry. Combined with fixed USDC pricing and free status reads, finalize means the worst case of any interrupted run is a paused task, never a duplicated charge.
The same discipline applies to the first deploy's thirty-minute activation window. If the upload payment settled but the run died before activation, finalize is how the agent finds out and finishes the job — instead of discovering the torn-down project after the window closed and losing the $0.01.
Recovery rules
- finalize re-checks settlement instead of paying again
- A settled payment completes the pending operation
- An unsettled payment means nothing was spent; retry safely
- Always finalize before re-attempting a paid operation
- Status reads are free, so verification costs nothing