genesispay-js

JavaScript/TypeScript SDKs for GenesisPay — stablecoin payments over HTTP 402 (x402) that work for both humans and AI agents. USDC on Base; every amount is integer minor units, never floats.

Package	What it does
@genesis-tech/genesispay-seller	Framework-agnostic payment gate: wrap any Fetch-API handler (Next.js, Hono, Bun) and it becomes a paid x402 endpoint.
@genesis-tech/genesispay-agent	Agent-side client: pay x402-gated URLs (GET, or POST with an exact JSON body) from a policy-guarded agent wallet, discover payable services and shops, handle human approvals.
@genesis-tech/genesispay-mcp	MCP stdio server (npx @genesis-tech/genesispay-mcp) exposing genesispay_discover / genesispay_shops / genesispay_quote / genesispay_shipping_profile / genesispay_pay / genesispay_payment_status / genesispay_account and more (16 tools, plus an MCP App product card) to Claude and other MCP clients.
@genesis-tech/genesispay-protocol	Pure x402 V2 types, header codecs, validators, and EIP-3009 typed-data helpers. Zero I/O.

Sell: gate an endpoint

import { createPaymentGate, genesisPaySettlement } from "@genesis-tech/genesispay-seller";

const gate = createPaymentGate({
  amountUsdc: "0.10",
  payTo: "0xYourWallet",
  description: "Premium market data",
  network: "base-sepolia",
});

export const GET = gate.wrap(async () => Response.json({ data: "…" }), {
  verifySettlement: genesisPaySettlement({
    facilitatorBaseUrl: "https://your-genesispay-instance.example",
    apiKey: process.env.GENESISPAY_SELLER_KEY!, // gp_sk_...
  }),
});

Buy: pay from an agent

import { GenesisPayAgent } from "@genesis-tech/genesispay-agent";

const agent = new GenesisPayAgent(); // env: GENESISPAY_AGENT_KEY, GENESISPAY_BASE_URL

const [service] = await agent.discover("weather api");
// Persist the key with your order before the first call, then reuse it on retries.
const result = await agent.pay(service.resourceUrl, { idempotencyKey: "saved-order-42", maxAmountUsdc: "0.50" });

if (result.settled) if (result.response) console.log(result.json()); // Replay has no captured resource body.
else console.log("Needs human approval:", result.approvalUrl);

Spending caps, allowlists, and approvals are enforced server-side by GenesisPay — the agent key never holds a raw private key.

Give your AI agent the tools

claude mcp add genesispay \
  --env GENESISPAY_AGENT_KEY=gp_ag_your_key \
  --env GENESISPAY_BASE_URL=https://your-genesispay-instance.example \
  -- npx -y @genesis-tech/genesispay-mcp

See GenesisTechAT/genesispay-agent-skill for the full agent skill (discovery-then-pay pattern, approval handling) and config snippets for other MCP clients.

Development

npm ci
npm run build   # tsc -b, dependency order
npm test        # vitest, tests run from package sources

Node >= 20.9. Each package builds to dist/ with tsc; tests are colocated (src/*.test.ts).

This repository is a read-only publish mirror — development happens in the main GenesisPay repository and is synced here. Issues and PRs are welcome and are folded back upstream.

Releasing

1. Bump versions in packages/*/package.json.
2. Confirm npm Trusted Publishing authorizes .github/workflows/publish.yml for every package. The workflow uses GitHub OIDC (id-token: write); it does not read an NPM_TOKEN secret.
3. Tag the reviewed snapshot and push that tag.
4. The publish workflow builds, tests, verifies pack manifests, and publishes only package versions absent from npm.

License

MIT © GenesisTech