Add Stacks network support (Phase 1: Crosschain middleware)

[whoabuddy]

Summary

Add Stacks as a payment option alongside existing EVM networks using the crosschain middleware pattern.

Context

Enable Stacks payments without modifying the facilitator or building a new mechanism package. This is the lowest-friction path to multi-chain support.

Available infrastructure:

• x402-stacks SDK (v2.0.1)
• x402-stacks-facilitator (Go)
• OpenFacilitator (TypeScript, multi-chain including Stacks)
• x402-crosschain-example - reference pattern

Implementation

1. Install dependency

npm install x402-stacks

2. Add Stacks to 402 response accepts[]

accepts: [
  { scheme: "exact", network: "eip155:56", ... },  // existing BNB
  { scheme: "exact", network: "stacks:1", amount: "1000000",
    asset: "STX", payTo: stacksAddress, maxTimeoutSeconds: 300,
    extra: { facilitator: "https://facilitator.stacksx402.com" } }
]

3. Route by network prefix in Payment-Signature header

import { X402PaymentVerifier } from "x402-stacks";

const decoded = JSON.parse(atob(paymentSignature));
if (decoded.accepted?.network?.startsWith("stacks:")) {
  const stacksVerifier = new X402PaymentVerifier(facilitatorUrl);
  const result = await stacksVerifier.settle(decoded, {
    paymentRequirements: decoded.accepted,
  });
  // result: { success, transaction, payer, network }
}
// else: existing EVM middleware handles it

Networks (CAIP-2)

Network	ID
Mainnet	stacks:1
Testnet	stacks:2147483648

Tokens

Token	Asset Value	Decimals
STX	"STX"	6
sBTC	SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token::sbtc-token	8
USDCx	SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx::usdcx-token	6

Environment additions

# Add to existing .env
STACKS_ADDRESS=SP2YourStacksAddress
STACKS_NETWORK=mainnet
STACKS_FACILITATOR_URL=https://facilitator.stacksx402.com

Tasks

• Install x402-stacks alongside existing @x402/evm
• Add Stacks payment option to 402 response accepts[] array
• Implement Payment-Signature header routing by network prefix
• Add Stacks verifier using x402-stacks SDK
• Configure facilitator URL for Stacks
• Update example server (Hono) with Stacks support
• Test end-to-end: EVM client pays on BSC, Stacks client pays STX, same endpoint

References

• x402-crosschain-example - Reference pattern
• x402-stacks SDK docs