# Instinct — Guided Agent Commerce (full reference)

> Instinct is the guided-commerce network for AI agents on the x402 payment protocol. It writes a recommendation for an agent's next API call into the settlement response of the call it just paid for, so the agent skips a blind search and the recommended endpoint is reached at the moment it is the answer. Conversion-priced: the advertiser pays only when the recommendation turns 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.

The useful part of advertising was never the ad. It was the routing: matching demand to supply at the moment demand appeared. An agent mid-task has just paid for one API and has a goal, and nothing connects the two; left alone it searches, guesses, and burns tokens. Instinct is the layer that closes that gap. It is not a quieter ad unit; it is the discovery mechanism the agentic web was missing.

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 guided call leaves the agent better off than a plain one. It arrives with the next step already chosen instead of leaving the agent to hunt for it, so the agent has no reason to refuse it. Instinct calls that property negative friction, and it is why guidance works where advertising could not.

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

There is no signup and no API key. Identity is the wallet, proven two ways: an x402 payment, or a Sign-In-With-X (CAIP-122) signature. The wallet that pays or signs IS the advertiser identity; it resolves to an advertiser account automatically on first use. Use the same wallet to manage the same campaigns.

Informational endpoints — create a draft campaign, list campaigns, read campaign detail, read analytics — are SIW-X-or-pay: free with a SIGN-IN-WITH-X signature in the SIGN-IN-WITH-X header, or x402-gated in USDC if no signature is sent. Endpoints that move budget — fund, activate, pause, update — are always x402-gated. Per-route prices are listed under each endpoint below.

## 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
Free with a SIGN-IN-WITH-X wallet signature, or 0.10 USDC via x402. The signing or paying wallet becomes the advertiser. A draft campaign holds zero budget and matches nothing until funded, so creating one is informational — a signature proves identity without the fee.

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.
- target_transports — string[], optional, default []. Empty matches all transports.
- target_url_patterns — string[], optional, default []. Match settlements whose resource URL matches these patterns.
- rec_bazaar_id — string, optional. Bazaar listing id associated with the recommendation.
- 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 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 USD of budget. Note this differs from max_bid_amount, which is atomic.
- asset — string, optional, "usdc" (default) or "dexter". With "usdc" you pay the full USD amount in USDC. With "dexter" you pay in the DEXTER token at a 25% discount — 75% of the USD value in DEXTER — and the campaign is still credited the full USD budget. The DEXTER amount is quoted live at request time.

Example: { "amount": "0.50" } — or { "amount": "0.50", "asset": "dexter" }

The x402 payment settles, and the backend credits budget_total and budget_remaining by the full USD amount regardless of which asset paid. 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 — free with a SIGN-IN-WITH-X signature, or 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} — free with a SIGN-IN-WITH-X signature, or 0.01 USDC.
Full campaign detail with impression/conversion stats, deposits, and recent conversions.

## Endpoint: analytics

GET https://x402ads.io/v1/agent/analytics — free with a SIGN-IN-WITH-X signature, or 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 — free with a SIGN-IN-WITH-X signature, or 0.10 USDC; campaign created as draft.
3. POST /v1/agent/campaigns/{id}/fund with { amount } — pays the budget in USDC, or in DEXTER for a 25% discount.
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