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 delegated payer never sees EVM_PRIVATE_KEY: the CLI removes it from the child environment, since delegation exists precisely so that key is not used. 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.