How It Works

The x402 protocol defines a SettlementResponse object that the facilitator returns after every successful payment. This object includes an extensions field. The facilitator injects recommendations into SettlementResponse.extensions["sponsored-access"]. The standard x402 middleware on every resource server encodes the full SettlementResponse and forwards it to the client as a PAYMENT-RESPONSE header (HTTP) or _meta["x402/payment-response"] (MCP).

Recommendations reach agents in two ways: via protocol metadata (headers and extensions) or via response body injection. Headers and extensions are visible to the network layer but not to the agent's LLM context. To surface recommendations where the LLM can see them, publisher middleware reads extensions["sponsored-access"] from the settlement response and injects a _x402_sponsored field into the JSON response body. The facilitator never modifies the response body; only middleware at the publisher can perform body injection.

The Flow

1. An agent pays for an API endpoint through the Dexter facilitator
2. The facilitator settles the payment on-chain
3. The facilitator checks if a campaign matches the resource URL
4. If matched, the recommendation is added to SettlementResponse.extensions["sponsored-access"]
5. The standard x402 protocol delivers the receipt (with recommendation) to the client
6. The agent receives the API response plus a recommendation for a related tool

By default (Model A), the publisher's response body is never modified. The recommendation travels in the payment receipt (headers or extensions). When the publisher enables response body injection (Model B), the middleware reads the recommendation from the settlement response and injects _x402_sponsored into the response body so the LLM can see it.

Model A: Facilitator-Native

The base layer. Zero publisher integration required.

The facilitator calls the ad-network match API after every successful settlement. If a campaign targets the resource URL pattern, the facilitator injects the recommendation into the settlement receipt before returning it to the resource server.

The resource server's existing x402 middleware encodes the full SettlementResponse (including the new extension) into the PAYMENT-RESPONSE header and sends it to the client. The resource server code is completely unmodified.

This works on every x402 publisher using the Dexter facilitator, immediately, without any integration.

Model B: Publisher Middleware

The premium upgrade. Publishers install the @dexterai/x402-ads-publisher npm package for additional features:

• Price discounts: The middleware reduces the payment amount. The advertiser subsidizes the difference.
• Response body injection: Set sponsoredAccess: true in the middleware config to inject recommendations into the response body as _x402_sponsored.
• Higher revenue share: Publishers who actively participate earn more per impression.
• Analytics: Publisher-side impression counts and fill rate tracking.

npm install @dexterai/x402-ads-publisher

import { withSponsoredAccess } from '@dexterai/x402-ads-publisher';
 
app.use('/api/data', withSponsoredAccess({
  publisherId: 'pub_abc123',
  apiKey: 'key_...',
  contentCategory: 'finance'
}));

Model A continues to run underneath. Model B adds capabilities on top.

For package-specific middleware documentation, use @dexterai/x402-ads-publisher Package Overview.

What the Client Receives

HTTP

The recommendation is in the PAYMENT-RESPONSE header (base64-encoded JSON), inside extensions["sponsored-access"]:

{
  "success": true,
  "transaction": "5xK9ab3...",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "extensions": {
    "sponsored-access": {
      "info": {
        "version": "1",
        "recommendations": [
          {
            "resourceUrl": "https://x402.dexter.cash/api/tools/solscan/trending",
            "description": "Solscan Trending Tokens: real-time trending data on Solana",
            "sponsor": "Dexter"
          }
        ]
      }
    }
  }
}

MCP

The recommendation is in _meta["x402/payment-response"].extensions["sponsored-access"]. The tool result content[] is untouched unless the publisher enables body injection.

A2A

The recommendation is in task message metadata at x402.sponsoredAccess.recommendations.

Response Body Injection (Model B)

When the publisher enables sponsoredAccess: true in the middleware config, the recommendation is also injected into the JSON response body as _x402_sponsored. This is the only way recommendations reach the agent's LLM context, since headers and receipt metadata are not visible to LLMs. Model A never modifies the response body.