@cloudpayx/x402-pay 0.2.4 → 0.2.5

package/AGENTS.md

@@ -0,0 +1,53 @@
+# Autonomous Agent Integration — cloudpayX
+
+**One SDK. Two capabilities. Three XRPL assets.**
+
+Package: `@cloudpayx/x402-pay`
+Install: `npm install @cloudpayx/x402-pay`
+Network: XRPL mainnet (`xrpl:0`)
+Protocol: x402 V2 exact
+Assets: XRP, RLUSD, Circle USDC
+
+No mandatory cloudpayX account, dashboard, subscription, or wallet brand.
+
+## Discover
+
+Read `README.md`, `docs/QUICKSTART.md`, `docs/API.md`,
+and `types/public-node.d.ts`.
+
+Use package-root exports only:
+- validateSecureNodePurchase
+- executeSecureNodePurchase
+- reconcileSecureNodePurchase
+- createCpXAgentEarn
+
+## BUY workflow
+
+1. Identify the seller, resource, exact price, asset, and invoice.
+2. Obtain a compatible signer and explicit spending authorization.
+3. Set per-asset budgets, fee ceiling, and one-shot constraints.
+4. Use a durable private journal and unique intent ID.
+5. Validate configuration before executing the authorized purchase.
+6. Reconcile the original intent before claiming XRPL settlement.
+7. Never retry an uncertain signed payment automatically.
+
+Public Pay execution requires HTTP POST.
+
+## SELL workflow
+
+1. Choose a receiving wallet and supported XRPL asset.
+2. Set amount, invoice ID, destination tag, and HTTPS facilitator.
+3. Configure persistent replay and transaction journal storage.
+4. Create the endpoint using createCpXAgentEarn.
+5. Call initialize(), then forward requests to handle().
+6. Deliver paid resources only through onPaid.
+
+## Safety
+
+Never publish seeds, private keys, or signing credentials.
+Never treat HTTP success alone as validated XRPL settlement.
+Never bypass authorization, spending caps, or replay protection.
+Never substitute Base/EVM assets for XRPL assets.
+Never change SDK payment internals just to simplify integration.
+
+The SDK is free to install; XRPL fees and paid services are not free.

package/README.md

@@ -1,6 +1,10 @@
-# cpX x402 Pay
+# cpX x402 Pay + Earn
 
-**XRPL-native x402 payments for autonomous AI agents.**
+**XRPL-native payment infrastructure for autonomous AI agents.**
+
+**One SDK. Two capabilities. Three XRPL assets.**
+
+`npm install @cloudpayx/x402-pay`
 
 cpX x402 Pay enables autonomous AI agents to purchase x402-protected services using XRP, RLUSD, and Circle USDC on the XRP Ledger.
 
@@ -8,12 +12,20 @@ The SDK provides wallet-agnostic signing integration, explicit payment authoriza
 
 Self-funded agents can integrate without a cloudpayX account, dashboard, or mandatory wallet provider.
 
+## Developer and agent integration guides
+
+- [Quick Start](docs/QUICKSTART.md)
+- [API Reference](docs/API.md)
+- [Agent Instructions](AGENTS.md)
+- [Machine-readable Manifest](docs/agent-manifest.json)
+- [Earn HTTP Example](examples/earn-http-server.mjs)
+
 ## Installation
 
 `npm install @cloudpayx/x402-pay`
 
-**Network:** XRPL mainnet (`xrpl:0`)  
-**Protocol:** x402 V2, `exact`  
+**Network:** XRPL mainnet (`xrpl:0`)
+**Protocol:** x402 V2, `exact`
 **Assets:** XRP, RLUSD, Circle USDC
 
 ## Quick start: validate a payment configuration
@@ -33,6 +45,16 @@ Validation confirms the guarded configuration structure. It does not authorize a
 
 For live integration, replace the placeholders with a compatible XRPL signer, real payment details, and your own authorization policy. Use `executeSecureNodePurchase()` for execution and `reconcileSecureNodePurchase()` for settlement verification.
 
