Spec Proposal: Discovery-Time Access & Monetization Signaling

[MartinRistov]

Following up on this #20 monetization signaling in ARD entries with a fleshed-out design so we have something concrete to react to. Scoped to access/monetization only — auth-feasibility signaling is kept out (see "Out of scope" below), per @zeroasterisk & @darrelmiller's point that auth hints at the discovery layer are a separate discussion.

Design principle: ARD signals, it doesn't transact

accessModel communicates a coarse access signal; registries and clients judge and act — same shape as the trust model, consistent with §3.6 Separation of Concerns. Authoritative commercial terms live behind pricingUrl / in the resource's native card. Any structured price echoed into the entry is an optional, non-authoritative cache for filtering — ARD does not become a billing spec. §4.5 Description Vocabulary already names pricing as a legitimate filter dimension; this just gives it a small, named, interoperable shape.

Proposed field (optional, on the Catalog Entry §4.2)

Only tier is required when the object is present; everything else is optional (a publisher can say as little as {"tier": "free"}).

"accessModel": {
  "tier": "paid",
  "paymentProtocol": "x402",
  "pricingUrl": "https://acme.com/pricing",
  "price": { "amount": 0.01, "currency": "USD", "unit": "per_call" },
  "freeTier": { "unit": "per_month", "quantity": 100 },
  "mediation": { "marketplace": "example-marketplace", "productRef": "prod-xxxxx" }
}

Field	Req.	Description
tier	yes*	free | freemium | subscription | paid | negotiated. Primary filterable/rankable signal.
paymentProtocol	no	Self-serve payment mechanism, e.g. x402, marketplace.
pricingUrl	no	Authoritative terms (source of truth).
price	no	Non-authoritative echo for filtering: { amount, currency, unit }.
price.unit	no	per_call | per_token | per_seat | per_month | flat.
freeTier	no	Included allowance, e.g. { unit, quantity }.
mediation	no	Vendor-neutral pointer that the resource is transactable via a marketplace; marketplace + opaque productRef (ARD does not interpret them).

* required only when the object is present; the object is optional on the entry.

tier: negotiated deliberately separates self-serve-payable from needs-a-deal (price not public / private offer). price.unit, negotiated, and mediation are intentionally abstract so any marketplace or SaaS vendor can instantiate them without their model being baked into the spec.

How a client uses it

