@x402api/agent-wallet-cli 0.2.2 → 0.2.4

package/README.md

@@ -4,15 +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.2.
+be updated in place in version 0.2.4.
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x402api/agent-wallet-cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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.2"
+    "@x402api/agent-wallet-core": "0.2.4"
   }
 }

package/skill/SKILL.md

@@ -80,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
@@ -104,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

@@ -34,7 +34,7 @@ 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.2 sets it only at wallet creation and
+daily or cumulative budget. Version 0.2.4 sets it only at wallet creation and
 does not provide a policy-update command.
 
 Unlocking commands additionally require `X402API_WALLET_PASSWORD_FILE` or an
@@ -95,13 +95,21 @@ when a merchant-specific integration owns the request lifecycle.
   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,34 @@ 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.
+
+## Programmatic charge handoff
+
+A merchant may create a variable-price challenge with the tenant-authenticated
+x402api `POST /v1/charges` endpoint before writing the wallet request envelope.
+That operation belongs to trusted merchant server code—not this wallet.
+
+- The merchant uses the current template `active_version.id` as
+  `resource_version_id`; a resource UUID or `pay_...` public payment ID is not a
+  substitute.
+- One active template may allow multiple rails. The merchant charge supplies
+  exact runtime amounts for a non-empty subset; the wallet independently
+  validates and selects one returned `PAYMENT-REQUIRED.accepts` alternative.
+- The request envelope receives only the exact credential-free protected
+  request and canonical `PAYMENT-REQUIRED` challenge. It never contains the
+  tenant API credential, `resource_version_id`, or a tenant-side API request.
+- Retiring or replacing a template is a merchant concern. The wallet validates
+  the exact issued challenge and must not discover, guess, or rewrite a
+  template UUID.
+
+See the tenant integration guide at
+https://x402api.com/docs/payments/x402/programmatic-charges.
 
 ## Payment submission or artifact handoff
 

package/skill/references/safety.md

@@ -9,7 +9,7 @@ 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.2
+artifacts, or protect a wallet on a compromised same-user host. Version 0.2.4
 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