FairAd

The open-source protocol for the agentic ad economy.

Merchants pay AI agents to prioritize and display their products during user conversations—with zero-config discovery, signed bidding, Proof of Human, and mandatory transparency. E-commerce transacts on the last mile of the conversation with proof, not promises.

Quick Start · Merchant onboarding · Concepts · Development

The Idea

Two parties, one protocol: merchants bid for placement; agents show sponsored recommendations only when a real human is in the loop. Every impression is attested, disclosed, and settled via a Proof of Impression receipt.

	🛒 Merchant	🤖 AI Agent
Goal	Get products in front of humans in conversation	Monetize the last mile with paid, verifiable ads
Deploys	.well-known/fairad.json + Merchant MCP	Discovery crawler + MCP client
Gets	Qualified impressions, settlement on proof	Payment commitment + rich product metadata
Guide	Merchant onboarding →	Concepts & protocol →

Features

• Zero-config discovery — fairad.json at domain.com/.well-known/fairad.json; crawler builds a local merchant directory for agents.
• Signed bidding — Merchant MCP returns product metadata (Markdown/JSON) and a Payment Commitment: a cryptographic promise to pay $X upon proof of human-verified impression.
• Proof of Human (PoH) — X-FairAd-Human-Token in the handshake; attestations from Worldcoin, Privy, or OIDC. Payment commitments are binding only when PoH is valid.
• Mandatory transparency — Sponsored replies must include "Sponsored Recommendation from [Merchant]"; the Proof of Impression hash includes this disclosure.
• Proof of Impression (PoI) — Ad-receipt combining bid signature + human token + disclosure hash; the invoice for settlement.

🚀 Quick Start

git clone https://github.com/Fairfetch-co/fairad.git
cd fairad
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
make setup-dev

For merchants — serve a manifest and run the Ad-Server

Host fairad.json at https://yourdomain.com/.well-known/fairad.json:

{
  "mcp_endpoint": "https://yourdomain.com/mcp",
  "public_key": "<base64 Ed25519 public key>",
  "bidding_categories": ["electronics", "apparel"],
  "currency": "USD",
  "min_bid": "100"
}

export FAIRAD_MERCHANT_DOMAIN=yourdomain.com
export FAIRAD_MERCHANT_NAME="Your Store"
python -m mcp_server.server

For AI agents — discover and query

# Discover merchants (crawls .well-known/fairad.json)
python examples/run_discovery.py example.com

# MCP Inspector: connect and call get_sponsored_context
npx @modelcontextprotocol/inspector python -m mcp_server.server

HTTP API (same semantics as MCP):

make dev-api
# API runs on http://localhost:8403
curl -X POST http://localhost:8403/sponsored-context -H "Content-Type: application/json" -d '{"category":"electronics"}'

HTTP API

Endpoint	Method	Description
/health	GET	Health check
/manifest	GET	FairAd manifest (same as .well-known/fairad.json)
/well-known/fairad.json	GET	Manifest at well-known path
/sponsored-context	POST	Body: { "category": "electronics", "amount": "100" }. Header: X-FairAd-Human-Token for binding commitment
/settlement/submit	POST	Submit Proof of Impression JSON; returns settlement_id
/settlement/status/{id}	GET	Status of a settlement

# Get sponsored context (no PoH)
curl -X POST http://localhost:8403/sponsored-context -H "Content-Type: application/json" -d '{"category":"electronics"}'

# Submit PoI for settlement
curl -X POST http://localhost:8403/settlement/submit -H "Content-Type: application/json" -d @receipt.json

Stricter Proof of Human (PoH)

Set FAIRAD_POH_STRICT=true to enforce:

• OIDC — When you have the raw token, use verify_poh_with_token(raw_token) to verify JWT signature against the issuer’s JWKS (.well-known/jwks.json).
• Worldcoin / Privy — Non-empty subject and (in strict mode) signature required.

Settlement ledger

