CLI reference
x402-hosting finalize: command reference.
finalize reconciles a pending payment handoff by asking the server what actually happened — without paying again. It costs nothing and takes no flags.
Synopsis
$ npx x402-hosting@latest finalize
Run it from the directory where the interrupted command ran. It requires a pending x402-hosting.payment.json handoff file; without one it exits with an error, because there is nothing to reconcile.
What a handoff is
When a payment cannot be signed inline — the external payer mode, or a delegated wallet through --payer-cmd — the CLI writes x402-hosting.payment.json into the project directory. That file holds the exact request to pay, the payment requirements from the HTTP 402 challenge, the amount, and the client-generated operation id. Do not commit it, and never delete it by hand: while one exists, deploy refuses to run, which is what stops a second payment for the same work.
Running finalize
Pay the handoff once with any x402 wallet, resending the headers verbatim, then run finalize. It looks up the operation id the server already knows about and reports one of three outcomes:
- The paid work is finished — finalize completes it locally
- No payment was ever recorded — the handoff is cleared and retrying is safe
- The operation failed after settling — check the wallet's receipts before paying again, because the charge may still have gone through
For a first deploy there are two paid steps — the $0.01 upload and the duration price — so the external path takes two rounds of pay-then-finalize before the project activates. There is never a second charge for the same step: finalize reconciles by operation id alone.
When to run it — and when not to
Run finalize after any interrupted paid command: a crashed wallet, a lost network connection, a payer command that errored after the money may have moved. Do not run it to cancel a payment you have not made — if nothing was ever recorded, the server says so and the handoff is cleared, but the fix for an abandoned plan is simply not paying. And do not run it mid-flight while a delegated payer is still working; let the operation reach a terminal state first. The recovery model is described in how agents recover interrupted payments and in the docs.