API Reference

The ad-network service runs on port 4080. In production, all endpoints are accessed through the Next.js API proxy at /api/ads/*.

Campaign Matching

POST /v1/match

Called by the facilitator at settle-time to find a matching campaign for the settled resource.

Request:

{
  "resourceUrl": "https://x402.dexter.cash/api/jupiter/quote",
  "resourceDescription": "Jupiter swap quote",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "payerWallet": "7nY2Bq...",
  "settledAmount": "50000"
}

Response (matched):

{
  "matched": true,
  "campaignId": "604b09ca-e246-45ed-96ce-003711e22a7d",
  "recommendation": {
    "resourceUrl": "https://x402.dexter.cash/api/tools/solscan/trending",
    "description": "Solscan Trending Tokens, 0.05 USDC per call",
    "sponsor": "Dexter"
  },
  "impressionBeacon": "http://localhost:4080/v1/track/impression/604b09ca...",
  "conversionResource": "https://x402.dexter.cash/api/tools/solscan/trending"
}

Response (no match):

{ "matched": false }

Campaigns

GET /v1/campaigns

List all campaigns with advertiser info.

GET /v1/campaigns/:id

Get a single campaign by ID.

POST /v1/campaigns

Create a new campaign.

Required fields: advertiser_id, name, budget_total, budget_daily, max_bid_amount, schedule_start, rec_resource_url, rec_description, rec_sponsor_name

Optional fields: target_categories, target_networks, target_transports, target_url_patterns, schedule_end, rec_bazaar_id, bid_strategy

All budget/bid amounts are in atomic USDC (6 decimals). 1000000 = 1.00 USDC.

PATCH /v1/campaigns/:id

Update campaign fields.

POST /v1/campaigns/:id/activate

Set campaign status to "active". The campaign immediately starts matching.

POST /v1/campaigns/:id/pause

Set campaign status to "paused". The campaign stops matching.

Advertisers

GET /v1/advertisers

List all advertisers.

POST /v1/advertisers

Register a new advertiser.

Required fields: name, wallet_address, network

Settlement Events

POST /v1/events

Record a settlement event from the facilitator. Called automatically by the facilitator after every sponsored settlement.

Request:

{
  "txHash": "5xK9ab3...",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "resource": {
    "url": "https://x402.dexter.cash/api/jupiter/quote",
    "description": "Jupiter swap quote"
  },
  "payer": "7nY2Bq...",
  "settledAmount": "50000",
  "campaignId": "604b09ca...",
  "timestamp": "2026-03-05T14:30:50.428Z"
}

GET /v1/events

List recent settlement events. Accepts ?limit=N (default 50).

Conversions

POST /v1/conversions

Record a conversion (agent called a recommended resource).

Request:

{
  "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"
}

GET /v1/campaigns/:id/conversions

Get all conversions for a campaign.

Publisher Manifest

GET /v1/manifest

Returns active campaigns for the publisher middleware (Model B). Publishers poll this periodically to cache campaign data locally.

Impression Beacon

GET /v1/track/impression/:campaignId

Impression beacon endpoint. HTTP clients fire this URL to confirm recommendation delivery. Returns 204 No Content.

Health

GET /healthz

Service health check. Returns service name, version, and Bazaar resource count.

{
  "status": "ok",
  "service": "x402-ads",
  "version": "0.1.0",
  "bazaarResources": 0
}