Taffy (open-source ad network framework)

Self-hostable multi-app ad network: CPM/CPC campaigns, house inventory, wallet funding, agent HTTP API, optional console UI.

MIT licensed. Taffy is the reference deployment; any operator can white-label via env/config.

The supported runtime is Node.js 22–24 (.nvmrc is included). The hosted API and console are a monorepo deployment; the reusable SDK is independently installable as @taffy/ads.

Self-host for any project

cp .env.example .env
# Minimum demo without a chain:
#   SETTLEMENT_ADAPTER=mock
#   STORE_ADAPTER=sqlite
#   ADMIN_WALLETS=0xYourWallet
# Production Taffy-style:
#   SETTLEMENT_ADAPTER=robinhood-usdg
#   STORE_ADAPTER=sqlite   # or postgres + DATABASE_URL
#   ADS_TREASURY_ADDRESS=0x…
#   ADMIN_SECRET=…   # ≥16 chars
# Brand:
#   NETWORK_NAME=My Ads
#   BRAND_WORDMARK=MY×ADS
#   SESSION_COOKIE_NAME=my_ads_session

npm install --legacy-peer-deps
npm run dev   # API :3040 + web :5174

For a publisher or app that only needs the SDK:

npm install @taffy/ads

The package ships compiled ESM, declarations, public subpath exports, and an MIT license. Install better-sqlite3 or pg only when using those optional store adapters.

Stores: sqlite (default, one API writer + payments) → postgres (multi-instance ledger, auth, rate limits, bid walls, and webhook outbox). See ARCHITECTURE.md and OPERATIONS.md.

See docs/WHITE_LABEL.md and docs/ARCHITECTURE.md.

Docs

Doc	Contents
docs/ARCHITECTURE.md	Kernel boundaries, adapters
docs/WHITE_LABEL.md	Run under your brand
docs/ENV.md	Full environment variable reference
docs/AGENT.md	Agent integration, discovery, auth
docs/X402.md	HTTP 402 payment challenges + settlement
docs/TERMS.md / PRIVACY / AUP	Legal (operator must customize)
docs/HOW_IT_WORKS.md	Serve, impressions, clicks, eligibility
docs/PRICING.md	CPM / CPC formulas, floors
docs/BID_WALLS.md	Reusable bid-wall API, payments, and embed
docs/SECURITY.md	Threat model, production checklist
docs/DEPLOY.md	Hosting, backups
docs/OPERATIONS.md	Release, backup/restore, webhook, and incident runbook
/llms.txt	GEO / AI crawler brief

Monorepo

packages/ads     # @taffy/ads — core, hono, store, react, agent
apps/api         # HTTP host (auth, settlement adapters, admin)
apps/web         # Marketing + advertiser + admin
apps/mcp         # Agent CLI tools
config/          # publishers.json (showcase catalog)

Quick start (Taffy reference)

cp .env.example .env   # edit ADMIN_WALLETS, treasury, VITE_REOWN_PROJECT_ID
npm install --legacy-peer-deps
npm run dev            # API :3040 + web :5174 (shared root .env)

Environment: every variable is listed in docs/ENV.md and .env.example.

URL	What
http://127.0.0.1:5174	Site + console
http://127.0.0.1:3040/api/health	API health
http://127.0.0.1:3040/api/ads/v1/agent	Agent capability JSON
http://127.0.0.1:3040/api/ads/v1/bid-walls	Reusable bid-wall API
http://127.0.0.1:3040/api/openapi.json	OpenAPI 3.1
http://127.0.0.1:5174/llms.txt	GEO / LLM brief

In one minute

1. Serve — publisher calls GET /api/ads/v1/serve?appId=&placement= → creative + impression. CPM campaigns pay bid/1000 per serve.
2. Click — UI POST /api/ads/v1/click with creativeId → log click, open href. CPC campaigns pay full bid per click.
3. House ads cost $0. Paid ads spend advertiser balance (topped up on-chain).

Details: docs/HOW_IT_WORKS.md · docs/PRICING.md.

Publisher embed

import { AdSlot } from '@taffy/ads/react'

<AdSlot
  appId="sheesh"
  placement="sidebar"
  baseUrl="https://ads.example.com/api/ads"
  variant="strip"
/>

1. Register appId in ADS_PUBLISHER_APP_IDS
2. Allow origin in CORS_ORIGINS
3. Point baseUrl / VITE_ADS_BASE_URL at this API

Waitlist

Public form on the homepage (#waitlist): Buy ads (purchaser) or Publish ads (publisher). Stored in DATA_DIR/waitlist.json; visible under Admin.

npm

Package: @taffy/ads.