logicsrc/docs/agentad-marketplace.md

AgentAd Marketplace (PRD)

Status: Draft Owner: Profullstack / LogicSRC Milestone: AgentBBS M5 — AgentAd marketplace Standard: built on the AgentAd primitive family in @logicsrc/schemas

AgentAd (see docs/agentad.md) already defines the contracts: agentad.ad, agentad.placement, agentad.ad_request, agentad.ad_response, agentad.impression, agentad.click, and agentad.campaign. This PRD defines the marketplace — the two-sided product layer that lets advertisers buy inventory and publishers sell it, with matching, serving, metering, and settlement in between. cl1s.tech is the reference hosted network; AgentBBS is the reference publisher surface (SSH/TUI over the CLI/TUI/agent surfaces).

1. Summary

The AgentAd Marketplace is a disclosed, agent-native advertising exchange for command-line tools and AI agents. Advertisers fund campaigns of ads; publishers register placements in their CLI/TUI/agent surfaces; the exchange matches, serves, meters, and settles. Every unit is disclosed as sponsored and carries a machine_readable payload so an agent can reason about the offer rather than scrape rendered text.

The marketplace is the product wrapper around the AgentAd contracts: it adds identity-scoped accounts, listings/discovery, an auction, budget pacing, verified metering, and CoinPay-backed billing and payouts. LogicSRC owns the schemas and the exchange contracts; hosted networks (cl1s.tech first) run the exchange; surfaces like AgentBBS consume it.

2. Goals & non-goals

Goals

• A working two-sided exchange: advertiser buy-side + publisher sell-side over the existing AgentAd schemas, with no schema forks — extend via the reference network, not the standard.
• Disclosure is non-negotiable. Every served unit sets disclosure.sponsored: true and a visible label; agent responses expose sponsored: true explicitly. Undisclosed serving is a protocol violation and a fillable-inventory ban.
• DID-scoped accounts. Advertisers and publishers are identified by DID (via CoinPay/ANS); campaigns and placements bind to advertiser_did / publisher_did.
• Verified metering. Impressions and clicks are only billable when confirmed with the signed impression_token from the ad_response.
• CoinPay settlement. Budgets are escrowed; publisher payouts and network fees settle through CoinPay; reputation events flow from spend and delivery quality.
• AgentBBS integration. AgentBBS registers placements (menu banners, TUI panels, agent chat) and earns payouts; advertisers can target the BBS surface.

Non-goals (v1)

• Real-time bidding across external third-party exchanges (single-exchange auction only).
• Rich media / image ads beyond banner/ansi_art and media.icon.
• Human web-display advertising — this is CLI/TUI/agent/CI surfaces only.
• Cross-network ad syndication (out of scope until the contracts stabilize on one network).

3. Personas

Persona	Wants
Advertiser (e.g. Railway, a tool vendor)	Reach agents/CLIs with a disclosed, budgeted campaign; pay per CPM/CPC/CPA/flat; see delivery + spend.
Publisher (AgentBBS, a CLI, an agent)	Register placements, control formats/frequency/category blocks, earn payouts, keep UX clean.
Agent consumer	Receive a structured sponsored: true offer it can act on, or ignore, without being deceived.
Human consumer	See a clearly [Sponsored] unit in the terminal, never mistaken for organic output.
Network operator (cl1s.tech)	Run the auction, meter honestly, take a transparent fee, keep advertisers and publishers trusting the exchange.

4. Marketplace model

Two sides bridged by the exchange:

Advertiser ──creates──▶ Campaign ──contains──▶ Ads
     │                     │ budget/schedule/targeting        (agentad.campaign / agentad.ad)
     │ escrow (CoinPay)    │
     ▼                     ▼
              ┌────────────── Exchange ──────────────┐
              │  match → auction → pace → serve      │
              │  meter (impression/click) → settle   │
              └──────────────────────────────────────┘
     ▲                     ▲
     │ payout (CoinPay)    │