+## cpX x402 Earn — Agent monetization
+
+Turn agent capabilities into paid services with XRPL-native settlement.
+
+cpX x402 Earn verifies payment requirements, enforces persistent replay protection, checks transaction identity, and independently confirms XRPL ledger settlement before delivering protected resources.
+
+**Security by design:** Unsupported payment-processing sequences are rejected rather than permitted to bypass settlement verification.
+
+The public SDK exposes `createCpXAgentEarn()` for configuring a protected XRPL payment endpoint.
+
 ## Capabilities
 
 - **Autonomous agent payments:** Agents can purchase compatible x402 resources using their own XRPL signing infrastructure.
@@ -54,6 +76,7 @@ Import the guarded payment operations from `@cloudpayx/x402-pay`.
 | `validateSecureNodePurchase` | Validate a proposed guarded payment configuration. |
 | `executeSecureNodePurchase` | Execute a policy-controlled XRPL x402 purchase. |
 | `reconcileSecureNodePurchase` | Reconcile an existing purchase against validated XRPL ledger evidence. |
+| `createCpXAgentEarn` | Protect and monetize agent services with verified XRPL settlement. |
 
 Payment execution requires compatible signing infrastructure and application-supplied authorization and policy configuration.
 

package/README.pre-pay-earn-release.bak

@@ -0,0 +1,96 @@
+# cpX x402 Pay
+
+**XRPL-native x402 payments for autonomous AI agents.**
+
+cpX x402 Pay enables autonomous AI agents to purchase x402-protected services using XRP, RLUSD, and Circle USDC on the XRP Ledger.
+
+The SDK provides wallet-agnostic signing integration, explicit payment authorization, spending controls, guarded transactions, persistent payment tracking, and validated-ledger settlement reconciliation.
+
+Self-funded agents can integrate without a cloudpayX account, dashboard, or mandatory wallet provider.
+
+## Installation
+
+`npm install @cloudpayx/x402-pay`
+
+**Network:** XRPL mainnet (`xrpl:0`)
+**Protocol:** x402 V2, `exact`
+**Assets:** XRP, RLUSD, Circle USDC
+
+## Quick start: validate a payment configuration
+
+Start with a no-wallet example before connecting a live XRPL signer.
+
+From the SDK project:
+
+    npm install
+    node examples/quickstart-validation.mjs
+
+The example imports the published SDK interface, configures an XRP purchase, and calls `validateSecureNodePurchase()`.
+
+It uses placeholder addresses and a signer that refuses to sign. **No funds move.**
+
+Validation confirms the guarded configuration structure. It does not authorize a payment, validate an address checksum, or verify settlement.
+
+For live integration, replace the placeholders with a compatible XRPL signer, real payment details, and your own authorization policy. Use `executeSecureNodePurchase()` for execution and `reconcileSecureNodePurchase()` for settlement verification.
+
+## Capabilities
+
+- **Autonomous agent payments:** Agents can purchase compatible x402 resources using their own XRPL signing infrastructure.
+- **Wallet-agnostic integration:** No mandatory wallet brand or cloudpayX custody.
+- **Three-asset support:** Native XRP, Ripple-issued RLUSD, and Circle-issued USDC with issuer validation.
+- **Payment authorization:** Explicit autonomous opt-in or application-controlled approval.
+- **Spending controls:** Per-asset limits, persistent aggregate budgets, recipient restrictions, and transaction fee ceilings.
+- **Guarded signing:** Checks transaction destination, asset, amount, invoice binding, fees, and other transaction constraints.
+- **Durable payment records:** Persistent journals and duplicate-payment protections.
+- **Settlement verification:** Reconciliation against validated XRPL transaction evidence.
+- **Protected resource access:** HTTPS validation, anti-SSRF protections, and redirect restrictions.
+
+## Public SDK API
+
+Import the guarded payment operations from `@cloudpayx/x402-pay`.
+
+| Export | Purpose |
+| --- | --- |
+| `validateSecureNodePurchase` | Validate a proposed guarded payment configuration. |
+| `executeSecureNodePurchase` | Execute a policy-controlled XRPL x402 purchase. |
+| `reconcileSecureNodePurchase` | Reconcile an existing purchase against validated XRPL ledger evidence. |
+
+Payment execution requires compatible signing infrastructure and application-supplied authorization and policy configuration.
+
+## Supported assets
+
+| Asset | Network | Amount format |
+| --- | --- | --- |
+| XRP | XRPL mainnet | Integer drops |
+| RLUSD | XRPL mainnet | Decimal token amounts, Ripple issuer-bound |
+| Circle USDC | XRPL mainnet | Decimal token amounts, Circle issuer-bound |
+
+**cpX x402 Pay is XRPL-only.** It does not execute Base/EVM payments, automatically swap tokens, or substitute unrelated assets with similar names.
+
+## Payment lifecycle
+
+1. An agent requests an x402-protected resource.
+2. The resource returns payment requirements.
+3. The SDK validates the payment requirements and configured spending authorization.
+4. The guarded transaction is signed and submitted through the payment flow.
+5. Purchase state and transaction evidence are preserved.
+6. Ledger reconciliation verifies the settlement outcome.
+
+Uncertain payment results require reconciliation rather than automatic duplicate payment attempts.
+
+## Security architecture
+
+The guarded SDK interface incorporates explicit authorization, spending budgets, transaction-signing restrictions, invoice binding, issuer validation, fee controls, duplicate-payment protection, safe resource-host validation, and ledger reconciliation.
+
+Applications must secure their XRPL signing credentials independently. An agent with unrestricted access to wallet keys can bypass local SDK policies outside the guarded interface.
+
+Issued-token payments require applicable trustlines, sufficient balances, and XRP for network fees and reserves. Third-party resource delivery depends on the seller and network conditions.
+
+## Resources
+
+- Website: https://cloudpayx.com
+- Agent infrastructure: https://api.cloudpayxagent.xyz
+- npm: https://www.npmjs.com/package/@cloudpayx/x402-pay
+- XRPL x402 specification: https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_xrpl.md
+
+**cloudpayX | Infrastructure for the autonomous economy**

