Spec proposal: access and monetization signaling in ARD entries

[zeroasterisk]

Problem

Resources discovered via ARD may require payment or have access restrictions. Currently, a client discovers and selects a resource, then fails with 402/permission errors at invocation time. There is no way to signal access requirements at discovery time.

Proposal

Add optional access/monetization metadata to ARD catalog entries so clients can filter or rank based on access feasibility before attempting invocation.

Originally proposed by: @brochacho94 (Martin, AWS) — Discord #before-launch, Jun 14

Discussion

• @rvguha_05463 (Jun 15): "Martin, I agree with you."
• @darrelmiller (Jun 15): Agreed commercial terms would be useful but was less convinced about auth hints at the discovery layer.
• @zeroasterisk (Jun 15): "I really like this recommendation, but I want to backlog this."

Status

Deferred from v0.9. Needs design discussion on:

• What fields to add (free/paid/freemium, pricing tier, access requirements)
• Whether this belongs in the entry or in the agent card
• Interaction with auth signaling (Spec proposal: access and monetization signaling in ARD entries #20)

cc: @brochacho94 @darrelmiller @rvguha

[aaitor]

Building on #20 — a concrete, deployed take on how to signal payment on an ARD entry, offered
as input to this thread rather than a competing proposal.

Where this fits

#20 asks how access and monetization should be signaled in ARD entries, and raises the open
question of whether payment belongs on the entry or inside the artifact card. This is a
worked answer to the entry-level half: a small, namespaced payment vocabulary carried as
JSON-LD extension terms (§3.4), so a calling agent can read price, currency, settlement
network, and the payment protocol before it decides to invoke, and a registry can index
those as filter dimensions (§5.3.1). It is deployed in production today (details at the end),
which is the main reason to put it in front of this thread — it's been through contact with
real x402 traffic.

It is deliberately additive and non-normative: it uses the extension mechanism ARD already
defines, needs no change to the entry model or conformance, and any entry that doesn't carry
it is unaffected.

Why a shared namespace, when §3.4 already allows any namespace

§3.4 makes a payment vocabulary possible — Nevermined already uses one under a private
prefix. What §3.4 does not do is make publishers converge on the same one, and cross-publisher
discovery value is a network effect: a query like "flight agents that accept x402 under $0.05
USDC" only works if every payable publisher's price resolves to the same IRI (prefixes are
local and irrelevant per §5.3.1; the IRI is what matters). That convergence is exactly why ARD
named a2a-agent-card+json / mcp-server-card+json instead of leaving them per-vendor. The
ask here is the same: nominate one payment namespace as the convergence point, so the terms
below mean the same thing across publishers who never coordinated.

This should coordinate with the adjacent payment efforts rather than pre-empt them — the x402
maintainers, and the A2A / AP2 (Agent Payments Protocol) work — so pay:protocol is
protocol-neutral: "ap2" is as first-class as "x402".

Proposed core vocabulary

A deliberately small core — four terms plus one facet. Everything a discovering agent needs to
evaluate cost and route, and nothing that leaks a particular vendor's plan/credit model.

Term	Type	Description
pay:protocol	string[]	Payment protocol(s) the resource speaks: "x402", "mpp", "ap2". The primary facet — "agents that accept x402."
pay:price	decimal	Headline price of the default offer, as a decimal in pay:currency units (0.01). Advisory (see below); full precision, no truncation.
pay:currency	string	Currency of pay:price: token symbol ("USDC") or ISO-4217 ("USD"). Display/filter only — not sufficient to settle (see pay:accepts).
pay:accepts	JSON (opaque)	Protocol-specific, advisory pre-construct hints — see below. Opaque to the graph (@type: @json); its sub-fields are not filter dimensions.
pay:network	string	(facet) Settlement network: CAIP-2 chain id for on-chain ("eip155:8453") or processor id off-chain ("stripe"). Useful as a filter; also present inside pay:accepts.

Queryable filter dimensions are the top-level scalars (pay:protocol, pay:currency,
pay:network, and pay:price for equality/range). pay:accepts is intentionally opaque.

pay:accepts — advisory, x402-scoped, not authoritative

For x402, pay:accepts mirrors the structure of the 402 accepts[] so an agent can
pre-construct and estimate a payment before making the call — but it is a hint, not a
mandate. Each block SHOULD carry the fields a wallet actually needs, e.g. for the x402 exact
EVM scheme: scheme, network (CAIP-2), asset (the ERC-20 contract address — a symbol
alone is ambiguous across chains), payTo, maxAmountRequired, resource, maxTimeoutSeconds,
and extra (the EIP-712 token domain, name/version). Absent any of these a client cannot
sign, so a partial block is an estimate only.

Normative-intent note for the thread: the live 402 is authoritative; pay:accepts
and pay:price are advisory. A client MUST verify the 402's payTo / asset / amount
against discovery and its own spend limit, and MUST sign against the 402 — never blind-sign a
registry-supplied authorization. This keeps discovery a routing aid and preserves x402's
server-issued binding (nonce, resource, validity window). "Pre-construct/estimate," not
"pre-sign."

