CLI reference
The --payer-cmd template explained.
--payer-cmd lets any wallet software pay the USDC charges the hosting API issues, by describing that wallet's pay command as a template. The cost of the hosting operation is unchanged — the template only decides which wallet signs the HTTP 402 payment challenge.
Synopsis
$ npx x402-hosting@latest renew --days 30 \
--payer-cmd 'mywallet pay {url} -X {method} -H {headers} --max {maxAmount}'Every paid command accepts the flag: deploy, renew, rollback, transfer, and delete. It is mutually exclusive with --payer — passing both is an error, because a custom wallet replaces the built-in payer modes rather than combining with them.
The placeholders
Each placeholder in the template becomes exactly one argument when the CLI builds the command — no shell is involved, so quoting and escaping are never interpreted:
{url}— the request URL to pay; required{headers}— the request headers as JSON; required, because they carry the key that payment recovery depends on{method}— the HTTP method of the request to pay{body}— the request body as JSON{maxAmount}— the amount quoted in the payment challenge, so the wallet can cap what it spends{operationId}— the client-generated operation id, for correlation
The CLI validates the template — builds the full argument vector — before any state is written, so a malformed template fails fast and can never strand a payment.
How the CLI invokes it
When a 402 challenge arrives, the CLI substitutes the placeholders, prints the delegated command it is about to run, and executes it from the project directory. The payer's own output is never parsed — the CLI watches the server-side operation, keyed by the operation id, as the source of truth for whether the payment settled.
A worked example
The built-in awal mode is itself a template, which makes it a good model for your own:
npx awal x402 pay {url} -X {method} -d {body} -h {headers} --max-amount {maxAmount} --correlation-id {operationId}Reconcile afterwards
If the payer command errors, the money may already have moved — do not retry blindly. Run finalize to ask the server what actually happened before paying again. The docs cover the recovery flow in full.