The settlement ledger accepts PoI receipts at POST /settlement/submit. It validates:

• Payment Commitment signature (Ed25519)
• Disclosure hash format (sha256: + 64 hex chars)
• Unique poi_id (no duplicate submissions)

Optional: set FAIRAD_LEDGER_PATH=/path/to/ledger.json to persist settlements to disk. By default the ledger is in-memory.

Generate a Proof of Impression (Ad-Receipt)

python scripts/poi_generator.py \
  --commitment commitment.json \
  --human-token poh_token.json \
  --merchant-name "Example Merchant" \
  --snippet "Sponsored Recommendation from [Example Merchant]\nProduct snippet..." \
  -o receipt.json

Protocol at a glance

1. Discovery — Agent crawls /.well-known/fairad.json, gets mcp_endpoint, public_key, bidding_categories, min_bid.
2. Signed bidding — Agent calls Merchant MCP get_sponsored_context(category, amount?, human_token?). Receives product metadata + Payment Commitment (signed). Commitment is binding only if human_token is valid PoH.
3. Transparency — Agent must append "Sponsored Recommendation from [Merchant]" to the UI. Disclosure is hashed into the Proof of Impression.
4. Proof of Impression — On human-verified impression, agent builds PoI: commitment + PoH token id + disclosure hash. This is the settlement invoice.

📁 Project structure

fairad/
├── api/                      # HTTP API (REST wrapper)
│   ├── main.py               # FastAPI app, CORS
│   └── routes.py             # /manifest, /sponsored-context, /settlement
├── settlement/               # Ledger stub
│   └── ledger.py            # Accepts PoI, validates, persists (optional)
├── docs/
│   ├── CONCEPTS.md           # Protocol concepts and headers
│   ├── MERCHANT_ONBOARDING.md
│   ├── PROTOCOL_STANDARDS.md # RFCs and world standards
│   └── WELL_KNOWN_SPEC.md
├── interfaces/               # Open standard types
│   ├── manifest.py           # fairad.json schema
│   ├── payment.py            # Payment Commitment
│   └── poh.py                # Proof of Human attestation
├── core/                     # Signing, PoH, transparency, PoI
│   ├── signatures.py
│   ├── poh_verifier.py
│   ├── transparency.py
│   ├── transparency_middleware.py
│   ├── poi.py
│   └── url_validation.py     # SSRF protection
├── discovery/                # Zero-config discovery
│   └── crawler.py
├── mcp_server/               # Merchant MCP (Ad-Server)
│   ├── logic.py
│   └── server.py
├── scripts/
│   ├── poi_generator.py
│   └── run_api.py
├── examples/
│   ├── well-known/fairad.json
│   └── run_discovery.py
├── tests/
├── .github/workflows/
├── pyproject.toml
├── Makefile
└── LICENSE                   # Apache 2.0

Standards & security

FairAd follows world-standard protocols:

• Well-known URI — RFC 8615 for /.well-known/fairad.json.
• HTTPS — TLS in production; discovery blocks private IPs and SSRF targets.
• Ed25519 — RFC 8032 for Payment Commitments and PoI.
• JSON — RFC 8259; OIDC/JWT for Proof of Human.

See docs/PROTOCOL_STANDARDS.md for the full list. SECURITY.md for reporting and best practices.

📖 Detailed guides

Guide	What's inside
Merchant onboarding	Publish your manifest and run the Ad-Server
Concepts	Terms, headers, and flows in plain language
Protocol standards	RFCs and world standards (well-known, HTTPS, Ed25519)
Development	Local setup, running services, testing
Contributing	How to contribute, CLA, code standards
Security	Reporting vulnerabilities and security measures
Code of Conduct	Community standards

📄 License

Apache 2.0 — use it freely, commercially or otherwise.

---

Docs · Issues · Contributing

_{Built so merchants and AI agents can transact on the last mile of the conversation—with proof, not promises.}