package/docs/API.md

@@ -0,0 +1,76 @@
+# cpX x402 Pay + Earn — Public API
+
+Package: `@cloudpayx/x402-pay`
+Network: XRPL mainnet only (`xrpl:0`).
+
+## Pay
+
+`validateSecureNodePurchase(options)` returns true or throws.
+It validates configuration shape, not settlement or authorization.
+
+`executeSecureNodePurchase(options)` starts at most one guarded purchase.
+Its response includes:
+- status: `HTTP_RESPONSE_LEDGER_UNVERIFIED`
+- httpStatus
+- paymentResponseHeaderPresent
+- journalStatus
+
+Required options:
+- intent: intentId, payer, seller, resource, asset, amount
+- journalDir: private durable directory
+- budgetCaps: xrpDrops, rlusd, usdc (positive strings)
+- signer: matching classicAddress and sign function
+- policy: explicit payment authorization configuration
+- oneShot: recipient, asset, exactAmount, maxFeeDrops
+- maxFeeDrops: positive string matching oneShot
+- request: matching URL, POST method, string body
+
+For issued tokens, oneShot additionally requires issuer and maxSendMax.
+Optional timeoutMs: 1–60000, default 20000.
+
+Initial requests cannot contain payment-signature, x-payment,
+authorization, or cookie headers.
+
+`reconcileSecureNodePurchase({ journalDir, intentId })` performs read-only
+ledger recovery. Successful results contain:
+- status: VALIDATED_SUCCESS
+- transactionHash
+- ledgerIndex
+- deliveredAmount
+- asset
+- feeDrops
+- invoiceID
+
+Reconciliation never resubmits a transaction.
+
+## Earn
+
+`createCpXAgentEarn(options)` accepts:
+- walletAddress: valid XRPL classic receiving address
+- asset: XRP, RLUSD, or USDC
+- amount: positive string (XRP in drops)
+- invoiceId: 1–256 characters
+- destinationTag: integer 0–4294967295
+- facilitatorUrl: HTTPS URL
+- journalDir: persistent private directory
+- onPaid: (request, settlement) => Response or Promise<Response>
+- method: GET or POST, optional; default POST
+- path: valid route, optional; default /paid
+
+Returns:
+- initialize(): initialize x402 resource server
+- handle(request): process Fetch API Request and return Response
+
+Earn uses proof replay protection, transaction identity checks, and
+validated-ledger verification before paid resource delivery.
+Unsupported processing sequences fail closed.
+
+## Asset identifiers
+
+RLUSD issuer: rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De
+USDC issuer: rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE
+
+This SDK does not support Base/EVM settlement.
+Do not expose wallet secrets or bypass public guarded APIs.
+
+Canonical TypeScript signatures: `types/public-node.d.ts`.

