Facilitator

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

URL

https://facilitator.shadowfeed.app

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.

curl https://facilitator.shadowfeed.app/supported

{
  "x402Version": 2,
  "kinds": [
    {
      "scheme": "exact",
      "network": "stacks:1",
      "asset": "STX"
    },
    {
      "scheme": "exact",
      "network": "stacks:2147483648",
      "asset": "STX"
    }
  ]
}

POST /verify

Validates a signed transaction without broadcasting it.

curl -X POST https://facilitator.shadowfeed.app/verify \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": { "payload": { "transaction": "hex..." } },
    "paymentRequirements": { "amount": "5000", "payTo": "SP1DV..." }
  }'

{
  "valid": true,
  "payer": "SP2PBB...",
  "invalidReason": null
}

POST /settle

Broadcasts the transaction and waits for confirmation.

curl -X POST https://facilitator.shadowfeed.app/settle \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": { "payload": { "transaction": "hex..." } },
    "paymentRequirements": { "amount": "5000", "payTo": "SP1DV..." }
  }'

{
  "success": true,
  "payer": "SP2PBB...",
  "transaction": "0xabc123...",
  "network": "stacks:1"
}

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