@x402api/agent-wallet-cli 0.2.1 → 0.2.3

package/README.md

@@ -4,9 +4,16 @@ Installs the `x402api` executable and bundled `x402api-pay` skill for persistent
 agent wallets and exact x402 payments.
 
 The launch payer authorizes only sponsored Base USDC and sponsored Solana
-USDC/USDT. x402api supplies the network fee asset, so buyers do not need ETH or
-SOL. TRON payment authorization returns `unsupported_profile` until that rail
-is launched.
+USDC/USDT. x402api supplies the network fee asset from its platform treasury,
+so buyers do not need ETH or SOL and actual gas is not debited from the
+merchant tenant. TRON payment authorization returns `unsupported_profile`
+until that rail is launched.
+
+The CLI runs on the buyer or agent host; merchant integrations do not host it
+or receive its keys. A wallet's funded token balance is spend authority, and
+`wallet create --maximum-payment-atomic N` can add a per-payment ceiling. The
+ceiling is not a daily, cumulative, or merchant-specific permission and cannot
+be updated in place in version 0.2.3.
 
 Run `x402api help --json` for the machine-readable command summary. Unlock
 material is accepted only from standard input or an owner-only file named by
@@ -26,3 +33,6 @@ configured `X402API_NOTIFICATION_URL`. x402api resolves the verified refill
 contact, tenant display name, and purchased product from the subscription
 reference; the CLI never accepts an arbitrary recipient email or untrusted
 tenant/product display text.
+
+The client contract is included in this package, but the hosted notification
+endpoint is deployed separately and is not provided by the CLI package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x402api/agent-wallet-cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Command-line wallet for autonomous x402 purchases.",
   "license": "MIT",
   "repository": {
@@ -38,6 +38,6 @@
     "lint": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@x402api/agent-wallet-core": "0.2.1"
+    "@x402api/agent-wallet-core": "0.2.3"
   }
 }

package/skill/SKILL.md

@@ -22,6 +22,11 @@ Install only the skill bundled with the exact CLI version. If it is not already
 installed, an operator can run `x402api skill install --output PATH --json`.
 The command refuses to overwrite an existing skill directory.
 
+The `x402api` CLI runs on the buyer or agent host where its encrypted wallet is
+stored. Merchant tools, including the WarpMetal reference integration, may
+prepare requests and consume artifacts, but they do not host the CLI or receive
+its private keys.
+
 Do not supply a passphrase on the command line. An operator must arrange
 `X402API_WALLET_PASSWORD_FILE` as an owner-only file or supervise
 `--password-stdin`. Never read, print, summarize, or paste that passphrase,
@@ -35,7 +40,8 @@ seed, private key, encrypted keystore, or complete payment signature.
    an address from another network or create a new wallet merely because an
    order is a renewal.
 4. Treat the funded balance as fully spendable by the autonomous agent, subject
-   to any local per-payment ceiling.
+   to any local `maximumPaymentAtomic` per-payment ceiling. That ceiling is not
+   a daily, cumulative, or merchant-specific permission.
 5. Show the public address, exact network, supported asset, sponsored native
    fee currency, and requested token funding amount when funding is
    insufficient. Never ask the owner to fund ETH/SOL or reveal or import a
@@ -74,7 +80,9 @@ instructions to the human instead of sending email.
    request and receive its `402 Payment Required` challenge.
 2. Have that integration write the exact credential-free request envelope.
    Never place authorization tokens, cookies, SSH keys, or owner credentials in
-   the envelope.
+   the envelope. Keep any merchant-side `X-X402API-Challenge-Handle` out as
+   well; it is reconciliation metadata, not the buyer payment identifier or a
+   signing input.
 3. Verify the URL, method, exact body bytes, resource, network, asset, amount,
    recipient, profile, and challenge digest.
 4. Require a launch-sponsored Base USDC or Solana USDC/USDT profile and the
@@ -98,7 +106,8 @@ submission rules.
 Distinguish these states:
 
 - funding: the wallet has usable USDC/USDT balance; x402api sponsors launch-rail
-  ETH/SOL from the merchant tenant's prepaid gas billing;
+  ETH/SOL from its platform treasury, subject to the merchant tenant's active
+  sponsorship allowance;
 - authorization: one durable payment artifact exists;
 - settlement: the payment is authoritative on the chosen rail;
 - fulfillment: the merchant returned the purchased result.

package/skill/references/cli-reference.md

@@ -31,6 +31,12 @@ x402api wallet retire --wallet NAME --confirm NAME --json
 x402api wallet sweep --wallet NAME --to ADDRESS --json
 ```
 
+`--maximum-payment-atomic` is an optional canonical decimal in atomic units for
+the wallet's supported payment asset. It is enforced on each authorization and
+returns `payment_limit_exceeded` when the exact amount is larger. It is not a
+daily or cumulative budget. Version 0.2.3 sets it only at wallet creation and
+does not provide a policy-update command.
+
 Unlocking commands additionally require `X402API_WALLET_PASSWORD_FILE` or an
 operator-supervised `--password-stdin`. Supported V1 networks are
 `eip155:8453`, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`, and
