Skip to main content

Facilitator

The facilitator is a Cloudflare Worker that verifies and settles x402 payments on the Stacks blockchain.

URL

Why a Custom Facilitator?

ShadowFeed built its own facilitator instead of using the official facilitator.stacksx402.com because:
  • The official facilitator returns 500 errors on /settle for mainnet transactions
  • Custom facilitator gives us full control over broadcast retry logic
  • Hiro API key integration for reliable transaction broadcasting
  • Better error messages for debugging

Endpoints

GET /supported

Returns supported networks and assets.

POST /verify

Validates a signed transaction without broadcasting it.

POST /settle

Broadcasts the transaction and waits for confirmation.

Implementation Details

  • Runtime: Cloudflare Workers (Hono framework)
  • TX Deserialization: @stacks/transactions v7
  • Broadcasting: Direct POST to Hiro API (/v2/transactions) with API key
  • Confirmation: Polls Hiro API for TX status (up to 25 seconds)
  • Address Derivation: c32address from signer hash for proper SP-prefix addresses
  • Retry Logic: 3 attempts with exponential backoff for 429 rate limits