create-x402-sessions-facilitator

Scaffold a ready-to-run x402-sessions facilitator service in one command.

npm create x402-sessions-facilitator@latest my-facilitator
cd my-facilitator
npm run dev

That's it. The scaffold:

1. Copies a fresh facilitator template into ./my-facilitator
2. Runs npm install for you
3. Generates a fresh Stellar testnet keypair
4. Funds the keypair via friendbot
5. Writes .env with the signing secret pre-filled

By the time you cd in, you can npm run dev and the facilitator is live on http://localhost:4021.

What you get

A small Express + better-sqlite3 service implementing the x402 facilitator HTTP API plus the session scheme extension:

GET  /health                 — liveness + facilitator address
GET  /supported              — x402 spec: advertise scheme/network kinds
POST /verify                 — x402 spec: stateless session payload check
POST /settle                 — x402 spec: re-verify + debit + on-chain transfer_from
POST /sessions               — create a session from a signed approval tx hash
GET  /sessions/:id           — inspect session state (cap / spent / expiry)

The facilitator:

• Verifies on-chain allowance(user, facilitator) when a session is created
• Persists sessions atomically in sqlite (WAL mode)
• Executes transfer_from(facilitator, user, recipient, amount) on every /settle
• Rolls back sqlite debits if the on-chain call fails
• Enforces a per-call amount policy (MAX_PER_CALL env var) as an off-chain safety rail on top of the SAC's on-chain cap + expiry

Options

npm create x402-sessions-facilitator@latest [target-dir] [options]

| Flag | What | |---|---| | --skip-install | Don't run npm install after copying the template | | --skip-fund | Don't friendbot the generated keypair (useful when offline or for pubnet setup) |

Pubnet usage

The scaffold generates a testnet keypair by default. For pubnet:

1. Generate + fund a pubnet keypair yourself
2. Edit .env:

   STELLAR_NETWORK=stellar:pubnet
   SOROBAN_RPC_URL=https://soroban-rpc.mainnet.stellar.gateway.fm
   NETWORK_PASSPHRASE=Public Global Stellar Network ; September 2015
   FACILITATOR_SECRET=<your funded pubnet secret>
   USDC_CONTRACT_ID=CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75

3. Run npm run dev

Companion SDK

Pair the facilitator with the x402-sessions client SDK in your dapp / agent / resource server.

License

MIT