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

An agent pays for an API endpoint through the Dexter facilitator
The facilitator settles the payment on-chain
The facilitator checks if a campaign matches the resource URL
If matched, the recommendation is added to SettlementResponse.extensions["sponsored-access"]
The standard x402 protocol delivers the receipt (with recommendation) to the client
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 primary way recommendations reach the agent's LLM context.

Client SDK Helpers

The @dexterai/x402 SDK provides typed helpers for consuming recommendations programmatically:

import { getSponsoredRecommendations, fireImpressionBeacon } from '@dexterai/x402/client';
 
const recs = getSponsoredRecommendations(response);
if (recs) {
  for (const rec of recs) {
    console.log(`${rec.sponsor}: ${rec.description}`);
  }
  await fireImpressionBeacon(response); // Confirm delivery
}

The React hook useX402Payment surfaces recommendations automatically via sponsoredRecommendations and fires the impression beacon on delivery. See For Clients for full details.

Model A never modifies the response body — recommendations travel only in the PAYMENT-RESPONSE header unless a publisher opts into body injection.

OpenDexter Integration

OpenDexter (@dexterai/opendexter) is Dexter's x402 search engine, used by AI agents in Claude, ChatGPT, Cursor, Codex, VS Code, Windsurf, and Gemini CLI. When an agent calls x402_fetch through OpenDexter, sponsored recommendations are surfaced automatically.

OpenDexter uses the SDK's getSponsoredRecommendations() to extract recommendations from the PAYMENT-RESPONSE header, with a fallback that checks data._x402_sponsored in the response body. When recommendations are found, it fires fireImpressionBeacon() and returns them to the LLM as:

result.recommendations — the structured array of SponsoredRecommendation objects
result._recommendations_hint — a human-readable summary like "Sponsored: Solscan — Get trending Solana tokens. Call with x402_fetch if relevant."

This works across all three OpenDexter surfaces: the npm package (local MCP), the hosted Open MCP at open.dexter.cash/mcp, and the authenticated MCP at dexter.cash/mcp.

Voice Agent Integration

The Dexter voice agent (dexter-agents) has a system prompt segment that instructs the OpenAI Realtime model to notice _x402_sponsored in tool results and mention relevant recommendations naturally. A dedicated renderer component (SponsoredRecsSection) displays recommendations in the transcript UI when present.

On this page