x402-sessions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 madhav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# x402-sessions
+
+**Sign once, settle many times — session-based x402 payments on Stellar.**
+
+A tiny TypeScript SDK that turns a single Stellar Asset Contract (SAC) `approve` into an unlimited stream of x402 micropayments. Pay $1 upfront, then every API call automatically settles $0.10 on-chain via `transfer_from`. No per-call wallet popup. No off-chain bookkeeping tricks. The cap and expiry are enforced on-chain by the SAC itself.
+
+> Classic x402 = 1 request, 1 signature, 1 settlement.
+> **x402-sessions = 1 signature, N settlements.**
+
+## Why
+
+If you're building an AI agent, a dapp game, a pay-per-inference API, or anything where a user makes many small payments in a row, classic x402 becomes friction theatre — one wallet popup per request. Thirdweb built a session model for EVM using Permit2 + off-chain facilitator bookkeeping. This package is the Stellar-native equivalent, and it's arguably simpler *and* stronger:
+
+- **On-chain enforcement of the cap** via SEP-41 `approve`. Not a facilitator-side ledger hack.
+- **Zero escrow.** Unused allowance stays in the user's wallet. No refund dance when a session expires.
+- **Works with existing x402 infra.** Registers as a new scheme (`session`) alongside Coinbase's `exact`. Drop-in on the resource-server side via `@x402/core`'s `x402ResourceServer.register()`.
+- **Tiny wire format.** The retry `PaymentPayload.payload` is just `{ sessionId }`.
+
+## Install
+
+```bash
+npm install x402-sessions @stellar/stellar-sdk
+# if you're also building the resource-server side:
+npm install @x402/core @x402/next
+```
+
+Peer deps: `@stellar/stellar-sdk ^14 || ^15`, `@x402/core ^2.8.0` (optional — only if you use the server-side scheme plugin).
+
+You also need a running **x402-sessions facilitator** — a small service that verifies sessions and performs the on-chain `transfer_from`. A reference implementation (Express + better-sqlite3 + `@stellar/stellar-sdk`) ships alongside this package. Self-host it or point your clients at one you trust.
+
+## 30-second quickstart
+
+### 1. Client side (Node)
+
+```ts
+import { Keypair } from "@stellar/stellar-sdk";
+import { createSession } from "x402-sessions";
+
+const session = await createSession({
+  signer: Keypair.fromSecret(process.env.USER_SECRET!),
+  facilitatorUrl: "http://localhost:4021",
+  network: "stellar:testnet",
+  asset: "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA", // USDC testnet SAC
+  spendingCap: "1.00",   // $1 total
+  expiresIn: 3600,       // 1 hour
+  recipient: "GBWYMS7R...", // your resource server's wallet
+});
+
+// session.fetch is a drop-in fetch that transparently pays per call.
+for (let i = 0; i < 10; i++) {
+  const res = await session.fetch("https://yourapi.example/inference");
+  console.log(await res.json()); // each call settles $0.10 on-chain
+}
+```
+
+Under the hood `createSession` signs and submits **one** SAC `approve(user, facilitator, cap, expiration_ledger)` tx, registers the approval with the facilitator, and returns a `SessionHandle` whose `fetch()` method transparently handles 402 responses.
+
+### 2. Client side (browser with Freighter)
+
+```ts
+import { signTransaction, requestAccess } from "@stellar/freighter-api";
+import { createSession } from "x402-sessions";
+
+const { address } = await requestAccess();
+
+const session = await createSession({
+  signer: {
+    publicKey: () => address,
+    signTransaction: async (xdr, opts) => {
+      const r = await signTransaction(xdr, {
+        networkPassphrase: opts?.networkPassphrase,
+        address,
+      });
+      if (r.error) throw new Error(r.error.message ?? "sign failed");
+      return r.signedTxXdr;
+    },
+  },
+  facilitatorUrl: "http://localhost:4021",
+  network: "stellar:testnet",
+  asset: process.env.NEXT_PUBLIC_USDC_SAC_ID!,
+  spendingCap: "1.00",
+  expiresIn: 3600,
+  recipient: process.env.NEXT_PUBLIC_RECIPIENT!,
+});
+
+// Use it anywhere you'd use fetch()
+await session.fetch("/api/chat", {
+  method: "POST",
+  body: JSON.stringify({ prompt: "hi" }),
+  headers: { "Content-Type": "application/json" },
+});
+```
+
+Any signer with `publicKey()` + either `sign(tx)` (Node `Keypair`) or `signTransaction(xdr, opts)` (browser wallet adapter) works.
+
+### 3. Resource-server side (Next.js + `@x402/next`)
+
+```ts
+import { paymentProxy, x402ResourceServer } from "@x402/next";
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import { SessionStellarScheme } from "x402-sessions";
+
+const facilitator = new HTTPFacilitatorClient({
+  url: process.env.SESSION_FACILITATOR_URL ?? "http://localhost:4021",
+});
+
+const server = new x402ResourceServer(facilitator).register(
+  "stellar:testnet",
+  new SessionStellarScheme({
+    assetContractId: "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
+    facilitatorUrl: process.env.SESSION_FACILITATOR_URL,
+  }),
+);
+
+export const handler = paymentProxy(
+  {
+    "/api/chat": {
+      accepts: [
+        {
+          scheme: "session" as const,
+          price: "0.10",
+          network: "stellar:testnet",
+          payTo: process.env.SERVER_STELLAR_ADDRESS!,
+        },
+      ],
+      description: "AI chat, settled per message via session",
+    },
+  },
+  server,
+);
+```
+
+That's it. Any request to `/api/chat` without a session payload gets a 402. With one, it passes through and $0.10 settles on-chain.
+
+## How it works
+
+```
+┌──────────────┐                                        ┌───────────────┐
+│  user wallet │──1. approve(facilitator, $1, 1h) ─────▶│   USDC SAC    │
+│  (Freighter) │                                        │  (on-chain)   │
+└──────┬───────┘                                        └───────▲───────┘
+       │                                                        │
+       │ 2. POST /sessions {approvalTxHash, cap, …}              │
+       ▼                                                        │
+┌──────────────┐    3. sessionId                                 │
+│ x402-sessions│◀─────────────────┐                              │
+│  facilitator │                  │                              │
+│  (HTTP)      │                  │                              │
+└──────┬───────┘                  │                              │
+       │                          │                              │
+       │                          │                              │
+       │           4. POST /api/chat (per call)                  │
+       │           ┌──────────────┴───────────────┐              │
+       │           │                              │              │
+       │           │       ┌──────────────┐       │              │
+       │           └──────▶│   resource   │       │              │
+       │                   │   server     │       │              │
+       │                   │ (@x402/next) │       │              │
+       │                   └──────┬───────┘       │              │
+       │                          │               │              │
+       │◀── 5. /verify ────────── │               │              │
+       │    /settle                                              │
+       │──── 6. transfer_from(facilitator, user, server, $0.10) ─▶
+       │                                                         │
+       │                   7. ok + reply                         │
+       │                   └──────────────▶ user                 │
+       └──── decrement session (sqlite) ─────────────────────────┘
+```
+
+1. User signs **one** on-chain `approve(spender=facilitator, amount=cap, expiration_ledger)`.
+2. SDK registers the approval with the facilitator (`POST /sessions`).
+3. Facilitator verifies on-chain allowance via `allowance()`, stores the session, returns a `sessionId`.
+4. User hits protected endpoint with `session.fetch(...)`. SDK handles the 402 dance automatically:
+   - Reads the `PAYMENT-REQUIRED` header (x402 v2)
+   - Builds a payment payload `{ sessionId }`
+   - Retries with `PAYMENT-SIGNATURE` header
+5. Resource server's `x402ResourceServer` calls facilitator `/verify` then `/settle`.
+6. Facilitator runs `transfer_from(spender, from, to, amount)` on-chain. The SAC itself enforces the cap and expiry.
+7. Response flows back to the user. Spent counter decrements.
+
+## API reference
+
+### `createSession(options)`
+
+Signs + submits the on-chain `approve`, registers the session with the facilitator, and returns a `SessionHandle`.
+
+```ts
+function createSession(opts: CreateSessionOptions): Promise<SessionHandle>
+
+interface CreateSessionOptions {
+  signer: ClientSigner;              // Keypair or browser wallet adapter
+  facilitatorUrl: string;            // e.g. "http://localhost:4021"
+  network?: "stellar:testnet" | "stellar:pubnet"; // default testnet
+  asset: string;                     // SAC contract id (C...)
+  spendingCap: string;               // human units, e.g. "1.00"
+  decimals?: number;                 // default 7 (USDC)
+  expiresIn: number;                 // seconds; converted to ledger count
+  recipient: string;                 // payTo address (G...)
+  sorobanRpcUrl?: string;            // override default
+}
+
+interface SessionHandle {
+  sessionId: string;
+  user: string;
+  spender: string;
+  asset: string;
+  recipient: string;
+  cap: string;            // base units (stroops for 7-dec USDC)
+  spent: string;          // base units
+  expirationLedger: number;
+  network: Network;
+  facilitatorUrl: string;
+  fetch: typeof fetch;    // auto-paying fetch
+}
+```
+
+### `wrapFetch(sessionId)`
+
+Lower-level helper. Returns a `fetch`-compatible function that, on receiving a 402, reads the `PAYMENT-REQUIRED` header, builds a `PaymentPayload` with the given `sessionId`, and retries with `PAYMENT-SIGNATURE`. Use this if you want to manage the session handle yourself (e.g. persist it across pages).
+
+```ts
+function wrapFetch(sessionId: string): typeof fetch
+```
+
+### `SessionStellarScheme`
+
+Resource-server plugin for `@x402/core`'s `x402ResourceServer.register()`. Advertises the `session` scheme, parses prices, and enriches 402 responses with facilitator metadata.
+
+```ts
+class SessionStellarScheme {
+  constructor(config: {
+    assetContractId: string;   // SAC contract id
+    decimals?: number;         // default 7
+    facilitatorUrl?: string;   // exposed to clients in 402.extra
+  });
+}
+```
+
+Structurally compatible with `@x402/core`'s `SchemeNetworkServer` interface. (It doesn't `implements` literally, to avoid an `@x402/core/types` module-resolution requirement — your TypeScript will happily pass it to `register(network, new SessionStellarScheme(...))` via structural typing.)
+
+### `ClientSigner`
+
+Minimal signer interface. A `Keypair` from `@stellar/stellar-sdk` satisfies it natively (via its `sign(Buffer)` method). For browser wallets, provide the `signTransaction` shape.
+
+```ts
+interface ClientSigner {
+  publicKey(): string;
+  sign?(data: Buffer): Buffer;
+  signTransaction?(
+    xdr: string,
+    opts?: { networkPassphrase: string },
+  ): Promise<string>;
+}
+```
+
+### Helpers
+
+```ts
+import {
+  decimalToBaseUnits,     // "1.50" + 7 decimals -> 15000000n
+  defaultRpcUrlFor,       // network -> public Soroban RPC URL
+  networkPassphraseFor,   // network -> stellar-sdk Networks constant
+} from "x402-sessions";
+```
+
+## Wire format (session scheme)
+
+- **Scheme:** `"session"`
+- **Network:** `"stellar:testnet"` | `"stellar:pubnet"`
+- **`PaymentPayload.payload`** (the scheme-specific slot): `{ sessionId: string }`
+- **Facilitator HTTP surface** (added to the standard x402 triplet):
+  - `GET  /supported` — standard x402
+  - `POST /verify`    — standard x402
+  - `POST /settle`    — standard x402
+  - `POST /sessions`  — **new**: register a session from a signed approval tx hash
+  - `GET  /sessions/:id` — **new**: inspect remaining cap / spent / expiry
+
+## Trust model
+
+| Limit | Enforced by | Hardness |
+|---|---|---|
+| **Total cap** (e.g. $1) | SAC `approve` + `transfer_from` reverts past cap | **On-chain** |
+| **Expiry** (ledger) | `expiration_ledger` parameter in SAC `approve` | **On-chain** |
+| **Per-call price** (e.g. $0.10) | Facilitator `/settle` refuses amounts > policy | Off-chain (trust your facilitator) |
+| **Recipient binding** | Facilitator only pays the pre-registered `recipient` | Off-chain |
+| **Session reuse control** | Facilitator sqlite bookkeeping | Off-chain |
+| **Unused balance handling** | Funds never escrowed — they stay in the user's wallet | **Native** |
+
+In short: on-chain handles the money-safety invariants (total and expiry). Off-chain handles the application policy (per-call price, recipient, bookkeeping). This is the same trust model as thirdweb's session x402 on EVM, except the cap enforcement is *strictly better* because ours is on-chain.
+
+If you need on-chain per-call policy enforcement (e.g. "no more than $0.10 per call, no matter what"), upgrade to a Soroban custom account / smart wallet with a policy-signer session key — out of scope for this package.
+
+## No refund dance
+
+Because `approve` is a *permission*, not an escrow, tokens never leave the user's wallet until `transfer_from` is called:
+
+| Scenario | What happens |
+|---|---|
+| Session expires unused | Still in user's wallet. Allowance becomes unusable. No refund call. |
+| Session partially used | The untouched portion never moved. No refund call. |
+| User wants to end early | Optional: sign `approve(..., amount=0)` to revoke. Not required — expiry handles it. |
+
+Compare this to escrow-based session models where you must explicitly claim refunds.
+
+## Security notes
+
+- Treat the `sessionId` as a **bearer token** — anyone who steals it can spend the full cap to the pre-registered recipient. Keep it in memory or secure storage; don't log it.
+- The recipient is bound at session creation. A stolen sessionId cannot redirect funds.
+- Worst-case: an attacker drains the whole cap to *your* game server. User loses up to `cap`; funds still end up where they were meant to go.
+- For higher-trust scenarios, use a smaller cap per session and rotate often.
+
+## FAQ
+
+**Q: Is this the same as Coinbase x402's `upto` scheme?**
+A: No — `upto` is a canonical Coinbase-authored scheme that's currently EVM-only and enforces single-use authorizations. This is a **new scheme** called `session`, Stellar-native, built on SAC `approve`.
+
+**Q: Is this the same as thirdweb's session x402?**
+A: Same *model* (sign once, settle many), different *mechanism*. Thirdweb uses Uniswap Permit2 on EVM with facilitator-side bookkeeping. This package uses Stellar SAC `approve`/`transfer_from` with on-chain bookkeeping. No EIP-7702 involved on either side.
+
+**Q: Can I use it with real Circle USDC on Stellar?**
+A: Yes — the SAC contract ID for Circle testnet USDC is `CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA`, and pubnet is `CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75`. Any SEP-41 token works — native XLM SAC, Circle USDC, or your own issued asset.
+
+**Q: What if on-chain `transfer_from` fails after the facilitator debits sqlite?**
+A: The reference facilitator rolls back the sqlite debit automatically and returns `success: false, errorReason: "onchain_transfer_failed"` in the `payment-response` header.
+
+**Q: Can I reuse a session across multiple resource servers?**
+A: Only if the `recipient` matches. The facilitator binds a session to exactly one recipient at creation time.
+
+**Q: What happens if the session cap runs out mid-request?**
+A: Facilitator `/verify` returns `invalidReason: "cap_exceeded"`. The client sees a 402 with the reason in the `payment-response` header; the resource is not served and no on-chain tx is submitted.
+
+**Q: Can I use the browser `fetch` directly, without `wrapFetch`?**
+A: Yes — just handle the 402 yourself. Read the `PAYMENT-REQUIRED` response header (base64 JSON), find the `scheme: "session"` accept, build a `PaymentPayload` with `{ payload: { sessionId } }`, base64-encode it, and retry with a `PAYMENT-SIGNATURE` header.
+
+## License
+
+MIT © madhav

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+import type { CreateSessionOptions, SessionHandle } from "./types";
+export declare function createSession(opts: CreateSessionOptions): Promise<SessionHandle>;
+/**
+ * Returns a fetch-compatible function that, on a 402 response, decodes the
+ * `PAYMENT-REQUIRED` response header (x402 v2), finds a `scheme: "session"`
+ * accept entry, and retries with `PAYMENT-SIGNATURE` (plus `X-PAYMENT` as a
+ * fallback for older servers).
+ *
+ * The x402 v2 wire format (per @x402/core):
+ *   - Server 402 puts PaymentRequired JSON in `PAYMENT-REQUIRED` header (base64).
+ *     The body is empty `{}`.
+ *   - Client retries with PaymentPayload JSON in `PAYMENT-SIGNATURE` header (base64).
+ */
+export declare function wrapFetch(sessionId: string): typeof fetch;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,oBAAoB,EAMpB,aAAa,EAEd,MAAM,SAAS,CAAC;AAKjB,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CA8DtF;AAgCD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,KAAK,CAuDzD"}

