@clavestraorbital/x402-ecash

Fedimint eCash payment scheme for x402. Accept and pay with eCash via HTTP 402.

Install

npm install @clavestraorbital/x402-ecash

Quick Start

Server (accept eCash payments)

import { registerExactEcashScheme } from "@clavestraorbital/x402-ecash";

const scheme = registerExactEcashScheme({
  clientdUrl: "http://localhost:5000",
  clientdPassword: "your-password",
  federationId: "your-federation-id",
});

Client (pay with eCash)

import { ExactEcashClient } from "@clavestraorbital/x402-ecash/client";

const client = new ExactEcashClient({
  clientdUrl: "http://localhost:5000",
  clientdPassword: "your-password",
  federationId: "your-federation-id",
});

const payload = await client.createPaymentPayload(paymentRequirements);

How It Works

1. Agent requests a resource
2. Server returns 402 Payment Required with eCash payment requirements
3. Agent spends eCash notes via fedimint-clientd
4. Agent sends OOBNotes in PAYMENT-SIGNATURE header
5. Server reissues notes against the federation (atomic verify + settle)
6. Server returns the resource

No Lightning. No channels. No facilitator. Server redeems directly.

Architecture

Three independent scheme classes implementing @x402/core interfaces:

| Class | Subpath | Role | |-------|---------|------| | ExactEcashClient | @clavestraorbital/x402-ecash/client | Spends eCash, creates payment payloads | | ExactEcashFacilitator | @clavestraorbital/x402-ecash/facilitator | Verifies and settles payments | | ExactEcashServer | @clavestraorbital/x402-ecash/server | Extracts and validates payment headers |

Network Identifier

fedimint:<federation_id>

Custom CAIP-2 style identifier. Each federation is a unique payment network.

Configuration

import type { FedimintConfig } from "@clavestraorbital/x402-ecash";

const config: FedimintConfig = {
  clientdUrl: "http://localhost:5000",  // fedimint-clientd REST API
  clientdPassword: "your-password",     // clientd auth
  federationId: "your-federation-id",   // federation to use
  timeoutMs: 30_000,                    // optional, default 30s
};

Requirements

• fedimint-clientd running and connected to a federation
• @x402/core >= 2.0.0 (peer dependency)

License

MIT