Add Stacks to Your x402 App

Add Stacks payment support to your existing x402 app. Whether you're on EVM (Base) or Solana, this example shows the integration pattern.

Choose Your Starting Point

You Have	Guide
EVM/Base app with @x402/express	Add Stacks to EVM
Solana app with x402-solana or x402-next	Add Stacks to Solana
Nothing yet, starting fresh	Getting Started with Stacks x402
Need your own facilitator	Self-Hosting Guide

Quick Start

git clone https://github.com/aibtcdev/x402-crosschain-example
cd x402-crosschain-example
npm install
cp .env.example .env  # Add your Stacks address

npm run dev           # Express (port 3000)
npm run dev:hono      # Hono (port 3001)

npm run client:stacks # Test Stacks payment

Why Stacks?

Feature	What It Means
sBTC	Accept Bitcoin directly (programmable BTC on Stacks)
Bitcoin finality	Transactions anchored to Bitcoin's security
Multiple tokens	STX, sBTC, USDCx - let users pay how they want
Gasless support	Sponsor relay for AI agents

The Pattern

Adding Stacks to an existing x402 endpoint takes 3 steps:

// 1. CHECK for payment header (v2: unified across all networks)
const paymentSignature = req.header("payment-signature");

// 2. ADD Stacks to your 402 response
accepts: [
  { /* your existing EVM/Solana option */ },
  { scheme: "exact", network: "stacks:2147483648", asset: "STX", amount: "1000", ... }
]

// 3. ROUTE by network (decode base64 JSON payload)
const payload = JSON.parse(Buffer.from(paymentSignature, "base64").toString());
if (payload.accepted.network.startsWith("stacks:")) {
  return stacksMiddleware(req, res, next);
}

Your existing clients continue working unchanged. Stacks clients get a new payment option.

Protocol Version

This implementation uses x402 v2 protocol with the unified Payment-Signature header (base64-encoded JSON).

Network	Header	Status
EVM (Base)	Payment-Signature	✓
Solana	Payment-Signature	✓
Stacks	Payment-Signature	✓

See x402 v2 spec.

Stacks Tokens

Token	Description
STX	Native Stacks token (default)
sBTC	Bitcoin on Stacks
USDCx	USDC on Stacks

Resources

Stacks x402

• x402-stacks - TypeScript client/server
• Stacks Facilitator - Payment verification
• Stacks x402 Spec
• Sponsor Relay - Gasless transactions

Self-Hosted Facilitators

• x402-stacks-facilitator - Lightweight Go facilitator
• OpenFacilitator - Multi-network platform with dashboard

x402 Protocol

• x402.org - Protocol home
• Coinbase x402 - Reference implementation

Other Networks

• Solana x402 Template - Solana Foundation
• x402-solana - PayAI

Live Examples

• x402.aibtc.dev - Testnet API
• x402.aibtc.com - Mainnet API

License

MIT