package/dist/client.js

@@ -0,0 +1,178 @@
+"use strict";
+// createSession() — the main client-facing API.
+//
+// Flow:
+//   1. GET {facilitatorUrl}/supported to learn the facilitator's spender address.
+//   2. Sign & submit SAC approve(user, spender, cap, expiration_ledger) on-chain.
+//   3. POST /sessions to register the approval. Returns a sessionId.
+//   4. Return a SessionHandle with a wrapFetch() that auto-handles 402 responses.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSession = createSession;
+exports.wrapFetch = wrapFetch;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const stellar_1 = require("./stellar");
+const DEFAULT_DECIMALS = 7;
+const DEFAULT_NETWORK = "stellar:testnet";
+async function createSession(opts) {
+    const network = opts.network ?? DEFAULT_NETWORK;
+    const decimals = opts.decimals ?? DEFAULT_DECIMALS;
+    const rpcUrl = opts.sorobanRpcUrl ?? (0, stellar_1.defaultRpcUrlFor)(network);
+    // 1. Fetch facilitator's /supported to discover spender address and scheme config.
+    const supported = await fetchSupported(opts.facilitatorUrl);
+    const kind = supported.kinds.find((k) => k.scheme === "session" && k.network === network);
+    if (!kind) {
+        throw new Error(`facilitator ${opts.facilitatorUrl} does not advertise scheme=session network=${network}`);
+    }
+    const spender = kind.extra?.spender ?? supported.signers["stellar:*"]?.[0];
+    if (!spender) {
+        throw new Error(`facilitator /supported did not include a spender address; got: ${JSON.stringify(supported)}`);
+    }
+    // 2. Compute expiration ledger from expiresIn seconds.
+    const server = new stellar_sdk_1.rpc.Server(rpcUrl, { allowHttp: rpcUrl.startsWith("http://") });
+    const expirationLedger = await (0, stellar_1.computeExpirationLedger)(server, opts.expiresIn);
+    // 3. Sign & submit SAC approve on-chain.
+    const capBaseUnits = (0, stellar_1.decimalToBaseUnits)(opts.spendingCap, decimals);
+    const { txHash } = await (0, stellar_1.approveSAC)({
+        signer: opts.signer,
+        assetContractId: opts.asset,
+        spender,
+        amount: capBaseUnits,
+        expirationLedger,
+        network,
+        sorobanRpcUrl: rpcUrl,
+    });
+    // 4. Register the session with the facilitator.
+    const createReq = {
+        approvalTxHash: txHash,
+        user: opts.signer.publicKey(),
+        asset: opts.asset,
+        recipient: opts.recipient,
+        cap: capBaseUnits.toString(),
+        expirationLedger,
+        network,
+    };
+    const created = await postSession(opts.facilitatorUrl, createReq);
+    // 5. Build the session handle with wrapped fetch.
+    return {
+        sessionId: created.sessionId,
+        user: created.user,
+        spender: created.spender,
+        asset: created.asset,
+        recipient: created.recipient,
+        cap: created.cap,
+        spent: created.spent,
+        expirationLedger: created.expirationLedger,
+        network: created.network,
+        facilitatorUrl: opts.facilitatorUrl,
+        fetch: wrapFetch(created.sessionId),
+    };
+}
+async function fetchSupported(facilitatorUrl) {
+    const res = await fetch(joinUrl(facilitatorUrl, "/supported"));
+    if (!res.ok)
+        throw new Error(`facilitator /supported returned ${res.status}`);
+    return (await res.json());
+}
+async function postSession(facilitatorUrl, body) {
+    const res = await fetch(joinUrl(facilitatorUrl, "/sessions"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`facilitator /sessions ${res.status}: ${text}`);
+    }
+    return (await res.json());
+}
+function joinUrl(base, path) {
+    return base.replace(/\/+$/, "") + (path.startsWith("/") ? path : `/${path}`);
+}
+// --------------------------------------------------------------------------
+// wrapFetch: automatically handles 402 responses by attaching the session payload
+// --------------------------------------------------------------------------
+/**
+ * Returns a fetch-compatible function that, on a 402 response, decodes the
+ * `PAYMENT-REQUIRED` response header (x402 v2), finds a `scheme: "session"`
+ * accept entry, and retries with `PAYMENT-SIGNATURE` (plus `X-PAYMENT` as a
+ * fallback for older servers).
+ *
+ * The x402 v2 wire format (per @x402/core):
+ *   - Server 402 puts PaymentRequired JSON in `PAYMENT-REQUIRED` header (base64).
+ *     The body is empty `{}`.
+ *   - Client retries with PaymentPayload JSON in `PAYMENT-SIGNATURE` header (base64).
+ */
+function wrapFetch(sessionId) {
+    return async (input, init = {}) => {
+        const first = await fetch(input, init);
+        if (first.status !== 402)
+            return first;
+        // Try v2 header-based discovery first, then v1 body-based.
+        let required = null;
+        const headerValue = first.headers.get("payment-required") ??
+            first.headers.get("PAYMENT-REQUIRED") ??
+            first.headers.get("x-payment-required");
+        if (headerValue) {
+            try {
+                required = base64DecodeJson(headerValue);
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        if (!required) {
+            try {
+                const body = (await first.clone().json());
+                if (body && Array.isArray(body.accepts))
+                    required = body;
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        if (!required)
+            return first;
+        const sessionAccept = (required.accepts ?? []).find((a) => a.scheme === "session");
+        if (!sessionAccept)
+            return first;
+        const paymentPayload = {
+            x402Version: required.x402Version ?? 2,
+            accepted: sessionAccept,
+            payload: { sessionId },
+        };
+        const encoded = base64EncodeJson(paymentPayload);
+        const retryInit = {
+            ...init,
+            headers: {
+                ...init.headers,
+                // v2 canonical name
+                "PAYMENT-SIGNATURE": encoded,
+                // v1 fallback — harmless if server ignores it
+                "X-PAYMENT": encoded,
+            },
+        };
+        return fetch(input, retryInit);
+    };
+}
+function base64EncodeJson(obj) {
+    const json = JSON.stringify(obj);
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(json, "utf-8").toString("base64");
+    // Browser fallback
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const g = globalThis;
+    return g.btoa(unescape(encodeURIComponent(json)));
+}
+function base64DecodeJson(b64) {
+    let json;
+    if (typeof Buffer !== "undefined") {
+        json = Buffer.from(b64, "base64").toString("utf-8");
+    }
+    else {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const g = globalThis;
+        json = decodeURIComponent(escape(g.atob(b64)));
+    }
+    return JSON.parse(json);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createSession, wrapFetch } from "./client";
+export { SessionStellarScheme } from "./scheme-server";
+export type { ClientSigner, CreateSessionOptions, CreateSessionRequest, CreateSessionResponse, Network, PaymentPayload, PaymentRequired, PaymentRequirements, SessionHandle, SessionPaymentPayloadBody, SupportedResponse, } from "./types";
+export { decimalToBaseUnits, defaultRpcUrlFor, networkPassphraseFor } from "./stellar";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,OAAO,EACP,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+// x402-sessions
+// Sign once, settle many times — session-based x402 payments on Stellar.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.networkPassphraseFor = exports.defaultRpcUrlFor = exports.decimalToBaseUnits = exports.SessionStellarScheme = exports.wrapFetch = exports.createSession = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "createSession", { enumerable: true, get: function () { return client_1.createSession; } });
+Object.defineProperty(exports, "wrapFetch", { enumerable: true, get: function () { return client_1.wrapFetch; } });
+var scheme_server_1 = require("./scheme-server");
+Object.defineProperty(exports, "SessionStellarScheme", { enumerable: true, get: function () { return scheme_server_1.SessionStellarScheme; } });
+var stellar_1 = require("./stellar");
+Object.defineProperty(exports, "decimalToBaseUnits", { enumerable: true, get: function () { return stellar_1.decimalToBaseUnits; } });
+Object.defineProperty(exports, "defaultRpcUrlFor", { enumerable: true, get: function () { return stellar_1.defaultRpcUrlFor; } });
+Object.defineProperty(exports, "networkPassphraseFor", { enumerable: true, get: function () { return stellar_1.networkPassphraseFor; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,gBAAgB;AAChB,yEAAyE;;;AAEzE,mCAAoD;AAA3C,uGAAA,aAAa,OAAA;AAAE,mGAAA,SAAS,OAAA;AACjC,iDAAuD;AAA9C,qHAAA,oBAAoB,OAAA;AAc7B,qCAAuF;AAA9E,6GAAA,kBAAkB,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AAAE,+GAAA,oBAAoB,OAAA"}

package/dist/scheme-server.d.ts

@@ -0,0 +1,42 @@
+import type { Network, PaymentRequirements } from "./types";
+type AssetAmount = {
+    asset: string;
+    amount: string;
+    extra?: Record<string, unknown>;
+};
+type Price = string | number | AssetAmount;
+export type SessionSchemeConfig = {
+    /** SAC contract id of the payment token (e.g. USDC). */
+    assetContractId: string;
+    /** Token decimals. Default 7 (USDC on Stellar). */
+    decimals?: number;
+    /** Facilitator base URL — embedded into /402 extras so clients can find the sessions endpoint. */
+    facilitatorUrl?: string;
+};
+/**
+ * Resource-server plugin for the `session` scheme on Stellar.
+ *
+ * Usage (in your proxy.ts):
+ *
+ *   import { SessionStellarScheme } from "x402-sessions/scheme-server";
+ *
+ *   const server = new x402ResourceServer(facilitatorClient)
+ *     .register("stellar:testnet", new SessionStellarScheme({
+ *       assetContractId: "CBIELTK6...",
+ *       facilitatorUrl: "http://localhost:4021",
+ *     }));
+ */
+export declare class SessionStellarScheme {
+    readonly scheme: "session";
+    private readonly config;
+    constructor(config: SessionSchemeConfig);
+    parsePrice(price: Price, _network: Network): Promise<AssetAmount>;
+    enhancePaymentRequirements(paymentRequirements: PaymentRequirements, supportedKind: {
+        x402Version: number;
+        scheme: string;
+        network: Network;
+        extra?: Record<string, unknown>;
+    }, _facilitatorExtensions: string[]): Promise<PaymentRequirements>;
+}
+export {};
+//# sourceMappingURL=scheme-server.d.ts.map

package/dist/scheme-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheme-server.d.ts","sourceRoot":"","sources":["../src/scheme-server.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE5D,KAAK,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AACtF,KAAK,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAYF;;;;;;;;;;;;GAYG;AAMH,qBAAa,oBAAoB;IAC/B,QAAQ,CAAC,MAAM,EAAG,SAAS,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwE;gBAEnF,MAAM,EAAE,mBAAmB;IAKjC,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAQjE,0BAA0B,CAC9B,mBAAmB,EAAE,mBAAmB,EACxC,aAAa,EAAE;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjC,EAED,sBAAsB,EAAE,MAAM,EAAE,GAC/B,OAAO,CAAC,mBAAmB,CAAC;CAUhC"}

package/dist/scheme-server.js

@@ -0,0 +1,71 @@
+"use strict";
+// SessionStellarScheme — resource-server plugin.
+//
+// Implements @x402/core's SchemeNetworkServer interface so it can be registered
+// with `x402ResourceServer.register(network, new SessionStellarScheme())`.
+//
+// Responsibilities:
+//   - parsePrice(): convert "1.00" (decimal USD-ish) to { asset, amount } base units.
+//   - enhancePaymentRequirements(): add scheme-specific extras (facilitator spender,
+//     sessions endpoint URL) to the 402 response so the client SDK knows where to
+//     create a session.
+//
+// The actual verify/settle happen on the HTTP facilitator (our Express service),
+// which x402's HTTPFacilitatorClient talks to.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStellarScheme = void 0;
+const DEFAULT_DECIMALS = 7;
+function decimalToBaseUnits(amount, decimals) {
+    const s = typeof amount === "number" ? amount.toString() : amount;
+    if (!/^\d+(\.\d+)?$/.test(s))
+        throw new Error(`invalid decimal amount: ${s}`);
+    const [whole, frac = ""] = s.split(".");
+    const padded = (frac + "0".repeat(decimals)).slice(0, decimals);
+    return (BigInt(whole) * 10n ** BigInt(decimals) + BigInt(padded || "0")).toString();
+}
+/**
+ * Resource-server plugin for the `session` scheme on Stellar.
+ *
+ * Usage (in your proxy.ts):
+ *
+ *   import { SessionStellarScheme } from "x402-sessions/scheme-server";
+ *
+ *   const server = new x402ResourceServer(facilitatorClient)
+ *     .register("stellar:testnet", new SessionStellarScheme({
+ *       assetContractId: "CBIELTK6...",
+ *       facilitatorUrl: "http://localhost:4021",
+ *     }));
+ */
+// NOTE: We intentionally do NOT `implements SchemeNetworkServer` here — @x402/core
+// uses an exports map that requires node16+ module resolution, which would force
+// us to emit ESM or use .js extensions. Instead, this class is structurally
+// compatible with SchemeNetworkServer. TypeScript's duck typing means consumers
+// can pass `new SessionStellarScheme(...)` directly to `x402ResourceServer.register(network, ...)`.
+class SessionStellarScheme {
+    constructor(config) {
+        this.scheme = "session";
+        this.config = { decimals: DEFAULT_DECIMALS, ...config };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async parsePrice(price, _network) {
+        if (typeof price === "object" && "asset" in price && "amount" in price) {
+            return price;
+        }
+        const amount = decimalToBaseUnits(price, this.config.decimals);
+        return { asset: this.config.assetContractId, amount };
+    }
+    async enhancePaymentRequirements(paymentRequirements, supportedKind, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _facilitatorExtensions) {
+        const mergedExtra = {
+            ...paymentRequirements.extra,
+            ...(supportedKind.extra ?? {}),
+        };
+        if (this.config.facilitatorUrl && !mergedExtra.facilitatorUrl) {
+            mergedExtra.facilitatorUrl = this.config.facilitatorUrl;
+        }
+        return { ...paymentRequirements, extra: mergedExtra };
+    }
+}
+exports.SessionStellarScheme = SessionStellarScheme;
+//# sourceMappingURL=scheme-server.js.map

package/dist/scheme-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheme-server.js","sourceRoot":"","sources":["../src/scheme-server.ts"],"names":[],"mappings":";AAAA,iDAAiD;AACjD,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAC3E,EAAE;AACF,oBAAoB;AACpB,sFAAsF;AACtF,qFAAqF;AACrF,kFAAkF;AAClF,wBAAwB;AACxB,EAAE;AACF,iFAAiF;AACjF,+CAA+C;;;AAgB/C,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B,SAAS,kBAAkB,CAAC,MAAuB,EAAE,QAAgB;IACnE,MAAM,CAAC,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IAClE,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,EAAE,CAAC,CAAC;IAC9E,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AACtF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,mFAAmF;AACnF,iFAAiF;AACjF,4EAA4E;AAC5E,gFAAgF;AAChF,oGAAoG;AACpG,MAAa,oBAAoB;IAI/B,YAAY,MAA2B;QAH9B,WAAM,GAAG,SAAkB,CAAC;QAInC,IAAI,CAAC,MAAM,GAAG,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAAC;IAC1D,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,UAAU,CAAC,KAAY,EAAE,QAAiB;QAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;YACvE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAwB,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClF,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,0BAA0B,CAC9B,mBAAwC,EACxC,aAKC;IACD,6DAA6D;IAC7D,sBAAgC;QAEhC,MAAM,WAAW,GAA4B;YAC3C,GAAG,mBAAmB,CAAC,KAAK;YAC5B,GAAG,CAAC,aAAa,CAAC,KAAK,IAAI,EAAE,CAAC;SAC/B,CAAC;QACF,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,CAAC;YAC9D,WAAW,CAAC,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;QAC1D,CAAC;QACD,OAAO,EAAE,GAAG,mBAAmB,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACxD,CAAC;CACF;AArCD,oDAqCC"}

package/dist/stellar.d.ts

@@ -0,0 +1,31 @@
+import { rpc } from "@stellar/stellar-sdk";
+import type { ClientSigner, Network } from "./types";
+export declare function networkPassphraseFor(network: Network): string;
+export declare function defaultRpcUrlFor(network: Network): string;
+export declare function computeExpirationLedger(server: rpc.Server, expiresInSeconds: number): Promise<number>;
+/**
+ * Convert a decimal-string amount (e.g. "1.00") to base-unit bigint given decimals.
+ * Supports simple decimal form only; rejects scientific notation.
+ */
+export declare function decimalToBaseUnits(amount: string, decimals: number): bigint;
+/**
+ * Build and submit a SAC `approve(from, spender, amount, expiration_ledger)` transaction.
+ *
+ * Returns the tx hash on success.
+ *
+ * Signing: if the signer exposes `signTransaction(xdr, { networkPassphrase })` (browser
+ * wallet adapter shape), we use that path. Otherwise we expect a `Keypair` (Node) and
+ * call `tx.sign(kp)` directly.
+ */
+export declare function approveSAC(args: {
+    signer: ClientSigner;
+    assetContractId: string;
+    spender: string;
+    amount: bigint;
+    expirationLedger: number;
+    network: Network;
+    sorobanRpcUrl?: string;
+}): Promise<{
+    txHash: string;
+}>;
+//# sourceMappingURL=stellar.d.ts.map

package/dist/stellar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stellar.d.ts","sourceRoot":"","sources":["../src/stellar.ts"],"names":[],"mappings":"AAMA,OAAO,EASL,GAAG,EAEJ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAYrD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE7D;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAIzD;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO3E;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,MAAM,EAAE,YAAY,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA4D9B"}

package/dist/stellar.js

@@ -0,0 +1,102 @@
+"use strict";
+// Client-side Stellar/Soroban helpers for the SDK:
+//  - build & submit SAC `approve(from, spender, amount, expiration_ledger)`
+//  - fetch the current ledger sequence (to compute expiration_ledger from expiresIn seconds)
+//
+// Imports stellar-sdk as a peer dep — users bring their own version.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.networkPassphraseFor = networkPassphraseFor;
+exports.defaultRpcUrlFor = defaultRpcUrlFor;
+exports.computeExpirationLedger = computeExpirationLedger;
+exports.decimalToBaseUnits = decimalToBaseUnits;
+exports.approveSAC = approveSAC;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const LEDGER_SECONDS = 5;
+function toI128(amount) {
+    return (0, stellar_sdk_1.nativeToScVal)(typeof amount === "string" ? BigInt(amount) : amount, { type: "i128" });
+}
+function addrToScVal(addr) {
+    return stellar_sdk_1.Address.fromString(addr).toScVal();
+}
+function networkPassphraseFor(network) {
+    return network === "stellar:pubnet" ? stellar_sdk_1.Networks.PUBLIC : stellar_sdk_1.Networks.TESTNET;
+}
+function defaultRpcUrlFor(network) {
+    return network === "stellar:pubnet"
+        ? "https://soroban-rpc.mainnet.stellar.gateway.fm"
+        : "https://soroban-testnet.stellar.org";
+}
+async function computeExpirationLedger(server, expiresInSeconds) {
+    const latest = await server.getLatestLedger();
+    return latest.sequence + Math.ceil(expiresInSeconds / LEDGER_SECONDS);
+}
+/**
+ * Convert a decimal-string amount (e.g. "1.00") to base-unit bigint given decimals.
+ * Supports simple decimal form only; rejects scientific notation.
+ */
+function decimalToBaseUnits(amount, decimals) {
+    if (!/^\d+(\.\d+)?$/.test(amount)) {
+        throw new Error(`invalid decimal amount: ${amount}`);
+    }
+    const [whole, frac = ""] = amount.split(".");
+    const padded = (frac + "0".repeat(decimals)).slice(0, decimals);
+    return BigInt(whole) * 10n ** BigInt(decimals) + BigInt(padded || "0");
+}
+/**
+ * Build and submit a SAC `approve(from, spender, amount, expiration_ledger)` transaction.
+ *
+ * Returns the tx hash on success.
+ *
+ * Signing: if the signer exposes `signTransaction(xdr, { networkPassphrase })` (browser
+ * wallet adapter shape), we use that path. Otherwise we expect a `Keypair` (Node) and
+ * call `tx.sign(kp)` directly.
+ */
+async function approveSAC(args) {
+    const rpcUrl = args.sorobanRpcUrl ?? defaultRpcUrlFor(args.network);
+    const server = new stellar_sdk_1.rpc.Server(rpcUrl, { allowHttp: rpcUrl.startsWith("http://") });
+    const passphrase = networkPassphraseFor(args.network);
+    const from = args.signer.publicKey();
+    const sourceAccount = await server.getAccount(from);
+    const contract = new stellar_sdk_1.Contract(args.assetContractId);
+    const tx = new stellar_sdk_1.TransactionBuilder(sourceAccount, {
+        fee: stellar_sdk_1.BASE_FEE,
+        networkPassphrase: passphrase,
+    })
+        .addOperation(contract.call("approve", addrToScVal(from), addrToScVal(args.spender), toI128(args.amount), (0, stellar_sdk_1.nativeToScVal)(args.expirationLedger, { type: "u32" })))
+        .setTimeout(60)
+        .build();
+    const prepared = await server.prepareTransaction(tx);
+    // --- signing paths ---
+    let signedXdr;
+    if (args.signer.signTransaction) {
+        const xdrStr = prepared.toXDR();
+        signedXdr = await args.signer.signTransaction(xdrStr, { networkPassphrase: passphrase });
+    }
+    else if (args.signer.sign) {
+        prepared.sign(args.signer);
+        signedXdr = prepared.toXDR();
+    }
+    else {
+        throw new Error("signer must expose either sign() or signTransaction()");
+    }
+    // Reconstruct signed tx for submission.
+    const signedTx = stellar_sdk_1.TransactionBuilder.fromXDR(signedXdr, passphrase);
+    const sent = await server.sendTransaction(signedTx);
+    if (sent.status === "ERROR") {
+        throw new Error(`approve send failed: ${JSON.stringify(sent.errorResult)}`);
+    }
+    // Poll for confirmation.
+    const deadline = Date.now() + 30000;
+    while (Date.now() < deadline) {
+        const r = await server.getTransaction(sent.hash);
+        if (r.status === stellar_sdk_1.rpc.Api.GetTransactionStatus.SUCCESS) {
+            return { txHash: sent.hash };
+        }
+        if (r.status === stellar_sdk_1.rpc.Api.GetTransactionStatus.FAILED) {
+            throw new Error(`approve tx failed: ${JSON.stringify(r)}`);
+        }
+        await new Promise((r) => setTimeout(r, 1500));
+    }
+    throw new Error(`approve tx ${sent.hash} timed out`);
+}
+//# sourceMappingURL=stellar.js.map

package/dist/stellar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stellar.js","sourceRoot":"","sources":["../src/stellar.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,126 @@
+export type Network = `${string}:${string}`;
+export type PaymentRequirements = {
+    scheme: string;
+    network: Network;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+};
+export type SessionPaymentPayloadBody = {
+    sessionId: string;
+};
+export type PaymentPayload = {
+    x402Version: number;
+    accepted: PaymentRequirements;
+    payload: SessionPaymentPayloadBody;
+    resource?: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    extensions?: Record<string, unknown>;
+};
+export type PaymentRequired = {
+    x402Version: number;
+    error?: string;
+    resource: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepts: PaymentRequirements[];
+    extensions?: Record<string, unknown>;
+};
+export type CreateSessionOptions = {
+    /** Facilitator HTTP base URL, e.g. http://localhost:4021 */
+    facilitatorUrl: string;
+    /** Stellar network identifier. Default: "stellar:testnet" */
+    network?: Network;
+    /** SAC contract id of the payment token (e.g. USDC). */
+    asset: string;
+    /**
+     * Spending cap in human units (e.g. "1.00" for 1 USDC).
+     * Will be converted to base units using `decimals`.
+     */
+    spendingCap: string;
+    /** Token decimals. USDC on Stellar = 7. Default: 7 */
+    decimals?: number;
+    /** How long the session is valid, in seconds. Converted to ledgers (~5s/ledger). */
+    expiresIn: number;
+    /** Address where settled funds go (resource server wallet). */
+    recipient: string;
+    /**
+     * Signer used to sign & submit the SAC approve transaction.
+     * For Node: a `Keypair` from @stellar/stellar-sdk.
+     * For browser: implement the `ClientSigner` interface below.
+     */
+    signer: ClientSigner;
+    /** Optional custom Soroban RPC URL. Defaults to testnet public RPC. */
+    sorobanRpcUrl?: string;
+};
+/**
+ * Minimal signer interface the SDK needs from a wallet.
+ * A @stellar/stellar-sdk `Keypair` satisfies this directly.
+ * For browser wallets (Freighter, etc.), provide an adapter.
+ */
+export interface ClientSigner {
+    /** The G... public key of this signer. */
+    publicKey(): string;
+    /** Sign a tx hash (raw 32-byte buffer). Used by the stellar-sdk internal tx.sign flow. */
+    sign?(data: Buffer): Buffer;
+    /**
+     * Alternative: sign a built Transaction's XDR string and return the signed XDR.
+     * Use this form for browser wallet adapters like Freighter that expose
+     * `signTransaction(xdr): Promise<xdr>`.
+     */
+    signTransaction?(xdr: string, opts?: {
+        networkPassphrase: string;
+    }): Promise<string>;
+}
+export type SessionHandle = {
+    sessionId: string;
+    user: string;
+    spender: string;
+    asset: string;
+    recipient: string;
+    cap: string;
+    spent: string;
+    expirationLedger: number;
+    network: Network;
+    facilitatorUrl: string;
+    /** Fetch wrapper that auto-adds X-PAYMENT session header on 402 responses. */
+    fetch: typeof fetch;
+};
+export type CreateSessionRequest = {
+    approvalTxHash: string;
+    user: string;
+    asset: string;
+    recipient: string;
+    cap: string;
+    expirationLedger: number;
+    network: Network;
+};
+export type CreateSessionResponse = {
+    sessionId: string;
+    user: string;
+    spender: string;
+    asset: string;
+    recipient: string;
+    cap: string;
+    spent: string;
+    expirationLedger: number;
+    network: Network;
+};
+export type SupportedResponse = {
+    kinds: Array<{
+        x402Version: number;
+        scheme: string;
+        network: Network;
+        extra?: Record<string, unknown>;
+    }>;
+    extensions: string[];
+    signers: Record<string, string[]>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,OAAO,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAE5C,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,yBAAyB,CAAC;IACnC,QAAQ,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC;AAMF,MAAM,MAAM,oBAAoB,GAAG;IACjC,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,SAAS,IAAI,MAAM,CAAC;IACpB,0FAA0F;IAC1F,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B;;;;OAIG;IACH,eAAe,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,iBAAiB,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtF;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,KAAK,CAAC;CACrB,CAAC;AAMF,MAAM,MAAM,oBAAoB,GAAG;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,KAAK,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjC,CAAC,CAAC;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACnC,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// Types shared between client SDK, resource-server scheme plugin, and facilitator.
+// These mirror the wire format defined in the facilitator package.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,mFAAmF;AACnF,mEAAmE"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "x402-sessions",
+  "version": "0.1.0",
+  "description": "Sign once, settle many times — session-based x402 payments on Stellar. One on-chain SAC approve unlocks unlimited micropayments via transfer_from until the cap or expiry is reached. No per-request wallet popup.",
+  "license": "MIT",
+  "author": "madhav",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./scheme": {
+      "types": "./dist/scheme-server.d.ts",
+      "default": "./dist/scheme-server.js"
+    },
+    "./stellar": {
+      "types": "./dist/stellar.d.ts",
+      "default": "./dist/stellar.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "x402",
+    "stellar",
+    "soroban",
+    "payments",
+    "micropayments",
+    "session",
+    "pay-per-call",
+    "sac",
+    "usdc",
+    "sign-once",
+    "settle-many",
+    "agentic-payments"
+  ],
+  "peerDependencies": {
+    "@stellar/stellar-sdk": "^14.0.0 || ^15.0.0",
+    "@x402/core": "^2.8.0"
+  },
+  "peerDependenciesMeta": {
+    "@x402/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@stellar/stellar-sdk": "^15.0.1",
+    "@types/node": "^22",
+    "@x402/core": "^2.8.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}