x402 Stacks API Host

A Cloudflare Worker that exposes APIs on a pay-per-use basis using the x402 protocol on Stacks.

Environments

Environment	Base URL	Network	Docs
Production	https://x402.aibtc.com	mainnet	/docs
Staging	https://x402.aibtc.dev	testnet	/docs

API Categories

• /inference/* - LLM chat completions (OpenRouter, Cloudflare AI)
• /stacks/* - Blockchain utilities (address, decode, profile, verify)
• /hashing/* - Clarity-compatible hashing functions
• /storage/* - Stateful operations (KV, paste, DB, sync, queue, memory)

Full endpoint documentation available at /docs.

Payment

All paid endpoints use the x402 v2 protocol with base64-encoded JSON headers.

Supported tokens: STX, sBTC, USDCx (via X-PAYMENT-TOKEN-TYPE header)

Flow:

1. Request endpoint without payment → receive HTTP 402 with payment-required header
2. Sign transaction and resend with payment-signature header
3. Payment verified, response includes payment-response header

Headers:

• payment-signature (request): Base64-encoded payment payload
• payment-required (402 response): Base64-encoded payment requirements
• payment-response (success): Base64-encoded settlement result
• X-PAYMENT-TOKEN-TYPE (optional): Token selector (STX, sBTC, USDCx)

Development

npm install      # Install dependencies
npm run dev      # Local development
npm run check    # Type check

Note: Do not run npm run deploy directly. Commit and push for automatic deployment.

Testing

E2E payment tests against live endpoints using the x402 protocol.

Setup

# Copy and configure environment
cp .env.example .env

# Set your testnet mnemonic (NEVER use mainnet funds!)
export X402_CLIENT_PK="your twelve word testnet mnemonic"

# Optional: target staging instead of localhost
export X402_WORKER_URL=https://x402.aibtc.dev

Run Tests

npm test              # Quick mode - stateless endpoints, STX only
npm run test:full     # Full mode - includes lifecycle tests
npm run test:verbose  # With debug output
npm run test:kv       # Just KV lifecycle test

# Filter by category or name
bun run tests/_run_all_tests.ts --category=hashing
bun run tests/_run_all_tests.ts --filter=sha256 --all-tokens

Rollout Check

For the immediate-pay-per-call stabilization path, run a focused staging or production check against a cheap paid endpoint:

export X402_WORKER_URL=https://x402.aibtc.dev
bun run tests/_run_all_tests.ts --filter=sha256 --token=STX --retries=2 --verbose

On any retryable 402 during this check, confirm the body stays on canonical caller-facing semantics:

• status never returns submitted
• paymentId is present before retrying the same payment
• terminalReason is the normalized terminal signal when present
• checkStatusUrl is treated as additive when present

Test Modes

Mode	Description
quick	Stateless endpoints only (hashing, stacks, inference)
full	Stateless + lifecycle tests for stateful endpoints

Automated Testing

# Cron job (runs hourly, logs only on failure)
0 * * * * /path/to/x402-api/scripts/run-tests-cron.sh

License

MIT