agentic-ad-exchange: Instructions file for Claude Code

CLAUDE.md — Agentic Ad Exchange Stack

AI behavior guide for this repository. This is a hackathon project for Circle's Nanopayments on Arc hackathon. Calibrate strictness accordingly: payment, auction, and wallet code needs rigor; demo UI does not.

---

Project Awareness & Context

Read these in this order:

1. README.md — runnable commands and Quick Start. Note: its "Still TODO" paragraph is stale; trust the code and REPO_SUMMARY.md instead.
2. Optional local context — these are untracked working notes that may or may not exist on a given checkout. Read them if present; do not block on them if missing:
   • PLANNING.md — architecture, data model.
   • hackathon-context.md — submission brief, tracks, judging criteria.
   • agentic-ad-exchange-stack.md — short product spec.
   • architecture-diagram.md — Mermaid system / payment / data diagrams.
   • ai-agent-micropayments-validation.md — strategy / framing.
   • tutorials/ — known-good Circle SDK / x402 / LangChain patterns. If present, consult before writing novel SDK code (these SDKs change fast). If absent, mirror existing usage in wallets/src/circleAdapter.ts and server/src/middleware/nanopayments.ts.

Before starting a new task: check the task list (via the Task tool). If the task isn't tracked, add it.

Non-negotiable hackathon constraints

Every code path that contributes to the demo must be compatible with:

• Per-action pricing ≤ $0.01 (USDC on Arc)
• ≥ 50 on-chain transactions visible in the submission demo
• Margin explainer — the model must be demonstrably uneconomic on traditional rails

If a design choice breaks any of the above, flag it before building.

---

Project Structure

pnpm-workspaces monorepo. Do not reshape it without flagging the change.

agentic-ad-exchange/
├── server/         # @ade/server         — Express API (matching, auction, SSE, x402 middleware)
├── shared/         # @ade/shared         — zod schemas, constants, env loader (zero runtime deps)
├── wallets/        # @ade/wallets        — Circle DCW SDK wrapper (server-side only)
├── agents/
│   ├── buyer/      # @ade/agents-buyer   — Buyer agent (Gemini + LangGraph) + tools
│   └── seller/     # @ade/agents-seller  — Seller agent (Gemini + LangGraph) + tools
├── ui/             # @ade/ui             — React + Vite + Tailwind dashboard
├── scripts/        # @ade/scripts        — Wallet provisioning, Gateway deposit, demo:load (≥50 cycles)
└── .env.example