Filter (prefer free/freemium; exclude negotiated for an autonomous run that can't complete a sales motion) or rank (bias toward affordable/covered) before selection — avoiding the select-then-402 dead end. Suggest adding an optional accessTier to the Appendix A structured filters.

Why entry (not card)

The coarse gate must be filterable without fetching the artifact, so it belongs in the entry the registry indexes. The optional richer terms stay in the same object (framed as a non-authoritative echo of pricingUrl/the native card) to avoid a second lookup. This matches the pattern in ai-catalog issue #63 and ai-catalog issue #65 — optional structured objects on the entry, justified by a discovery-time decision.

Out of scope

• Auth-feasibility (authHint) — supported auth schemes / DCR / on-behalf-of at discovery time. Separate concern; worth its own issue. (Note Spec Proposal: Dependencies manifest #63 already carries identityType: "OBO" on dependencies — an existing discovery-time auth-feasibility signal.)
• Entitlement / "covered" state — whether this buyer is already covered is buyer-specific and runtime-resolved, which fights the static-manifest model. Deferred as the runtime complement to this discovery-time signal.

Open questions

1. Is 5 the right granularity for tier? Is negotiated distinct enough to keep?
2. Keep price/freeTier in the entry (as non-authoritative echo), or stop at tier+paymentProtocol+pricingUrl and defer structured terms to the card?
3. Add accessTier to Appendix A filters?
4. Naming: accessModel vs. access vs. commercialTerms?

[YE-YI7]

We run a production library of 30 real commercial tools (task apps, design tools, booking/data APIs) with structured pricing/access fields, live behind an ai-catalog-shaped endpoint — so here's how your proposed shape holds up against actual data, keyed to your open questions.

Q1 — tier granularity: 5 is right, and negotiated earns its place. Our distribution: 17 free / 5 freemium / 6 paid-or-subscription / 2 negotiated. Even in a library deliberately biased toward agent-usable tools, negotiated shows up (RESO Web API needs an MLS data agreement; Duffel rates go through a sales motion) — and it's exactly the value an autonomous run must filter out because the agent can't complete the sales loop. Also worth noting: 22/30 being free/freemium means the minimal {"tier":"free"} form already does real filtering work on day one.

Q2 — keep the echo, but split by mutability. Our operational experience: tier is stable for months; amounts churn (price changes, plan reshuffles). We converged on the same rule your design implies — static gate signals inline, authoritative mutable terms behind a URL — and it's held up. If price/freeTier stay in the entry, two small hardenings from drift we've actually hit: an asOf timestamp on the echo, and registries re-stamping one catalog-level generated_at rather than per-field freshness. One gap in the unit enum from real billing pages: we see per_year (annual-only SaaS) and bulk-metered units (per_1M calls/rows) that don't map cleanly onto per_call|per_token|per_seat|per_month|flat — maybe per_year plus an optional quantity multiplier ({ "unit": "per_call", "per": 1000000 }).

Q3 — yes to accessTier in Appendix A filters. The pre-selection gate we run in production is precisely: autonomous run → exclude negotiated; no payment rail available → exclude paid; then rank survivors on cost. Doing that at filter time is what avoids the select-then-402 dead end; it needs to be expressible in the standard filter syntax to be portable.

Q4 — accessModel over commercialTerms. Since the echo is explicitly non-authoritative, "terms" overclaims; accessModel matches what it actually is.

One addition from selection data: for paid tools, freeTier presence/size is the single most decision-relevant field — cheapest-eligible selection lands on free allowances more often than on list prices. Making freeTier first-class (not buried in prose behind pricingUrl) is worth it.

Live data if useful: catalog · example manifest · schema/library. Happy to run any revised shape against the 30 tools and report what breaks.

(Drafted with Claude; reviewed and approved by me.)

[darrelmiller]

I would fully support this as an extension. I fear that if we dig into this topic there will be many open questions and we won't be able to meet our target for v1. I'd like to see this mature as an extension before adding it to the core.

[YE-YI7]

Ahead of tonight's WG discussion of this issue — one-table summary of the field data above, for easy reference:

Finding	Data (30 real commercial tools)
Tier distribution	17 free / 5 freemium / 6 paid-or-subscription / 2 negotiated
negotiated is real	RESO Web API (MLS agreement), Duffel (sales motion) — exactly what an autonomous run must filter out
unit enum gaps	per_year (annual-only SaaS) and bulk-metered units (per_1M calls/rows) don't map onto per_call|per_token|per_seat|per_month|flat
Drift hardening	amounts churn, tiers don't → price echo wants an asOf; registries re-stamp one catalog-level timestamp

We volunteer as a test implementation during the 0.9 freeze window — send any candidate shape and we'll run it against the library and report what breaks, usually same-day. Live conformance-tested endpoint: https://asm-spec.onrender.com/.well-known/ai-catalog.json

(Drafted with Claude; reviewed and approved by me.)

[doteyeso-ops]

Agree with the design principle: ARD signals, it doesn’t transact — and with Darrel’s caution about not blocking v1 on every monetization open question.

One coarse accessModel signal that has been useful in the wild for agent clients (without inventing a settlement protocol in the catalog):

• x402 / http-402 — pay-per-call at the resource
• prepaid-key — human funds once; agent resumes with a join-key (no hot wallet mid-run)
• day-pass — time-boxed burst access

We’ve been running that split on Solana USDC for Outcome APIs (catalog + fund: https://vibes-coded.com/start · meta: GET /api/v1/outcomes/meta). Fine if this stays out of core v1 and lands as an extension table — just offering real-world field values if the WG wants examples beyond “paid / free.”

[YE-YI7]

Following tonight's WG conclusion that this lands as an extension rather than core: worth noting the extension route already has a running example — our conformance-tested catalog serves exactly this data as flat namespaced extension keys (asm:*) today: https://asm-spec.onrender.com/.well-known/ai-catalog.json

When the WG settles the extension namespace/shape for access/monetization, we'll rename our keys to match, and can serve as a live test implementation during the 0.9 freeze window — same-day runs against the 30-tool library, as offered above.

@doteyeso-ops's mechanism values (x402 / prepaid-key / day-pass) compose cleanly with the tier signal: tier answers "can an autonomous run transact at all" (the filter), mechanism answers "over which rail" (the how). Both fit the same extension table without touching core.

(Drafted with Claude; reviewed and approved by me.)

[doteyeso-ops]

@YE-YI7 — solid. Keeping access/monetization as an extension (with your live asm:* catalog as the conformance example) is the right call for the 0.9 freeze.

When the WG locks the namespace, happy to align our coarse signals (x402 / prepaid-key / day-pass) to the same keys for a second live implementation — signal only, no settlement in the catalog.

[YE-YI7]

Thanks @darrelmiller — agreed, and "mature as an extension first" is the right sequencing. Happy to help that concretely rather than just talk: if the WG wants, I can draft a minimal signal-only extension proposal (namespace + the access fields), with our live asm:* catalog as one reference implementation.

@doteyeso-ops — a second aligned implementation is exactly what makes an extension credible. Suggest we don't privately fix the keys, though: better to let the WG bless the namespace so it's neutral, then both implementations conform to that. Two independent live implementations to validate the shape against is the useful thing to hand the group.

(Drafted with Claude; reviewed and approved by me.)

[doteyeso-ops]

Signal-only extension + live conformance catalogs is the right path for ARD.

When agents need a runtime check of monetization/402 shape (not just discovery signals), we exposed a few small pay-per-call probes that return structured JSON:

• payment-required-lint — validate accepts[] / fail reasons / Solana vs Base coverage
• accepts-dual-rail-check — probe a URL for Solana + Base (eip155:8453)
• merchant-smoke — one-shot reachability + lint summary

Catalog: https://vibes-coded.com/api/v1/outcomes/meta
Solana remains accepts[0]; Base ExactEvm is optional. Prepaid resume: https://vibes-coded.com/start

Public cite only — not proposing unpaid core-spec authorship.