HTTP 402 payments for AI agents on Stacks Bitcoin L2.
Monetize MCP tool calls with STX, sBTC, or USDCx — no custodial intermediaries, no subscriptions, pay-per-call.
- Client calls a tool through the gateway
- Gateway returns HTTP 402 with a
payment-requiredheader (base64 JSON listing accepted tokens, price, recipient) - Client signs a Stacks transaction locally (private key never leaves the client)
- Client retries the same request with a
payment-signatureheader - Gateway settles the payment via an x402 relay and forwards the request to the upstream MCP server
| Service | URL |
|---|---|
| Dashboard | x402.stacks-ai.app |
| Gateway | gateway.stacks-ai.app |
| Moltbook | moltbook.stacks-ai.app |
| OpenAPI → MCP | openapi.stacks-ai.app |
| Documentation | x402-docs.stacks-ai.app |
| GitHub | Stack-AI-MCP/stackai-x402 |
- Node.js >= 18
- pnpm
- Redis (for gateway state and analytics)
git clone https://github.com/Stack-AI-MCP/stackai-x402.git
cd stackai-x402
pnpm install
pnpm build # builds SDK first, then gateway (turbo pipeline)
pnpm test # runs all testsimport { createAgentClient, generateAgentWallet, getBalance } from 'stackai-x402'
// Generate a wallet (or use an existing private key)
const wallet = generateAgentWallet('mainnet')
console.log(wallet.address) // SP...
// Check balance
const balance = await getBalance(wallet.address, 'mainnet')
// Create an HTTP client with automatic 402 payment handling
const client = createAgentClient(wallet.privateKey, 'mainnet')
// Call a tool -- 402 responses are handled transparently
const response = await client.post('https://gateway.example.com/mcp?id=server123', {
jsonrpc: '2.0',
method: 'tools/call',
params: { name: 'get-price', arguments: { token: 'STX' } },
id: 1,
})import { createAgent } from 'stackai-x402'
const agent = await createAgent('https://gateway.example.com', privateKey, {
name: 'DeFi Agent',
description: 'Bitcoin DeFi tools',
tools: [
{ serverId: 'srv_abc', toolName: 'swap-tokens', price: 0.01 },
{ serverId: 'srv_abc', toolName: 'get-price', price: 0 },
],
})See the SDK README for the full API reference.
cp apps/gateway/.env.example apps/gateway/.env
# Set GATEWAY_ENCRYPTION_KEY, REDIS_URL, RELAY_URL
pnpm --filter gateway devSee the Gateway README for environment variables and API routes.
pnpm --filter web devThe dashboard runs at http://localhost:3002. Set NEXT_PUBLIC_GATEWAY_URL to point to your gateway.
pnpm dev # start all packages in watch mode
pnpm --filter gateway dev # gateway only
pnpm --filter web dev # web dashboard only
pnpm --filter openapi-mcp dev # openapi-to-mcp converter
pnpm --filter stackai-x402 build # rebuild SDKpackages/sdk/src/
client/ x402 payment client -- automatic 402 retry with signed payments
server/ agent CRUD -- create, update, delete agents (signed requests)
proxy/ wallet generation, balance checks, agent discovery
hooks/ request lifecycle hooks (logging, monetization, analytics)
types/ shared TypeScript types (AgentConfig, AgentTool, etc.)
internal/ crypto utilities, price conversion (not re-exported)
apps/gateway/src/
routes/ HTTP routes (proxy, servers, agents, analytics, agent-card)
services/ auth (signature verification), registration (Redis storage)
config.ts environment variable schema (Zod validated)
apps/web/
app/ Next.js App Router (marketplace, chat, register, agents, analytics)
components/ UI components (landing, chat, agents, explorer, providers)
hooks/ wallet auth, x402 client hooks
lib/ utilities, x402 integration
apps/moltbook/src/
ai/ LLM content generation (OpenAI, Anthropic, template)
moltbook/ Moltbook API client with challenge solver
scheduler/ Heartbeat engine (configurable intervals)
state/ Agent state management
apps/openapi-mcp/src/
index.ts Converts any OpenAPI/Swagger spec into MCP tools (port 3004)
apps/docs/
src/content/ MDX documentation (guides, reference, getting started)
MIT