Publisher ──registers──▶ Placement ──requests fill──▶ ad_request → ad_response
                           surface/formats/caps       (agentad.placement / ad_request / ad_response)

4.1 Buy side

• Advertiser account keyed by advertiser_did; onboarding funds a balance via CoinPay.
• Campaign (agentad.campaign): budget.total, budget.daily_cap, currency, schedule, status (draft|active|paused|completed), ad_ids.
• Ad (agentad.ad): format, title, body, url, cta, mandatory disclosure, optional machine_readable, targeting (surfaces/keywords/tools/languages), pricing (cpm|cpc|cpa|flat + bid), media, expires_at.
• Activating a campaign escrows budget.total (or a top-up tranche) in CoinPay so serving can never outrun funds.

4.2 Sell side

• Publisher account keyed by publisher_did.
• Placement (agentad.placement): surface (cli|tui|agent|ci), accepted_formats, dimensions, context_tags, frequency_cap, allow_categories / block_categories.
• Publisher configures a revenue share and payout wallet; blocks disallowed categories.

4.3 The exchange (new surface, on top of the standard)

1. Match — candidate ads whose targeting fits the placement surface, context_tags, accepted_formats, and pass its category blocks + frequency_cap.
2. Auction — rank eligible candidates by effective value (pricing.bid normalized across cpm/cpc/cpa, weighted by advertiser reputation and predicted engagement). Second-price clearing in v1.
3. Pace — enforce budget.daily_cap and remaining escrow before selecting a winner.
4. Serve — return agentad.ad_response with the winning ad, a rendered string in the requested format, and a signed impression_token. On no candidate: no_fill_reason (no_inventory | frequency_capped | blocked_category | invalid_request).
5. Meter — bill on the confirmed agentad.impression (CPM) or agentad.click (CPC), each validated against the signed token. CPA conversions post back via a click token.
6. Settle — debit advertiser escrow, credit publisher (minus network fee) through CoinPay, emit reputation + audit events.

5. Functional requirements

Advertiser

• Create/update/pause/complete campaigns and ads; all writes validate against the AgentAd schemas.
• Fund balance and escrow campaign budget via CoinPay; view remaining budget and daily pacing.
• Targeting by surface, keywords, tools (e.g. claude-code, gh), languages, plus exclude_keywords.
• Reporting: impressions, clicks, CTR, spend, CPA, by campaign/ad/surface/day.

Publisher

• Register/update/retire placements; set accepted formats, dimensions, frequency caps, category allow/block lists.
• Request fills (ad_request → ad_response); render per surface ([Sponsored] header for humans, structured sponsored: true view for agents).
• Confirm impressions/clicks with the returned tokens; view earnings and request payouts.

Exchange / operator

• Matching + second-price auction + budget pacing + frequency capping.
• Token minting/verification for impressions and clicks (anti-fraud: unforgeable, single-use, bound to request_id + placement).
• CoinPay integration for escrow, payout, and network fee; full audit log; reputation events.
• No-fill accounting and reason codes; category policy enforcement.

Consumer-facing rendering (delivery contract)

• consumer: human → rendered string with a visible [Sponsored] / label header.
• consumer: agent → structured object with explicit sponsored: true, advertiser, title, url, and the machine_readable data payload.

6. AgentBBS integration (reference publisher)

AgentBBS is the first-class publisher surface for M5:

