Genesis402 - Stellar x402 Gateway

Genesis402 is a no-code monetization layer that wraps existing APIs with pay-per-request enforcement using x402 on Stellar.

What This Repo Contains

• backend/: Express + TypeScript API for agent management and paid gateway routing
• frontend/: Next.js UI for creating and testing paid agents
• random-number/: Sample external API + x402 client workflow script

How It Works

1. Create an agent that points to an external API
2. Call its generated paid endpoint (/agent/:id)
3. If no payment is attached, backend returns HTTP 402 + payment requirements
4. Client signs payment and retries with X-PAYMENT
5. Backend verifies + settles via facilitator, then proxies to the external API

Architecture

Client -> /agent/:id -> x402 middleware -> external API -> response
                                         (402 if payment missing/invalid)

Prerequisites

• Node.js 18+
• npm
• MongoDB (local or remote)
• A Stellar wallet for signing payments (for client-side payment flows)

Quick Start

1) Install all dependencies

From repo root:

npm run install:all

2) Create env files

From repo root:

npm run setup

This creates:

• backend/.env
• frontend/.env.local

Then update values as needed (especially MongoDB/facilitator credentials).

3) Start backend

npm run dev:backend
# http://localhost:3001

4) Start frontend

npm run dev:frontend
# http://localhost:3000

NOTE

You can also go within /backend and /frontend folders, create and fill .env, and use npm install and run commands to work with the folders:

npm install
npm run dev

x402 Flow (Current Implementation)

1. Client calls /agent/:id without X-PAYMENT
2. Server returns HTTP 402 and X-402-VERSION: 2
3. Response body includes x402Version: 2 and accepts[0] payment requirements
4. Client signs and sends X-PAYMENT: <base64 payload>
5. Backend verifies via facilitator /verify
6. Backend settles via facilitator /settle
7. Backend proxies request and returns result (X-PAYMENT-RESPONSE: payment-received)

Local Demo: Random Number API + Client

The random-number/ folder includes:

• a sample API server (server.js)
• a workflow client that performs x402 payment retries (x402-client.js)

Setup:

cd random-number
npm install

npm run install:all does not download dependencies in random-number folder, so you need to do npm install

Run random number generator server:

node server.js

To run agentic workflow script:

1. Edit the api url (and any other input necessary)
2. Run:

node x402-client.js

Edit WORKFLOW in random-number/x402-client.js to point at your generated agent endpoint(s).