Discovery Paths

Overview

An AI agent can enter the RAMP flow through six paths. All paths converge on the same Exchange protocol — the same DiscoverResources, ExecuteTransaction, and ReportUsage RPCs regardless of how discovery happened.

Path	Entry Point	Use Case
A: Proactive Discovery	ramp.json	Agent checks before accessing content
B: Broker-Mediated	Broker	Agent delegates to multi-exchange router
C: Accidental Discovery	403 response	Wandering bot hits protected content
D: RSL-First	rsl.txt	Agent reads terms, then finds Exchange
E: Batch Multi-URL	Broker	Agent needs multiple resources at once
F: Subscription	Exchange	Agent has existing subscription deal

Path A: Proactive Discovery via ramp.json

The preferred path. The agent checks /.well-known/ramp.json before attempting to access content. No 403 needed, no wasted requests.

Standards mapping:

Step	Message	Standard
Check ramp.json	WellKnownManifest (role=ROLE_PUBLISHER)	RAMP (exchange routing)
Discover supply	ResourceQuery / ResourceResponse	RAMP wrapping RAMP Requester
Offers returned	Offer with Package + Pricing	RAMP Pricing + CoMP Package
Content attestations	Offer.attestations	RAMP ResourceAttestation (replaces ResourceAttestation)
Access restrictions	Offer.terms[].restrictions (repeated Restriction)	RAMP mapping of RSL permits/prohibits
Execute transaction	TransactionRequest / TransactionResponse	RAMP (billing_id, signed URL)
Fetch content	Signed URL on CDN	RAMP extension (signed URL delivery)
Report usage	UsageReport	RAMP (mandatory)

Path B: Broker-Mediated Multi-Exchange

The agent delegates to a RAMP Broker, which queries multiple Exchanges in parallel, compares offers, and selects the best deal.

Standards mapping:

Step	Message	Standard
Agent to Broker	DiscoveryRequest with RequestConstraints	RAMP (budget, authorized exchanges)
Broker to Exchanges	ResourceQuery (parallel fanout)	RAMP wrapping RAMP Requester
Offer comparison	Offer.pricing.unit_cost	RAMP unit cost normalization
Content dedup	Offer.identity (canonical_url, content_hash)	RAMP ResourceIdentity extension
Content attestations	Offer.attestations	RAMP v1.0 ResourceAttestation
Broker to Agent	DiscoveryResponse (offer_groups: signed offers per URI)	RAMP — discovery only, no delivery
Execute winning offer	ExecuteTransaction / TransactionResponse (signed URL + cost + billing_id)	RAMP (separate execute step, routed via Offer.exchange)
Usage reporting	UsageReport to the winning Exchange	RAMP

Path C: Accidental Discovery via Edge Function (403)

A wandering bot hits protected content without knowing about RAMP. The edge function on the provider’s CDN blocks it and points to the Exchange.

Standards mapping:

Step	Standard
403 + X-Content-Rules header	RAMP extension (discovery mechanism — not in CoMP or RSL)
Exchange endpoint in header	Points to Exchange listed in ramp.json
All subsequent steps	Same as Path A

The edge function is the “barking dog” — a fallback for bots that did not check ramp.json first.

Path D: Agent Reads RSL Directly

An agent reads rsl.txt to understand terms, then uses ramp.json to find the Exchange for transacting. RSL tells the agent what it costs; RAMP tells it where to pay.

Standards mapping:

Step	Standard
Read rsl.txt	RSL 1.0 — terms declaration
Read ramp.json	RAMP — exchange routing
DiscoverResources	Exchange returns Offers with pricing derived from RSL
Offer.terms[].restrictions	Maps RSL permits/prohibits to RAMP Restriction (kind RESTRICTION_KIND_FUNCTION) on each LicenseTerm

Path E: Batch Multi-URL Acquisition

The agent needs multiple resources in a single request (e.g., RAG grounding across several sources). The Broker sends all URIs in one ResourceQuery to each Exchange, receives OfferGroups, and returns the ranked signed offers per URI in a single DiscoveryResponse. Discovery stops there: the agent selects the best offer per URI and commits the selections itself via batch ExecuteTransaction calls (one per Exchange, routed by Offer.exchange), each returning a TransactionResponse.

Standards mapping:

Step	Message	Standard
Agent sends multi-URI request	DiscoveryRequest with multiple URIs	RAMP
Broker fans out	ResourceQuery with multiple URIs (one query per Exchange)	RAMP wrapping RAMP Requester
Exchange returns grouped offers	ResourceResponse.offer_groups[] with OfferGroup per URI	RAMP OfferGroup extension
Broker returns offers to Agent	DiscoveryResponse.offer_groups[] (signed offers per URI)	RAMP — discovery only, no delivery
Empty OfferGroup diagnostic	OfferGroup.absence_reason (OfferAbsenceReason enum)	RAMP v1.0 — per-URI diagnostic when no offers available
Rate limit signaling	ResourceResponse.rate_limit (RateLimitInfo)	RAMP v1.0 — proactive throttling for Broker fanout
Batch transaction	TransactionRequest.items[] with TransactionItem per offer	RAMP batch extension
Per-item results	TransactionResponse.items[] with TransactionResultItem per offer	RAMP batch extension
Usage reporting	One UsageReport per resource (not per batch)	RAMP