package/docs/QUICKSTART.md

@@ -0,0 +1,72 @@
+# cpX x402 Pay + Earn — Quick Start
+
+**One SDK. Two capabilities. Three XRPL assets.**
+
+Install: `npm install @cloudpayx/x402-pay`
+
+Network: XRPL mainnet (`xrpl:0`).
+Protocol: x402 V2, exact.
+Assets: XRP, Ripple RLUSD, Circle USDC.
+
+No mandatory cloudpayX account, subscription, dashboard, or wallet provider.
+XRPL fees, purchased services, and third-party facilitator charges may apply.
+
+## Pay — Buy agent services
+
+Import `validateSecureNodePurchase`, `executeSecureNodePurchase`, and
+`reconcileSecureNodePurchase` from `@cloudpayx/x402-pay`.
+
+Start with `node examples/quickstart-validation.mjs` in the source repository.
+This validates configuration without moving funds.
+
+For an authorized live purchase, provide:
+- Stable unique intent ID (at least 12 characters)
+- Payer, seller, public HTTPS resource, asset, and exact amount
+- Compatible XRPL signer with matching classicAddress
+- Explicit authorization policy and recipient restrictions
+- Positive persistent budgets for XRP drops, RLUSD, and USDC
+- One-shot guard matching recipient, asset, amount, and fee ceiling
+- Issuer and maxSendMax for RLUSD or USDC
+- Private durable journal directory
+- POST request with a string body
+
+Call `validateSecureNodePurchase(options)` to check configuration.
+Call `executeSecureNodePurchase(options)` only after authorization.
+
+An HTTP response is NOT verified XRPL settlement.
+
+For an existing journaled purchase:
+
+    import { reconcileSecureNodePurchase } from "@cloudpayx/x402-pay";
+
+    const receipt = await reconcileSecureNodePurchase({
+      journalDir: "./private-payment-journal",
+      intentId: "original-unique-intent-id"
+    });
+
+Only a `VALIDATED_SUCCESS` receipt establishes settlement through this API.
+Never automatically repeat a payment after a timeout or uncertain outcome.
+
+## Earn — Sell agent services
+
+Import `createCpXAgentEarn` from `@cloudpayx/x402-pay`.
+
+Configure a receiving wallet, asset, positive amount, invoice ID,
+destination tag, HTTPS facilitator, durable journal, and `onPaid` callback.
+
+Call `initialize()` before routing incoming Fetch API Request objects
+through `handle(request)`. Return the resulting Response to the caller.
+
+See `examples/earn-http-server.mjs` for a Node HTTP adapter.
+The paid service must only be delivered from `onPaid`.
+
+## Amounts
+
+- XRP: positive integer drops (1 XRP = 1,000,000 drops).
+- RLUSD: positive decimal units, Ripple issuer.
+- USDC: positive decimal units, Circle issuer.
+
+Issued-token wallets need the applicable trustlines, balances, and XRP
+for fees and reserves.
+
+See `docs/API.md` and `AGENTS.md`.

package/docs/agent-manifest.json

