# x402 Ads — Instinct (full reference)

> The advertising network for AI agents. Instinct attaches a sponsored recommendation to x402-protocol settlement responses. Conversion-priced: advertisers pay only when a recommendation converts into a real on-chain settlement. This file is the complete agent reference; the short overview is at https://x402ads.io/llms.txt.

## What Instinct is

Instinct is the guided-commerce layer for x402 (HTTP 402 Payment Required, USDC-settled across Solana, Base, Polygon, Arbitrum, Optimism, Avalanche, BSC, SKALE). Built by Dexter, it runs through the Dexter x402 facilitator at https://x402.dexter.cash.

When an agent settles a payment, the facilitator checks whether a campaign matches the resource. If one does, the recommendation is injected into the x402 SettlementResponse — the PAYMENT-RESPONSE header on HTTP, `_meta` on MCP. The buyer installs nothing; the seller integrates nothing. The recommendation travels inside the protocol.

A conversion is cryptographically provable: it either became a real on-chain USDC settlement or it did not. Pricing models: CPM (per thousand impressions), CPC (per click), CPA (per conversion), and hybrid. CPA is the default.

## Authentication model

The campaign API is x402-gated. There is no signup and no API key. The wallet that pays the x402 charge IS the advertiser identity — the facilitator resolves it to an advertiser account automatically on first use. Pay from the same wallet to manage the same campaigns.

## Base URL

All agent routes: https://x402ads.io/v1/agent/

## Discovery — start here

GET https://x402ads.io/v1/agent/campaigns/schema (free, no payment)

Returns the full self-describing contract: every field for creating, funding, and updating a campaign, with type, whether required, defaults, and a complete working example payload. An agent should fetch this before constructing a create request.

## Endpoint: create a campaign

POST https://x402ads.io/v1/agent/campaigns
x402-gated: 0.10 USDC. The paying wallet becomes the advertiser.

Request body fields:

- name — string, required. Human-readable campaign name.
- rec_sponsor_name — string, required. Advertiser/sponsor name shown with the recommendation.
- rec_resource_url — string (URL), required. The x402 endpoint agents are recommended to.
- rec_description — string, required. One-line pitch the agent sees in the settlement response.
- max_bid_amount — string, required. ATOMIC USDC (6 decimals). "250000" = 0.25 USDC. Maximum bid per auction win.
- schedule_start — string (ISO 8601), required. When the campaign becomes eligible, e.g. "2026-05-16T12:00:00Z".
- bid_strategy — enum cpm|cpc|cpa|hybrid, optional, default "cpa".
- budget_daily — string atomic USDC, optional, default "0" (no daily cap).
- target_categories — string[], optional, default []. Empty matches all categories.
- target_networks — string[] of CAIP-2 ids, optional, default []. Empty matches all networks.
- schedule_end — string (ISO 8601), optional. Omit for no end.

Example request body:

{
  "name": "Acme weather API — Q2 push",
  "rec_sponsor_name": "Acme Inc.",
  "rec_resource_url": "https://api.acme.com/v1/forecast",
  "rec_description": "High-accuracy hourly weather forecasts. 0.01 USDC per call.",
  "max_bid_amount": "250000",
  "schedule_start": "2026-05-16T12:00:00Z",
  "bid_strategy": "cpa",
  "budget_daily": "0",
  "target_categories": ["weather", "data"],
  "target_networks": []
}

Response: the created campaign with status "draft" and budget_remaining "0", plus `_hint` and `_actions` pointing to the fund step.

## Endpoint: fund a campaign

POST https://x402ads.io/v1/agent/campaigns/{id}/fund
x402-gated: the USDC amount you pay IS the campaign budget deposit.

Request body:

- amount — string, required. USD dollars, NOT atomic. "0.50" funds the campaign with 0.50 USDC. Note this differs from max_bid_amount, which is atomic.

Example: { "amount": "0.50" }

The x402 payment settles, and the backend credits budget_total and budget_remaining by that amount. The endpoint is idempotent on the payment transaction hash — re-submitting the same funded transaction returns "deposit already recorded" rather than double-crediting.

## Endpoint: activate

POST https://x402ads.io/v1/agent/campaigns/{id}/activate — 0.01 USDC.
Flips a draft or paused campaign to "active" so it matches settlements. Fails if budget_remaining is zero (fund first).

## Endpoint: pause

POST https://x402ads.io/v1/agent/campaigns/{id}/pause — 0.01 USDC.
Pauses an active campaign. It stops matching settlements until reactivated.

## Endpoint: update

PATCH https://x402ads.io/v1/agent/campaigns/{id} — 0.05 USDC.
Updates campaign targeting and bid. See the `update` section of /v1/agent/campaigns/schema for the patchable field list.

## Endpoint: list campaigns

GET https://x402ads.io/v1/agent/campaigns — 0.01 USDC.
Lists campaigns owned by the calling wallet. Supports `status`, `limit`, `offset` query params.

## Endpoint: campaign detail

GET https://x402ads.io/v1/agent/campaigns/{id} — 0.01 USDC.
Full campaign detail with impression/conversion stats, deposits, and recent conversions.

## Endpoint: analytics

GET https://x402ads.io/v1/agent/analytics — 0.02 USDC.
Cross-campaign performance for the calling wallet.

## Endpoint: escrow / funding info

GET https://x402ads.io/v1/agent/escrow — free.
Explains how campaign funding works over x402.

## Navigation

Every response includes `_hint` (plain-language next step) and `_actions` (an array of {rel, method, path} next-callable endpoints). An agent can drive the entire API by following `_actions` from any response, with no out-of-band documentation.

## Typical agent flow

1. GET /v1/agent/campaigns/schema — read the contract.
2. POST /v1/agent/campaigns with the fields above — pays 0.10 USDC, campaign created as draft.
3. POST /v1/agent/campaigns/{id}/fund with { amount } — pays the budget in USDC.
4. POST /v1/agent/campaigns/{id}/activate — campaign goes live.
5. GET /v1/agent/campaigns/{id} or /v1/agent/analytics — monitor performance.

## Related

- x402 protocol: https://github.com/x402-foundation/x402
- Dexter facilitator: https://x402.dexter.cash
- Indexter explorer (formerly x402gle): https://x402gle.com/explorer/instinct
- Web campaign creation: https://x402gle.com/explorer/instinct/create
- Source: https://github.com/Dexter-DAO/x402-ads