MPP and other rails are covered at the filter level only (pay:protocol, pay:price,
pay:currency, pay:network). MPP's 402 is a header challenge with a different shape (no
accepts[] array, bare-name network, splits), so it does not share x402's accepts block;
a per-protocol pay:accepts shape for MPP is out of scope here and can follow if there's pull.

schema.org

pay: covers what schema.org lacks for agent payment — protocol, settlement network, the
pre-construct block. For the headline price, publishers MAY additionally attach a schema.org
offer node (registries already facet on it):

"schema:offers": { "@type": "schema:Offer", "schema:price": "0.01", "schema:priceCurrency": "USDC", "schema:category": "x402" }

(Note: schema:offers → a node typed schema:Offer — schema:Offer is a class, not a
predicate.) pay: and schema.org coexist; neither is required.

@context

Coercions are attached to the pay:-prefixed term names entries actually use, pay:accepts
is @json (genuinely opaque, like ARD's own metadata/data/trustManifest), pay:price is
xsd:decimal (so range filters order numerically), and the namespace IRI is unversioned
— mirroring ARD's own …/ns# (only the context document is versioned). A versioned namespace
IRI would change every term's IRI on a bump and silently break the cross-publisher filters this
whole thing exists for.

{
  "@context": {
    "@version": 1.1,
    "pay": "https://agenticresourcediscovery.org/ns/payment#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "schema": "https://schema.org/",
    "pay:protocol": { "@id": "pay:protocol", "@container": "@set" },
    "pay:price":    { "@id": "pay:price", "@type": "xsd:decimal" },
    "pay:currency": { "@id": "pay:currency" },
    "pay:network":  { "@id": "pay:network" },
    "pay:accepts":  { "@id": "pay:accepts", "@type": "@json" }
  }
}

Example entry

An A2A agent card annotated with payability. Core ARD terms unchanged; pay: + schema: are
the added dimensions.

{
  "@context": {
    "pay": "https://agenticresourcediscovery.org/ns/payment#",
    "schema": "https://schema.org/"
  },
  "identifier": "urn:air:acme.com:agent:market-analyst",
  "displayName": "Market Analyst",
  "type": "application/a2a-agent-card+json",
  "url": "https://api.acme.com/agents/market-analyst.json",
  "representativeQueries": [
    "analyze this quarter's revenue trend",
    "summarize the earnings call sentiment"
  ],
  "pay:protocol": ["x402"],
  "pay:price": "0.01",
  "pay:currency": "USDC",
  "pay:network": "eip155:8453",
  "pay:accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xReceiver…",
      "maxAmountRequired": "10000",
      "resource": "https://api.acme.com/agents/market-analyst",
      "maxTimeoutSeconds": 120,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "schema:offers": { "@type": "schema:Offer", "schema:price": "0.01", "schema:priceCurrency": "USDC", "schema:category": "x402" }
}

Example query

Cross-publisher filtering, resolved by IRI regardless of each publisher's prefix (§5.3.1):

{
  "query": {
    "@context": { "pay": "https://agenticresourcediscovery.org/ns/payment#" },
    "text": "book a flight",
    "filter": {
      "type": ["application/a2a-agent-card+json"],
      "pay:protocol": ["x402"],
      "pay:currency": ["USDC"]
    }
  }
}

Conformance impact

None to the core. Recognized-namespace extension terms (§3.4) validate today against ArdEntry
(additionalProperties: true); entries without them are unaffected. If useful, the conformance
tool could later add an advisory check (warning, not error) that a pay:-bearing entry
resolves a pay:protocol — mirroring how representativeQueries is handled (§D.2). Nevermined
is happy to contribute that tooling PR.

Deployed instance

Nevermined publishes a live, conformance-passing /.well-known/ard.json that already carries
pay-per-call terms in this general structure, today, under a private namespace (nvm:) with
a schema.org price mirror — see
nevermined-io/nvm-monorepo#3079. That
it works under a private prefix is precisely the point of #20: it's usable in isolation but
fragmented — no other publisher's price resolves to the same IRI. We'd migrate to whatever
shared namespace this thread converges on. (Internally the block carries plan/credit specifics;
those stay a Nevermined extension on top of the shared core, not part of this proposal.)

What we're asking of this thread

1. Agreement that entry-level payment signaling is in scope for Spec proposal: access and monetization signaling in ARD entries #20, and on a small core term set.
2. A single convergence namespace for payment terms — hosted by the project, or by us as a
   neutral IRI listed the way §5.3.1 lists okf:; the ask is one canonical IRI, not who serves
   it. (We're not asking to own it — a shared IRI everyone binds is the whole value.)
3. A curated payment example merged under conformance/examples/ (Nevermined will contribute a
   small conformant catalog) — the cheapest, most durable way to make the shape concrete.

Media-type registration for payment-native artifacts (application/x402+json and MPP) is a
separate, later question — deferred until this entry-level vocabulary settles, and only sensible
jointly with the protocol owners.

---

The curated conformance example referenced above is up now as #86 (conformance/examples/nevermined/) — it passes the official conformance tool with 0 errors, and validates regardless of the vocabulary discussion since these are additive extension terms (§3.4).