Facilitator Integration

Any x402 facilitator can integrate with the sponsored-access system. The Dexter facilitator is the reference implementation, but the ad-network service is designed to work with multiple facilitators.

What You Need

Your facilitator must implement the standard x402 /settle endpoint
After a successful settlement, you call the ad-network match API
If a campaign matches, you inject the recommendation into SettlementResponse.extensions
You report the settlement event to the ad-network service

Step-by-Step

1. Register with the Ad Network

A facilitatorId identifying your facilitator
An API key for authenticating with the ad-network service
The base URL for the match and events APIs

2. Call the Match API After Settlement

After your facilitator settles a payment on-chain, call:

POST {AD_NETWORK_URL}/v1/match
Content-Type: application/json
Authorization: Bearer {API_KEY}

{
  "resourceUrl": "https://api.example.com/data",
  "resourceDescription": "Optional description",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "payerWallet": "7nY2Bq...",
  "settledAmount": "50000"
}

The response is either:

{ "matched": false }

Or:

{
  "matched": true,
  "campaignId": "604b09ca-...",
  "recommendation": {
    "resourceUrl": "https://x402.dexter.cash/api/tools/solscan/trending",
    "description": "Solscan Trending Tokens, 0.05 USDC per call",
    "sponsor": "Dexter"
  },
  "impressionBeacon": "https://ads.example.com/v1/track/impression/604b09ca...",
  "conversionResource": "https://x402.dexter.cash/api/tools/solscan/trending"
}

Use a timeout of 2 seconds or less. If the call fails or times out, skip the recommendation and return the normal settlement response. Never block settlement on the match API.

3. Inject into SettlementResponse

If a campaign matched, add the recommendation to SettlementResponse.extensions["sponsored-access"]:

{
  "success": true,
  "transaction": "tx_hash...",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "extensions": {
    "sponsored-access": {
      "info": {
        "version": "1",
        "recommendations": [
          {
            "resourceUrl": "https://x402.dexter.cash/api/tools/solscan/trending",
            "description": "Solscan Trending Tokens, 0.05 USDC per call",
            "sponsor": "Dexter"
          }
        ],
        "tracking": {
          "impressionBeacon": "https://ads.example.com/v1/track/impression/604b09ca...",
          "conversionResource": "https://x402.dexter.cash/api/tools/solscan/trending"
        }
      },
      "schema": { ... }
    }
  }
}

The standard x402 protocol delivers the full SettlementResponse to the client via the PAYMENT-RESPONSE header (HTTP) or _meta["x402/payment-response"] (MCP). No additional work is needed to deliver the recommendation to the client.

4. Report the Settlement Event

After injecting the recommendation, fire a POST to the events endpoint:

POST {AD_NETWORK_URL}/v1/events
Content-Type: application/json
Authorization: Bearer {API_KEY}

{
  "txHash": "5xK9ab3...",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "resource": {
    "url": "https://api.example.com/data",
    "description": "Optional"
  },
  "payer": "7nY2Bq...",
  "settledAmount": "50000",
  "campaignId": "604b09ca-...",
  "timestamp": "2026-03-05T14:30:50.428Z"
}

This should be fire-and-forget. Do not wait for a response. Do not block the settlement response on this call.

5. Optional: Conversion Tracking

For end-to-end conversion tracking, your facilitator can maintain an in-memory cache of recent recommendations (payer wallet to recommended resource URL). When a subsequent settlement arrives where the payer calls the recommended resource, report the conversion:

POST {AD_NETWORK_URL}/v1/conversions
Content-Type: application/json

{
  "originalTxHash": "5xK9ab3...",
  "conversionTxHash": "2kijHt5...",
  "campaignId": "604b09ca-...",
  "payerWallet": "7nY2Bq...",
  "convertedResourceUrl": "https://x402.dexter.cash/api/tools/solscan/trending",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "timestamp": "2026-03-05T14:31:04.056Z"
}

Reference Implementation

The Dexter facilitator implementation is at:

src/sponsoredAccess.ts in dexter-facilitator

This is a single file (~250 lines) that handles matching, injection, event reporting, and conversion tracking. It can be used as a reference for implementing the same logic in any x402 facilitator.

Requirements

Your facilitator must return the full SettlementResponse including extensions to the resource server
The standard @x402/core middleware already forwards the full response to clients
The match API call adds ~20ms latency to the settle path (measured in production)
Event reporting is async and adds zero latency

On this page