Citely-x402

An open MCP server that gates content & tools behind x402 stablecoin micropayments — with a pluggable content provider and a pluggable payment network (Base today, GOAT Network as the headline integration).

Most "agent payments" demos rebuild x402 from scratch. This repo extracts a clean, reusable gateway: an MCP server exposing search_articles + get_article, gated by a free-quota entitlement and then x402 pay-per-call. Two seams keep it generic and keep any proprietary data out.

Quickstart

pnpm install
cp .env.example .env      # defaults to base-sepolia
pnpm example              # boots the gateway on http://localhost:3402
pnpm tsx scripts/agent-client.ts   # discovers → hits the 402

The 402 → pay → 200 flow, end to end:

# 1) No payment → 402 with the x402 payment requirements
curl -i http://localhost:3402/api/read/stablecoin-licensing-basics
#   HTTP/1.1 402
#   [{"scheme":"exact","network":"eip155:84532","maxAmountRequired":"300000",
#     "asset":"0x036CbD…","payTo":"0x…","resource":"/read/stablecoin-licensing-basics"}]

# 2) With an X-PAYMENT proof → 200 with the body
curl -H "x-payment: <proof>" http://localhost:3402/api/read/stablecoin-licensing-basics

Architecture

                 x-citely-account (ERC-8004 id)
   AI agent ───────────────────────────────────────┐
      │  MCP: search_articles / get_article         │
      │  or   GET /api/read/:slug                    ▼
      │                                     ┌──────────────────┐
      └────────────────────────────────────▶│  gateway         │
                                             │  1. entitlement  │  free quota per account
                                             │  2. x402 paywall │  402 → USDC → 200
                                             │  3. ContentProvider ─▶ your catalog/body
                                             └──────────────────┘

Two seams isolate everything specific to your deployment:

ContentProvider (src/content/provider.ts) — listCatalog() / getContent(slug). The repo ships sampleContentProvider with dummy public content. Bring your own by implementing the interface.
PaymentNetwork (src/payment/network.ts) — { id, caip2, usdcAddress, buildResourceServer() }. Ships a Base-Sepolia adapter and a GOAT adapter.

Swap the payment network

Set X402_NETWORK (see .env.example):

`X402_NETWORK`	CAIP-2	Facilitator / token
`base-sepolia` (default)	`eip155:84532`	Coinbase CDP (`CDP_API_KEY_ID` / `_SECRET`); USDC `0x036CbD…`
`goat-testnet`	`eip155:48816`	`GOAT_FACILITATOR_URL` + `GOAT_USDC_ADDRESS`
`goat-mainnet`	`eip155:2345`	`GOAT_FACILITATOR_URL` + `GOAT_USDC_ADDRESS`

GOAT is an EVM-compatible, Bitcoin-secured L2, so the same ExactEvmScheme (EIP-3009 USDC) applies. See docs/goat-integration.md and docs/erc-8004-identity.md.

Bring your own content

import { createGatewayMcpHandler } from "citely-x402";
import type { ContentProvider } from "citely-x402";

const myProvider: ContentProvider = {
  listCatalog: (q) => /* your catalog */ [],
  getContent: (slug) => /* your body + provenance */ null,
};

const handler = createGatewayMcpHandler({
  provider: myProvider, store: myUsageStore, freeLimit: 3, subscribeUrl: "https://…",
});
export { handler as GET, handler as POST };

Relation to Citely

This is the open x402/MCP gateway. Citely (private) plugs its own provenance-backed content provider into these same interfaces — the proprietary content, on-chain (EAS) provenance, and expert-review pipeline stay private. Nothing in this repo is Citely content; the shipped provider is dummy sample data.

License

MIT — see LICENSE.