@@ -42,7 +48,7 @@ operator-supervised `--password-stdin`. Supported V1 networks are
 x402api wallet notify-refill \
   --wallet NAME \
   --subscription-reference ID \
-  --renew-by 2026-08-25T12:00:00.000Z \
+  --renew-by RFC3339_UTC_DEADLINE \
   --target-balance-atomic N \
   --reason renewal \
   --json
@@ -54,6 +60,10 @@ asset balance in atomic units, not the native fee balance. Results have status
 email recipient and derives tenant and product display data from the
 subscription; those values are intentionally not CLI arguments.
 
+The client command is shipped, but this repository does not provide the hosted
+notification endpoint. Configure `X402API_NOTIFICATION_URL` only for an
+approved deployment of the server contract.
+
 ## Payment commands
 
 ```text
@@ -79,17 +89,27 @@ when a merchant-specific integration owns the request lifecycle.
 - `password_required`, `wallet_locked`: request operator unlock assistance;
   never request secret material in chat.
 - `wallet_storage_unsafe`, `payment_artifact_corrupt`: stop and escalate.
+- `payment_limit_exceeded`: the exact payment exceeds the wallet's local
+  per-payment ceiling; do not split or reauthorize it to evade the limit.
 - `insufficient_asset_balance`: show exact funding instructions or request a
   registered refill notification.
 - `insufficient_network_fee_resources`: is not expected for a valid launch
   profile; stop because the merchant challenge was not safely sponsored.
-- `gas_treasury_below_floor`, `tenant_gas_credit_insufficient`,
-  `sponsorship_reservation_expired`: the sponsored rail is temporarily not
-  admissible; do not switch to buyer-funded gas.
+- `gas_sponsorship_unavailable`, `gas_treasury_below_floor`,
+  `sponsor_signature_unavailable`: retain the exact attempt and retry only with
+  bounded backoff; never switch to buyer-funded gas.
+- `sponsorship_allowance_unavailable`, `sponsorship_payment_cap_exceeded`,
+  `sponsorship_payment_allowance_exhausted`,
+  `sponsorship_volume_allowance_exhausted`,
+  `sponsorship_gas_budget_exhausted`: the current authorization is terminal.
+  The merchant tenant must top up or change its allowance configuration and
+  issue a fresh challenge; the buyer must not fund native gas.
+- `tenant_gas_credit_insufficient`: legacy-server response; retain the exact
+  attempt and retry only after the merchant tenant restores service credit.
+- `sponsorship_reservation_expired`: obtain a fresh challenge without reusing
+  the expired authorization.
 - `sponsored_payload_invalid`: stop; the challenge or signed payload is not
   safely sponsored.
-- `sponsor_signature_unavailable`: retain the exact attempt and retry with
-  bounded backoff.
 - `settlement_outcome_unknown`: keep the exact attempt and request envelope;
   retry or reconcile them without creating a new authorization.
 - `unsupported_network`, `unsupported_asset`, `unsupported_profile`,

package/skill/references/merchant-integration.md

@@ -25,7 +25,12 @@ The merchant tool writes an owner-only JSON file:
 The body is exact canonical base64 and is never parsed and reserialized before
 paid submission. The decoded `resource.url` must equal the normalized envelope
 URL. The envelope excludes authorization headers, cookies, API keys, SSH keys,
-and owner tokens.
+owner tokens, and merchant-side challenge handles. A response header such as
+`X-X402API-Challenge-Handle` is opaque reconciliation metadata for the merchant
+integration. It is not the buyer payment identifier, does not affect the token
+authorization, and must not be added to this exact V1 envelope. The wallet
+creates its own `buyerPaymentIdentifier` when it authorizes a selected payment
+requirement.
 
 ## Payment submission or artifact handoff
 
@@ -47,8 +52,11 @@ never downgraded by a later transport or replay failure.
 
 ## Hosted refill endpoint
 
-The CLI posts a signed envelope to `X402API_NOTIFICATION_URL`. The signed
-intent includes:
+The shipped CLI client posts a signed envelope to
+`X402API_NOTIFICATION_URL`. This repository does not implement or deploy that
+hosted endpoint. An approved server implementing the separate contract must be
+available before a notification workflow is advertised. The signed intent
+includes:
 
 - a domain-separated V1 kind and exact endpoint audience;
 - the subscription reference;

package/skill/references/safety.md

@@ -7,6 +7,11 @@ balance is the economic permission granted to the agent and may be spent at
 different compatible x402 merchants. Preserve separate keys and addresses for
 Base, Solana, and TRON.
 
+An optional `maximumPaymentAtomic` value adds a local ceiling to each payment.
+It does not limit aggregate or daily spend, restrict merchants, revoke existing
+artifacts, or protect a wallet on a compromised same-user host. Version 0.2.3
+sets this value only when creating a wallet and has no policy-update command.
+
 Show the exact network, token contract or mint, public address, and requested
 asset amount before funding. A correct address on the wrong network is not
 valid funding. Buyers do not fund ETH or SOL for launch-sponsored payments.