OfferAbsenceReason (v1.0)

When an OfferGroup has no offers, the absence_reason field explains why. This enables agents and Brokers to distinguish “content not in catalog” from “no offers matched your request” without trial-and-error transactions. The defined reasons:

Value	Description
NOT_IN_CATALOG	Resource URI is not in this Exchange's catalog.
CONTENT_BLOCKED	Resource exists but the provider has opted out of AI access for it (the provider's consent/opt-out signal blocks licensing).
RESTRICTION_FILTERED	Resource exists but its offers were pre-filtered out for one or more restriction axes the requester stated (a convenience filter matched to the query, not an enforcement verdict — see Restriction). The filtered axes are listed in OfferGroup.restriction_filters, in the same RestrictionKind vocabulary the terms use. The agent MAY still be eligible.
TEMPORARILY_UNAVAILABLE	Resource is temporarily unavailable (e.g., provider feed refresh in progress).
NOT_AUTHORIZED	Exchange is not authorized by the provider to sell this resource.
SCOPE_INSUFFICIENT	Requester's scopes/subscription do not cover this resource. Applies wherever access is gated by subscription or scope entitlements (not only enterprise deployments): the resource exists but the requester's delegation token or subscription does not grant it. The Exchange returns this so the requester learns the resource is reachable under the right subscription/scope. (Where existence itself must stay hidden, the Exchange MAY omit it silently instead.)
UNKNOWN_CRITICAL_EXTENSION	Consumer encountered ext_critical keys it does not recognize. The unrecognized keys SHOULD be listed in the OfferGroup's ext field under "unrecognized_critical_extensions" for diagnostic purposes.
BUDGET_EXCEEDED	Offers exist, but none fit within the requester's budget (e.g. every offer's price exceeds RequestConstraints.period_budget). Returned by Resolve as a successful "no result" answer when a budget/price ceiling filtered out every otherwise-licensable offer.

RESTRICTION_FILTERED reports an optional convenience pre-filter matched to the restriction attributes the requester volunteered (function / geography / user-type); the filtered axes are listed in OfferGroup.restriction_filters using the same RestrictionKind vocabulary the terms carry — not an enforcement verdict: restrictions ride on the offer and the agent self-selects (see Licensing terms).

RateLimitInfo (v1.0)

The ResourceResponse carries an optional rate_limit field with the caller’s current rate limit status: limit, remaining, reset_at, and window. This is particularly important for Broker fanout — when a Broker sends batch queries to multiple Exchanges, mid-batch rate limiting can cause partial results if not signaled early. Modeled after IETF RateLimit header fields.

DiscoveryMethod (v1.0)

Each OfferGroup carries a discovery_method field indicating how the offers were sourced. The discovery methods:

Value	Name	Description
0	DISCOVERY_METHOD_UNSPECIFIED	unset — output/optional; zero is a valid not-applicable/unset state
1	DISCOVERY_METHOD_EXCHANGE	URI was requested by the agent directly or found via Exchange query.
2	DISCOVERY_METHOD_SEARCH	URI was discovered via a search engine (e.g., Exa, Tavily, Brave Search). The Broker searched on the agent's behalf, then routed through Exchange.
3	DISCOVERY_METHOD_RECOMMENDATION	URI was recommended by a resource recommendation service.
4	DISCOVERY_METHOD_SYNDICATION	URI was found via resource syndication tracking (e.g., same article on another domain).

This allows agents and Brokers to understand the provenance of each offer group and apply method-specific ranking or filtering logic.

Batch transactions are non-atomic — individual items can fail independently. If one URI’s offer fails authorization, the others proceed.

Path F: Subscription-Based Access

The agent has an existing subscription deal with an Exchange. When querying supply, the Exchange includes subscription offers with zero marginal cost. The transaction skips per-request billing but still issues a signed URL and creates a usage reporting obligation.

Key points:

• Subscription detection at query time: The Exchange checks the requester’s subscription status and includes offers with subscription_id and rate=0.
• Reporting is still mandatory: Subscription offers carry ReportingObligation.required = true. Providers need consumption data for subscription renewals and content strategy.
• Quota enforcement: The Exchange checks remaining quota before authorizing subscription transactions. If the subscription’s token quota is exhausted, the subscription offer is not included.
• Broker preference: The Broker’s selection engine ranks subscription offers above all per-request offers (zero marginal cost). When preferred_exchanges is set and the agent has subscriptions there, those offers get top priority.
• Financial attribution: The subscription_unit_value field carries the per-unit cost even though cost.amount is 0, enabling prepaid drawdown accounting.

Next Steps

• Transaction Flow — detailed RPC definitions and wire formats
• Authentication — Ed25519 signature chain across all paths
• Scenario Walkthrough — a complete end-to-end scenario demonstrating multiple paths