API Reference

The ad-network service runs on port 4080. Endpoints are accessed in three ways:

• Agent API (public, x402-gated): https://x402ads.io/v1/agent/* — wallet-authenticated via x402 payment
• Admin proxy (internal): dexter.cash/api/ads/* — proxied through the Next.js app
• Direct (localhost only): http://localhost:4080/v1/* — for the facilitator and internal services

Agent API (x402-gated)

Public at x402ads.io. Every call requires an x402 payment. The paying wallet is the advertiser identity.

PayTo: FyuUZwAGudGpGjjgfDSWKYXdMczcTsFCbSmWBVhaDuwZ

Responses include _hint (human-readable next step) and _actions (machine-readable links). The API is discoverable in the Dexter Bazaar marketplace.

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.

Publisher Earnings

GET /v1/publisher/earnings?host=X

Publisher earnings aggregated by host. Returns total impressions, volume, per-endpoint breakdown, and payout history.

GET /v1/publisher/endpoints?host=X

Per-endpoint stats for a publisher host. Returns endpoint path, impressions, sponsored impressions, fill rate, and last active time.

GET /v1/publisher/hosts

List all publisher hosts with impression counts. Used by the publisher dashboard host selector.

Payouts

GET /v1/payouts

List all payout records (admin). Returns recipient type, wallet, amount, network fee, net payout, tx hash, and status.

GET /v1/payouts/:wallet

Payout history for a specific publisher wallet or host ID.

POST /v1/payouts/trigger

Manually trigger a daily payout cycle (admin). Aggregates publisher earnings for the previous day, creates payout records, and executes on-chain USDC transfers.

Stats

GET /v1/stats

Public aggregate network stats. Cached for 60 seconds. Available at x402ads.io/v1/stats.

{
  "activeCampaigns": 1,
  "totalSettlementEvents": 39001,
  "totalImpressions": 39001,
  "totalConversions": 0,
  "totalBudgetRemaining": "39713000",
  "updatedAt": "2026-03-21T06:55:32.103Z"
}

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
}