• Placements: a menu/lounge banner (surface: tui, banner/ansi), a TUI side panel, and agent-chat inserts (surface: agent, json). Each registered as an agentad.placement under the BBS publisher_did.
• Frequency + taste: conservative frequency_cap (e.g. one banner per session) and category blocks so the retro BBS UX stays clean; disclosure label rendered in lipgloss styling.
• Payouts: BBS ad revenue settles to the operator wallet via CoinPay; can subsidize free pods / lifetime tiers.
• Advertiser side: BBS members with a advertiser_did can run campaigns targeting the CLI/agent ecosystem from inside the BBS.
• Delivery split (mirrors the ascii-live pattern): the Go side (AgentBBS) renders and confirms tokens; the TS side (@logicsrc/* + the hosted network) owns campaigns, the auction, metering, and settlement.

7. Architecture & where it lives

Component	Where	Language
AgentAd schemas + validators	packages/schemas, packages/validators (exists)	JSON Schema / TS
Marketplace SDK (campaign/placement/serve/meter clients)	packages/sdk (extend)	TS
Exchange service (auction, pacing, metering, settlement)	cl1s.tech reference network	TS/Hono
CoinPay escrow/payout hooks	plugins/coinpay (exists)	TS
Publisher plugin surface	plugins/agentbbs (PluginDefinition: routes + events)	TS
AgentBBS render/confirm	profullstack/agentbbs (Go: wish/bubbletea/lipgloss)	Go

Schemas stay canonical under https://schemas.logicsrc.com/. The marketplace adds services and account/listing/auction/billing state, not new wire contracts — anything new (accounts, ledger, auction records) is reference-network internal until proven and promoted to the standard.

8. Data & settlement

• Identity: advertiser_did / publisher_did via CoinPay DID + ANS naming.
• Money: budgets escrowed in CoinPay on campaign activation; per-event debits on confirmed impressions/clicks; publisher payout = revenue − network fee; refunds of unspent escrow on campaign completion.
• Reputation: delivery quality (fill rate, valid-click ratio) and honored payments emit reputation events for both sides.
• Audit: every serve/meter/settle action is logged; disclosure compliance is auditable.

9. Trust, safety & disclosure

• Disclosure enforced at serve time — the exchange refuses to emit an ad_response whose ad lacks disclosure.sponsored: true.
• Publisher category blocks and advertiser exclude_keywords honored in matching.
• Anti-fraud: single-use signed tokens bound to request + placement; rate limits; anomaly flags on click/impression ratios feed reputation.
• Content policy: advertiser onboarding + campaign review; category taxonomy shared with publisher block lists.

10. Metrics

• Liquidity: fill rate, no-fill reasons distribution.
• Marketplace health: active advertisers/publishers, escrowed budget, GMV, network-fee revenue.
• Delivery quality: CTR, valid-impression/valid-click ratio, disclosure-compliance rate (target 100%).
• AgentBBS: ad revenue per active session, opt-out / complaint rate.

11. Milestones

Phase	Deliverable
M5.0 — Contracts & SDK	Marketplace SDK over existing AgentAd schemas; account/campaign/placement CRUD; validators wired.
M5.1 — Serve & meter	ad_request → ad_response with matching, frequency_cap, signed impression/click tokens; no-fill reasons.
M5.2 — Auction & pacing	Second-price auction, budget pacing against escrow + daily_cap, reputation-weighted ranking.
M5.3 — CoinPay settlement	Escrow on activation, per-event billing, publisher payouts, network fee, refunds, audit + reputation events.
M5.4 — AgentBBS publisher	BBS placements (banner/panel/agent-chat) rendering + token confirmation; operator payouts.
M5.5 — Advertiser & publisher consoles	Reporting/dashboards (CLI + web) for both sides; hosted on cl1s.tech.

12. Open questions

• Auction clearing: is second-price sufficient, or do we need reserve prices / floor CPMs per surface?
• Currency: native CoinPay token vs. stablecoin denomination for budgets and payouts.
• CPA attribution window and postback trust model across independent CLIs/agents.
• Do publisher category taxonomies live in the standard, or stay reference-network config in v1?
• Minimum reputation / KYC bar for advertisers before a campaign can serve.

References

• AgentAd standard — the primitive family and schemas this marketplace consumes.
• @logicsrc/schemas — agentad-*.schema.json canonical contracts.
• cl1s.tech — reference hosted AgentAd network.
• plugins/coinpay — DID, wallet, escrow, payout, reputation.
• AgentBBS docs/ascii-live.md — the Go-surface / TS-plugin split pattern this PRD follows.