x402-stellar-sdk 1.0.2 → 1.0.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 +122 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# x402-stellar-sdk
|
|
2
|
+
|
|
3
|
+
HTTP 402 Payment Required for Stellar. Monetize APIs by requiring a Stellar payment before serving protected routes. Config-driven (amount, asset, destination, network); works with Hono, Express, and Next.js.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install x402-stellar-sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Server API
|
|
12
|
+
|
|
13
|
+
### Options (`X402StellarOptions`)
|
|
14
|
+
|
|
15
|
+
| Field | Type | Description |
|
|
16
|
+
|-------|------|--------------|
|
|
17
|
+
| `price` | string | Amount (e.g. `"1"`, `"10.5"`) |
|
|
18
|
+
| `assetCode` | string | Asset code (e.g. `"XLM"`, `"USDC"`) |
|
|
19
|
+
| `issuer` | string? | Issuer account (G...) for custom assets; omit for native XLM |
|
|
20
|
+
| `network` | `"mainnet" \| "testnet"` | Stellar network |
|
|
21
|
+
| `destination` | string | Destination account (G...) that receives payment |
|
|
22
|
+
| `memo` | string? | Optional memo for payment correlation |
|
|
23
|
+
|
|
24
|
+
### Protect a route (Express)
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
import express from "express";
|
|
28
|
+
import { x402 } from "x402-stellar-sdk/server";
|
|
29
|
+
|
|
30
|
+
const app = express();
|
|
31
|
+
|
|
32
|
+
const options = {
|
|
33
|
+
price: "1",
|
|
34
|
+
assetCode: "XLM",
|
|
35
|
+
network: "testnet" as const,
|
|
36
|
+
destination: process.env.X402_DESTINATION!, // G...
|
|
37
|
+
memo: "premium-api",
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
app.use("/api/premium", x402(options));
|
|
41
|
+
app.get("/api/premium", (_req, res) => {
|
|
42
|
+
res.json({ data: "Premium content – payment verified." });
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
app.listen(3000);
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Protect a route (Hono)
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
import { Hono } from "hono";
|
|
52
|
+
import { x402Hono } from "x402-stellar-sdk/server/hono";
|
|
53
|
+
|
|
54
|
+
const app = new Hono();
|
|
55
|
+
const options = {
|
|
56
|
+
price: "0.5",
|
|
57
|
+
assetCode: "XLM",
|
|
58
|
+
network: "mainnet" as const,
|
|
59
|
+
destination: process.env.X402_DESTINATION!,
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
app.use("/api/premium", x402Hono(options));
|
|
63
|
+
app.get("/api/premium", (c) => c.json({ data: "Premium content" }));
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Protect a route (Next.js App Router)
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
// app/api/premium/route.ts
|
|
70
|
+
import { withX402 } from "x402-stellar-sdk/server/next";
|
|
71
|
+
|
|
72
|
+
const options = {
|
|
73
|
+
price: "1",
|
|
74
|
+
assetCode: "XLM",
|
|
75
|
+
network: "testnet" as const,
|
|
76
|
+
destination: process.env.X402_DESTINATION!,
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
export async function GET(req: Request) {
|
|
80
|
+
const res402 = await withX402(req.headers, options);
|
|
81
|
+
if (res402) return res402;
|
|
82
|
+
return Response.json({ data: "Premium content" });
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Verification
|
|
87
|
+
|
|
88
|
+
Payment is verified by reading `X-402-Transaction-Hash` from the request and checking the transaction on Horizon: correct destination, amount ≥ `price`, and asset. Optional memo is compared if set. Use `verifyPaymentOnChain(txHash, options)` from `x402-stellar-sdk/server` for custom flows.
|
|
89
|
+
|
|
90
|
+
## Client API
|
|
91
|
+
|
|
92
|
+
### `x402Fetch(input, init?, options?)`
|
|
93
|
+
|
|
94
|
+
Fetches a URL. If the server responds with **402 Payment Required**, the SDK parses payment details from headers (`X-402-Amount`, `X-402-Asset-Code`, `X-402-Network`, `X-402-Destination`, etc.). You must provide `payWithStellar` to perform the payment; then the client retries the request with the transaction hash in `X-402-Transaction-Hash`.
|
|
95
|
+
|
|
96
|
+
```typescript
|
|
97
|
+
import { x402Fetch } from "x402-stellar-sdk/client";
|
|
98
|
+
import type { X402PaymentRequest, X402PaymentResponse } from "x402-stellar-sdk/client";
|
|
99
|
+
|
|
100
|
+
const response = await x402Fetch("https://api.example.com/api/premium", undefined, {
|
|
101
|
+
payWithStellar: async (req: X402PaymentRequest): Promise<X402PaymentResponse | null> => {
|
|
102
|
+
// 1. Show UI (e.g. modal) with req.amount, req.assetCode, req.destination, req.network, req.memo
|
|
103
|
+
// 2. User pays with Freighter or another wallet
|
|
104
|
+
// 3. Return { transactionHash } once the payment tx is submitted
|
|
105
|
+
const txHash = await submitPaymentWithWallet(req);
|
|
106
|
+
return txHash ? { transactionHash: txHash } : null;
|
|
107
|
+
},
|
|
108
|
+
});
|
|
109
|
+
const data = await response.json();
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Using with a payment modal (UI)
|
|
113
|
+
|
|
114
|
+
In an app that uses the `ui` package (e.g. sdk-fe), you can show a modal with payment instructions and a “Pay with Stellar” action. The modal receives the `X402PaymentRequest` from the 402 response and calls your wallet (e.g. Freighter); on success, pass the transaction hash to `payWithStellar`’s resolution so `x402Fetch` can retry the request. See the `ui` package for an `X402PaymentModal` component that fits this flow.
|
|
115
|
+
|
|
116
|
+
## Exports
|
|
117
|
+
|
|
118
|
+
- **Main:** `x402`, `createPaymentRequiredResponse`, `processPaymentMiddleware`, `x402Fetch`, and types.
|
|
119
|
+
- **Server:** `x402-stellar-sdk/server` – `x402`, `createPaymentRequiredResponse`, `processPaymentMiddleware`, `verifyPaymentOnChain`, types.
|
|
120
|
+
- **Server Hono:** `x402-stellar-sdk/server/hono` – `x402Hono`.
|
|
121
|
+
- **Server Next:** `x402-stellar-sdk/server/next` – `withX402`.
|
|
122
|
+
- **Client:** `x402-stellar-sdk/client` – `x402Fetch`, `X402PaymentRequest`, `X402PaymentResponse`, `X402ClientOptions`.
|