@cloudpayx/x402-pay 0.2.2 → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +66 -64
- package/examples/quickstart-validation.mjs +65 -0
- package/package.json +3 -2
- package/types/public-node.d.ts +1 -1
package/README.md
CHANGED
|
@@ -1,94 +1,96 @@
|
|
|
1
|
-
# cpX x402 Pay
|
|
1
|
+
# cpX x402 Pay
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**XRPL-native x402 payments for autonomous AI agents.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
cpX x402 Pay enables autonomous AI agents to purchase x402-protected services using XRP, RLUSD, and Circle USDC on the XRP Ledger.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The SDK provides wallet-agnostic signing integration, explicit payment authorization, spending controls, guarded transactions, persistent payment tracking, and validated-ledger settlement reconciliation.
|
|
8
8
|
|
|
9
|
-
-
|
|
10
|
-
- `src/assets.ts` — verified XRPL mainnet XRP / Ripple RLUSD / Circle USDC identity constants and three-asset policy builder.
|
|
11
|
-
- `src/index.ts` — adapter to the existing proven `@x402/core`, `@x402/fetch`, `@x402/xrpl` client.
|
|
12
|
-
- `examples/feral-agent.example.ts` — signer-injection example; no secrets or hardcoded wallet provider.
|
|
13
|
-
- `examples/simulation-only.mjs` — no-wallet, no-network, no-payment demonstration.
|
|
14
|
-
- `tests/policy.test.mjs` and `tests/three-assets.test.mjs` — locally executable approval/denial tests for all three assets.
|
|
9
|
+
Self-funded agents can integrate without a cloudpayX account, dashboard, or mandatory wallet provider.
|
|
15
10
|
|
|
16
|
-
##
|
|
11
|
+
## Installation
|
|
17
12
|
|
|
18
|
-
|
|
13
|
+
`npm install @cloudpayx/x402-pay`
|
|
19
14
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
4. Run `npm run build` to check SDK integration types against the actual installed packages.
|
|
15
|
+
**Network:** XRPL mainnet (`xrpl:0`)
|
|
16
|
+
**Protocol:** x402 V2, `exact`
|
|
17
|
+
**Assets:** XRP, RLUSD, Circle USDC
|
|
24
18
|
|
|
25
|
-
|
|
19
|
+
## Quick start: validate a payment configuration
|
|
26
20
|
|
|
27
|
-
|
|
21
|
+
Start with a no-wallet example before connecting a live XRPL signer.
|
|
28
22
|
|
|
29
|
-
|
|
23
|
+
From the SDK project:
|
|
30
24
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
| XRP | `XRP` | None | Integer drops (1 XRP = 1,000,000 drops) |
|
|
34
|
-
| Ripple RLUSD | `524C555344000000000000000000000000000000` | `rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De` | Decimal RLUSD tokens |
|
|
35
|
-
| Circle USDC on XRPL | `5553444300000000000000000000000000000000` | `rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE` | Decimal USDC tokens |
|
|
25
|
+
npm install
|
|
26
|
+
node examples/quickstart-validation.mjs
|
|
36
27
|
|
|
37
|
-
|
|
28
|
+
The example imports the published SDK interface, configures an XRP purchase, and calls `validateSecureNodePurchase()`.
|
|
38
29
|
|
|
39
|
-
|
|
30
|
+
It uses placeholder addresses and a signer that refuses to sign. **No funds move.**
|
|
40
31
|
|
|
41
|
-
|
|
42
|
-
import { createCpXX402AgentPay, createThreeAssetPolicy } from './src/index.js';
|
|
32
|
+
Validation confirms the guarded configuration structure. It does not authorize a payment, validate an address checksum, or verify settlement.
|
|
43
33
|
|
|
44
|
-
|
|
45
|
-
signer: MY_SECURE_XRPL_SIGNER, // compatible @x402/xrpl ClientXrplSigner
|
|
46
|
-
policy: createThreeAssetPolicy({
|
|
47
|
-
limits: {
|
|
48
|
-
xrpDrops: '50000', // 0.05 XRP
|
|
49
|
-
rlusd: '0.05', // 0.05 RLUSD
|
|
50
|
-
usdc: '0.05' // 0.05 Circle USDC (XRPL)
|
|
51
|
-
},
|
|
52
|
-
recipients: { mode: 'any' }, // opt-in open seller participation
|
|
53
|
-
approval: { mode: 'autonomous' } // explicit local operator/agent opt-in
|
|
54
|
-
})
|
|
55
|
-
});
|
|
56
|
-
const response = await paidFetch('https://a-trusted-x402-resource.example/report');
|
|
57
|
-
```
|
|
34
|
+
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.
|
|
58
35
|
|
|
59
|
-
|
|
36
|
+
## Capabilities
|
|
60
37
|
|
|
61
|
-
|
|
38
|
+
- **Autonomous agent payments:** Agents can purchase compatible x402 resources using their own XRPL signing infrastructure.
|
|
39
|
+
- **Wallet-agnostic integration:** No mandatory wallet brand or cloudpayX custody.
|
|
40
|
+
- **Three-asset support:** Native XRP, Ripple-issued RLUSD, and Circle-issued USDC with issuer validation.
|
|
41
|
+
- **Payment authorization:** Explicit autonomous opt-in or application-controlled approval.
|
|
42
|
+
- **Spending controls:** Per-asset limits, persistent aggregate budgets, recipient restrictions, and transaction fee ceilings.
|
|
43
|
+
- **Guarded signing:** Checks transaction destination, asset, amount, invoice binding, fees, and other transaction constraints.
|
|
44
|
+
- **Durable payment records:** Persistent journals and duplicate-payment protections.
|
|
45
|
+
- **Settlement verification:** Reconciliation against validated XRPL transaction evidence.
|
|
46
|
+
- **Protected resource access:** HTTPS validation, anti-SSRF protections, and redirect restrictions.
|
|
62
47
|
|
|
63
|
-
##
|
|
48
|
+
## Public SDK API
|
|
64
49
|
|
|
65
|
-
|
|
50
|
+
Import the guarded payment operations from `@cloudpayx/x402-pay`.
|
|
51
|
+
|
|
52
|
+
| Export | Purpose |
|
|
53
|
+
| --- | --- |
|
|
54
|
+
| `validateSecureNodePurchase` | Validate a proposed guarded payment configuration. |
|
|
55
|
+
| `executeSecureNodePurchase` | Execute a policy-controlled XRPL x402 purchase. |
|
|
56
|
+
| `reconcileSecureNodePurchase` | Reconcile an existing purchase against validated XRPL ledger evidence. |
|
|
57
|
+
|
|
58
|
+
Payment execution requires compatible signing infrastructure and application-supplied authorization and policy configuration.
|
|
59
|
+
|
|
60
|
+
## Supported assets
|
|
61
|
+
|
|
62
|
+
| Asset | Network | Amount format |
|
|
66
63
|
| --- | --- | --- |
|
|
67
|
-
|
|
|
68
|
-
| RLUSD
|
|
64
|
+
| XRP | XRPL mainnet | Integer drops |
|
|
65
|
+
| RLUSD | XRPL mainnet | Decimal token amounts, Ripple issuer-bound |
|
|
66
|
+
| Circle USDC | XRPL mainnet | Decimal token amounts, Circle issuer-bound |
|
|
67
|
+
|
|
68
|
+
**cpX x402 Pay is XRPL-only.** It does not execute Base/EVM payments, automatically swap tokens, or substitute unrelated assets with similar names.
|
|
69
69
|
|
|
70
|
-
|
|
70
|
+
## Payment lifecycle
|
|
71
71
|
|
|
72
|
-
|
|
72
|
+
1. An agent requests an x402-protected resource.
|
|
73
|
+
2. The resource returns payment requirements.
|
|
74
|
+
3. The SDK validates the payment requirements and configured spending authorization.
|
|
75
|
+
4. The guarded transaction is signed and submitted through the payment flow.
|
|
76
|
+
5. Purchase state and transaction evidence are preserved.
|
|
77
|
+
6. Ledger reconciliation verifies the settlement outcome.
|
|
73
78
|
|
|
74
|
-
|
|
75
|
-
- Strict XRPL mainnet `xrpl:0`, x402 V2, `exact` scheme, `areFeesSponsored=false`.
|
|
76
|
-
- Explicit assets and exact amount caps; opt-in seller-neutral recipient policy or allowlist.
|
|
77
|
-
- Explicit `autonomous` opt-in or application-provided authorization callback, with fail-closed exceptions.
|
|
78
|
-
- A self-funded agent retains *unrestricted authority over its own signer*. A local SDK is **not a trust boundary** against an agent holding the key: it can bypass these checks. Hardware signers, dedicated wallets, and controlled signer services are needed for stronger enforcement.
|
|
79
|
-
- **Security protections:** Spending budgets, duplicate-payment protection, resource-host validation, anti-SSRF controls, replay protection, fee budgeting, guarded signing, and validated-ledger reconciliation are covered by the SDK's security tests. These controls apply when payments use the guarded SDK interface.
|
|
80
|
-
- The live x402 facilitator/service should validate transaction signatures and bind invoice, amount, asset, destination and network, as described in the XRPL exact scheme spec.
|
|
79
|
+
Uncertain payment results require reconciliation rather than automatic duplicate payment attempts.
|
|
81
80
|
|
|
82
|
-
##
|
|
81
|
+
## Security architecture
|
|
83
82
|
|
|
84
|
-
The
|
|
83
|
+
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.
|
|
85
84
|
|
|
86
|
-
|
|
85
|
+
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.
|
|
87
86
|
|
|
88
|
-
|
|
87
|
+
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.
|
|
89
88
|
|
|
90
|
-
##
|
|
89
|
+
## Resources
|
|
91
90
|
|
|
92
|
-
|
|
91
|
+
- Website: https://cloudpayx.com
|
|
92
|
+
- Agent infrastructure: https://api.cloudpayxagent.xyz
|
|
93
|
+
- npm: https://www.npmjs.com/package/@cloudpayx/x402-pay
|
|
94
|
+
- XRPL x402 specification: https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_xrpl.md
|
|
93
95
|
|
|
94
|
-
|
|
96
|
+
**cloudpayX | Infrastructure for the autonomous economy**
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { validateSecureNodePurchase } from '@cloudpayx/x402-pay';
|
|
2
|
+
|
|
3
|
+
// Example-only addresses. No real wallet or signing credentials.
|
|
4
|
+
const payer = 'r' + 'A'.repeat(25);
|
|
5
|
+
const seller = 'r' + 'B'.repeat(25);
|
|
6
|
+
const resource = 'https://example.com/paid-resource';
|
|
7
|
+
|
|
8
|
+
const purchase = {
|
|
9
|
+
intent: {
|
|
10
|
+
intentId: 'cpx-quickstart-0001',
|
|
11
|
+
payer,
|
|
12
|
+
seller,
|
|
13
|
+
resource,
|
|
14
|
+
asset: 'XRP',
|
|
15
|
+
amount: '1000' // XRP amounts are in drops
|
|
16
|
+
},
|
|
17
|
+
journalDir: './cpx-quickstart-journal',
|
|
18
|
+
budgetCaps: {
|
|
19
|
+
xrpDrops: '1000000',
|
|
20
|
+
rlusd: '2',
|
|
21
|
+
usdc: '2'
|
|
22
|
+
},
|
|
23
|
+
signer: {
|
|
24
|
+
classicAddress: payer,
|
|
25
|
+
sign: async () => {
|
|
26
|
+
throw new Error('DEMO_SIGNING_DISABLED');
|
|
27
|
+
}
|
|
28
|
+
},
|
|
29
|
+
policy: {
|
|
30
|
+
assets: [{
|
|
31
|
+
kind: 'xrp',
|
|
32
|
+
asset: 'XRP',
|
|
33
|
+
maxAmountDrops: '1000'
|
|
34
|
+
}],
|
|
35
|
+
recipients: {
|
|
36
|
+
mode: 'allowlist',
|
|
37
|
+
addresses: [seller]
|
|
38
|
+
},
|
|
39
|
+
approval: {
|
|
40
|
+
mode: 'callback',
|
|
41
|
+
authorize: async () => false
|
|
42
|
+
}
|
|
43
|
+
},
|
|
44
|
+
oneShot: {
|
|
45
|
+
recipient: seller,
|
|
46
|
+
asset: 'XRP',
|
|
47
|
+
exactAmount: '1000',
|
|
48
|
+
maxFeeDrops: '100'
|
|
49
|
+
},
|
|
50
|
+
maxFeeDrops: '100',
|
|
51
|
+
request: {
|
|
52
|
+
url: resource,
|
|
53
|
+
init: {
|
|
54
|
+
method: 'POST',
|
|
55
|
+
body: '{}'
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
};
|
|
59
|
+
|
|
60
|
+
const valid = validateSecureNodePurchase(purchase);
|
|
61
|
+
|
|
62
|
+
console.log('cpX x402 Pay');
|
|
63
|
+
console.log('Configuration valid:', valid);
|
|
64
|
+
console.log('No wallet connected. No transaction signed or submitted.');
|
|
65
|
+
console.log('This checks configuration shape, not payment authorization or settlement.');
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cloudpayx/x402-pay",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.4",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "XRPL-native x402 payment SDK for autonomous AI agents. Secure, wallet-agnostic XRP, RLUSD and Circle USDC payments with spending policies and verified settlement.",
|
|
6
6
|
"dependencies": {
|
|
@@ -38,6 +38,7 @@
|
|
|
38
38
|
"scripts/trusted-xrpl-primitives.mjs",
|
|
39
39
|
"scripts/trusted-xrpl-recovery.mjs",
|
|
40
40
|
"types/",
|
|
41
|
-
"README.md"
|
|
41
|
+
"README.md",
|
|
42
|
+
"examples/quickstart-validation.mjs"
|
|
42
43
|
]
|
|
43
44
|
}
|
package/types/public-node.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/** cpX x402 Pay
|
|
1
|
+
/** cpX x402 Pay supported Node.js API; no wallet keys are handled here. */
|
|
2
2
|
import type { ClientXrplSigner } from '@x402/xrpl';
|
|
3
3
|
import type { AgentPaymentConfig } from '../dist/src/policy.js';
|
|
4
4
|
import type { GuardOptions } from '../dist/src/one_shot_guard.js';
|