@@ -0,0 +1,51 @@
+{
+  "name": "cpX x402 Pay + Earn",
+  "provider": "cloudpayX",
+  "package": "@cloudpayx/x402-pay",
+  "network": "xrpl:0",
+  "protocol": {
+    "name": "x402",
+    "version": 2,
+    "scheme": "exact"
+  },
+  "assets": [
+    {
+      "symbol": "XRP",
+      "unit": "drops"
+    },
+    {
+      "symbol": "RLUSD",
+      "issuer": "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De"
+    },
+    {
+      "symbol": "USDC",
+      "issuer": "rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE"
+    }
+  ],
+  "pay": {
+    "exports": [
+      "validateSecureNodePurchase",
+      "executeSecureNodePurchase",
+      "reconcileSecureNodePurchase"
+    ],
+    "httpMethod": "POST",
+    "requiresSigner": true,
+    "requiresAuthorization": true
+  },
+  "earn": {
+    "export": "createCpXAgentEarn",
+    "httpMethods": [
+      "GET",
+      "POST"
+    ],
+    "requiresHttpsFacilitator": true,
+    "requiresValidatedSettlement": true
+  },
+  "documentation": [
+    "README.md",
+    "docs/QUICKSTART.md",
+    "docs/API.md",
+    "AGENTS.md"
+  ],
+  "cloudpayxAccountRequired": false
+}

package/docs/agent-onboarding.md

@@ -0,0 +1,236 @@
+# cpX x402 Pay | Autonomous Agent Onboarding
+
+Network: XRPL mainnet (xrpl:0)
+Protocol: x402 V2, exact
+SDK: @cloudpayx/x402-pay
+Status: Integration guidance
+Custody: None
+
+## Purpose
+
+This guide helps autonomous agents prepare their own XRPL wallets
+to purchase x402-protected resources through cpX x402 Pay.
+
+cloudpayX does not create wallets, hold private keys, fund accounts,
+or independently authorize an agent's spending.
+
+An agent may use its own wallet infrastructure or an existing
+compatible XRPL wallet signer.
+
+## 1. Prepare an XRPL wallet
+
+If you already control an XRPL wallet, continue to Step 2.
+
+Otherwise:
+
+1. Choose an existing XRPL-compatible wallet or wallet library.
+2. Generate credentials using that wallet's own secure process.
+3. Keep private keys and recovery credentials under your control.
+4. Obtain the wallet's XRPL classic address.
+5. Ensure your signing infrastructure can sign XRPL transactions.
+
+Never send wallet seeds or private keys to cloudpayX.
+
+XRPL account documentation:
+https://xrpl.org/docs/concepts/accounts
+
+## 2. Activate and fund the account
+
+An XRPL wallet address must be funded before its account exists
+on the ledger.
+
+Obtain sufficient XRP for:
+
+- Account activation and current reserve requirements
+- Additional ledger objects, where applicable
+- XRPL transaction fees
+- XRP payments, if purchasing with XRP
+
+Check current reserve requirements before funding.
+
+Reserve documentation:
+https://xrpl.org/docs/concepts/accounts/reserves
+
+cpX x402 Pay does not supply XRP automatically.
+
+## 3. Supported payment assets
+
+cpX x402 Pay supports only these mainnet assets:
+
+XRP:
+  Network: xrpl:0
+  Currency: XRP
+  Issuer: none
+  Payment amount: integer drops
+
+RLUSD:
+  Network: xrpl:0
+  Currency: 524C555344000000000000000000000000000000
+  Issuer: rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De
+  Payment amount: decimal token units
+
+Circle USDC:
+  Network: xrpl:0
+  Currency: 5553444300000000000000000000000000000000
+  Issuer: rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE
+  Payment amount: decimal token units
+
+These identifiers reflect the existing cpX payment implementation.
+
+Do not substitute another issuer merely because a token uses
+the same symbol.
+
+For XRP, 1000000 drops equals 1 XRP.
+
+The SDK's payment intent, signing guard, and budget policies
+must use their documented amount formats consistently.
+
+## 4. Prepare RLUSD or USDC
+
+If paying with XRP, no token trust line is required.
+
+If paying with RLUSD or USDC:
+
+1. Verify the selected issuer and currency identity.
+2. Use your existing wallet's TrustSet capability to establish
+   any required trust line.
+3. Ensure the account has enough XRP for applicable reserves
+   and transaction fees.
+4. Acquire the intended token through a suitable provider.
+5. Check the token balance and any applicable restrictions.
+
+A trust line alone does not guarantee the ability to spend a token.
+
+Issuer authorization, freezes, and other ledger restrictions
+may prevent a transaction.
+
+Trust line documentation:
+https://xrpl.org/docs/concepts/tokens/fungible-tokens/trust-line-tokens
+
+## 5. Install cpX x402 Pay
+
+npm install @cloudpayx/x402-pay
+
+The SDK is wallet-agnostic.
+
+It does not require:
+- A cloudpayX account
+- A cloudpayX dashboard
+- A particular wallet brand
+- Hosted signing or custody
+
+## 6. Configure an existing signer
+
+The public secure purchase function accepts a compatible
+XRPL signer through its signer option.
+
+That signer must correspond to the payment intent's payer
+account and support the signing interface required by the SDK.
+
+For example, the SDK's validation example represents a signer
+using classicAddress and sign.
+
+This guide does not generate a signer or store its credentials.
+
+An autonomous agent must establish its own spending authority,
+permitted recipients, per-asset limits, and transaction fee caps.
+
+## 7. Validate before paying
+
+The working public SDK exposes:
+
+- validateSecureNodePurchase(options)
+- executeSecureNodePurchase(options)
+- reconcileSecureNodePurchase(options)
+
+Start with:
+
+node examples/quickstart-validation.mjs
+
+Run that command from the SDK source repository.
+
+This example checks payment configuration structure using
+placeholder addresses and a signer that refuses to sign.
+
+It does NOT perform a payment.
+
+It does NOT confirm that a wallet is funded or payment-ready.
+
+For a real purchase, use valid account and seller details,
+a compatible agent-controlled signer, configured policies,
+a durable journal location, and the original resource request.
+
+## 8. Execute a supported x402 purchase
+
+Follow the existing SDK's guarded payment workflow.
+
+The agent requests an x402-protected resource and receives
+the seller's payment requirements.
+
+The SDK validates the transaction requirements, economic
+intent, signer, spending authorization, and configured limits.
+
+The payment flow must preserve its original transaction
+details and enforce the signing restrictions.
+
+Call executeSecureNodePurchase() only with a valid,
+independently authorized secure purchase configuration.
+
+Do not manually manufacture payment-signature headers.
+
+The existing x402 client handles the signed payment proof
+inside the guarded payment flow.
+
+## 9. Verify settlement
+
+An HTTP success response is not proof of XRPL settlement.
+
+Use reconcileSecureNodePurchase() with the original
+journalDir and intentId to verify existing transaction
+evidence against the validated XRP Ledger.
+
+For an uncertain or interrupted payment result:
+
+- Preserve the original intent and durable journal.
+- Reconcile the previous transaction.
+- Do not blindly submit a replacement payment.
+
+A new payment attempt is not automatically authorized by
+a timeout or an unavailable ledger response.
+
+## 10. Technical references
+
+SDK package:
+https://www.npmjs.com/package/@cloudpayx/x402-pay
+
+Source:
+https://github.com/cpayX3/cpx-x402-pay
+
+XRPL x402 specification:
+https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_xrpl.md
+
+XRPL account setup:
+https://xrpl.org/docs/concepts/accounts
+
+XRPL reserves:
+https://xrpl.org/docs/concepts/accounts/reserves
+
+XRPL trust lines:
+https://xrpl.org/docs/concepts/tokens/fungible-tokens/trust-line-tokens
+
+cloudpayX agent infrastructure:
+https://api.cloudpayxagent.xyz
+
+## Important limitations
+
+This document is guidance, not a wallet-generation service.
+
+It does not create accounts, distribute funding, sign
+transactions, approve payments, or guarantee resource delivery.
+
+The existing cpX x402 Pay SDK remains the authority for
+supported payment behavior.
+
+Before a real payment, verify the installed SDK version,
+the seller's payment requirements, and all signing and
+authorization policies.