Introducing Agent Governance Discovery (AGD): Machine-Readable Policy Discovery for the Agentic Web

1Shot API operates several permissionless APIs in the Web3 and AI-agent ecosystem, including the 1Shot Public Relayer, a gas abstraction service built around ERC-7710 and ERC-7715 smart wallet delegations. These services are intentionally non-custodial. Users interact through wallets, SDKs, MCP servers, and autonomous agents. Many never visit a website. Many never read human-oriented documentation.

That creates a problem nobody has solved well: how does an API tell an agent what its governance policies are?

Today we are publishing Agent Governance Discovery (AGD), an open specification for machine-readable governance metadata. AGD defines a standardized way for APIs, relayers, MCP servers, and other autonomous-system endpoints to publish Terms of Service, Acceptable Use Policies, Privacy Policies, compliance information, and operator contact details in a format that software can discover and parse, without assuming a human ever opens a browser.

This post explains why we built it, what problem it solves, and how it works. The full specification, JSON schema, examples, and reference implementations are available now in the public GitHub repository: github.com/1Shot-API/Agent-Governance-Discovery.

One framing point worth stating upfront: AGD is a policy discovery standard, not a policy enforcement mechanism. It does not define how services enforce terms, block abusive clients, or establish legal acceptance. It defines how autonomous software finds governance information in the first place. That distinction matters, and we will return to it throughout this post.

The old model assumes a browser

For decades, the implied interaction path for online services has looked like this:

Human → Browser → Website → Terms of Service page

Governance communication was designed around that path. Terms of Service live on marketing sites. Privacy policies are linked in footers. Acceptable use rules are buried in developer docs. Abuse contacts appear on /contact pages. Legal teams assume that somewhere in the flow, a human saw the policy, or at least that a human could have seen it.

That model still works for many services. It breaks down when the primary consumer of your API is not a human with a browser, but software acting on a human's behalf.

The new model: Human → Agent → API

The interaction path is changing fast:

Human → Agent → API

Consider what this looks like in practice at 1Shot.

A developer configures an AI agent with access to our MCP server. The agent discovers the 1Shot Public Relayer, constructs a delegated transaction through an ERC-7715 permission envelope, and submits it for gas abstraction. The human may have approved a high-level intent, such as "swap these tokens" or "execute this contract call," but never visited 1shotapi.com. They never scrolled through a Terms of Service page. They may not even know which relayer infrastructure executed the transaction.

This is not an edge case. It is increasingly the default path for:

• AI agents invoking tools through MCP servers or direct HTTP APIs
• Smart wallets submitting UserOperations through gas abstraction relayers
• SDKs and libraries wrapping permissionless endpoints without embedding policy URLs
• x402-enabled APIs where payment and access happen programmatically, with no login page or marketing site in the loop
• Autonomous software that selects services, routes requests, and retries across providers without human intervention at each step

These clients share a common property: they are machines looking for machine interfaces. They expect JSON schemas, OpenAPI documents, MCP tool definitions, and .well-known discovery endpoints. They do not expect to scrape HTML footers for legal links.

And yet governance information, the policies that define what a service allows, what it prohibits, who operates it, and how to report abuse, has no standardized machine-readable home.

What we learned operating the 1Shot Public Relayer

The 1Shot Public Relayer sits at an interesting intersection of Web3 infrastructure and agent-driven access patterns.

It is permissionless. Smart wallet holders can delegate execution rights via ERC-7710/7715 and submit transactions for relay without creating an account, without KYC, and without visiting a dashboard. That is a feature. Non-custodial, open access is exactly what many agentic workflows need.

But permissionless does not mean policy-free. Every relayer operator still has Terms of Service. Every API has acceptable use constraints, including rate limits, prohibited transaction types, and abuse reporting channels. Every service has a jurisdiction, an operator identity, and contact paths for legal and security inquiries.

The gap is not that these policies do not exist. The gap is that there is no standard place for an agent to look for them.

When an MCP-connected agent first encounters our relayer endpoint, what should it do?

• Should it search our website for a Terms of Service link? Many agents cannot browse websites reliably.
• Should it look for a custom X-Terms-Of-Service header? That is not a standard, and every API vendor would invent their own header name.
• Should it assume governance metadata is embedded in OpenAPI or MCP tool descriptions? Sometimes, inconsistently, maybe. But there is no shared schema or discovery path.
• Should it simply proceed without policy awareness? That is what happens today, by default.

We observed the same pattern across other services in our ecosystem: payment APIs, RPC providers, MCP servers, x402 endpoints. Each operator solves governance communication ad hoc, if at all. Agents cannot interoperably discover policy metadata across providers. Framework authors cannot build generic "check governance before use" tooling because there is nothing generic to check against.

This is an interoperability problem. And interoperability problems are what open specifications are for.

What exists today, and why it is not enough

Several existing standards solve adjacent problems. None solve this one.

security.txt (RFC 9116) defines a well-known location for security contact information. It is excellent for vulnerability disclosure. It does not cover Terms of Service, acceptable use, privacy policy, or general operator governance metadata.

OAuth Authorization Server Metadata (RFC 8414) and OpenID Connect Discovery define machine-readable metadata for authorization servers, including issuer URLs, JWKS endpoints, and supported scopes. They assume an OAuth/OIDC authentication context. Most permissionless APIs, relayers, and MCP servers are not OAuth authorization servers.

WebFinger (RFC 7033) resolves identities to service links. It is identity-centric, not governance-centric.

robots.txt communicates crawling policy to automated clients. It is a rare example of a machine-readable policy file designed for non-human consumers, but it covers web crawling, not service governance.

OpenAPI and MCP tool metadata can embed arbitrary documentation, including links to policies. But there is no standard field, no standard relation name, and no standard discovery path that works across OpenAPI, MCP, raw HTTP APIs, and Web3 RPC endpoints alike.

The result is a patchwork. Agents that want to be policy-aware must implement bespoke logic for every service they touch. Service operators who want to be policy-transparent must hope agents know where to look.

Introducing Agent Governance Discovery (AGD)

Agent Governance Discovery defines two complementary mechanisms for publishing governance metadata in a standardized, machine-readable format:

1. AGD Core, a .well-known discovery endpoint that returns a JSON governance document
2. AGD Link Relations, standardized HTTP Link header relation types for inline governance references on any API response

Together, these provide both explicit discovery (for onboarding and SDK initialization) and runtime discovery (for agents that encounter an API before they have performed explicit metadata lookup).

AGD is designed for:

• API providers and relayers (like the 1Shot Public Relayer)
• MCP server operators
• x402-enabled payment APIs
• Wallet SDKs and agent frameworks (as consumers)
• Any permissionless or programmatic service where the primary client may never visit a website

AGD is explicitly not designed to:

• Define the legal content of governance documents
• Enforce policy compliance
• Block, rate-limit, or authenticate clients based on policy acknowledgment
• Replace existing legal agreements or consent flows

It solves discovery. What clients and operators do with discovered policy information is outside the scope of the specification.

The draft specifications are published at github.com/1Shot-API/Agent-Governance-Discovery.

AGD Core: the /.well-known/api-governance endpoint

AGD Core follows the established .well-known URI pattern defined in RFC 8615. This is the same pattern used by security.txt, OAuth metadata, and other discovery mechanisms that autonomous clients already know how to find.

Every AGD-compliant service publishes a JSON document at:

/.well-known/api-governance

For the 1Shot Public Relayer, that would be:

https://relayer.1shotapi.com/.well-known/api-governance

A client, whether an agent, an SDK, or an MCP tool runner, performs a single GET request and receives structured governance metadata:

{
  "version": "1.0",

  "operator": {
    "name": "1Shot API, Inc.",
    "website": "https://1shotapi.com"
  },

  "termsOfService": "https://1shotapi.com/terms",
  "acceptableUsePolicy": "https://1shotapi.com/aup",
  "privacyPolicy": "https://1shotapi.com/privacy",
  "compliancePolicy": "https://1shotapi.com/compliance",

  "jurisdiction": "Delaware, USA",

  "contact": {
    "abuse": "abuse@1shotapi.com",
    "legal": "legal@1shotapi.com",
    "security": "security@1shotapi.com"
  }
}

Field design

The schema is intentionally simple:

• version identifies the AGD Core specification version (currently "1.0").
• operator identifies who runs the service, including name and optional website.
• Governance document URLs (termsOfService, acceptableUsePolicy, privacyPolicy, compliancePolicy) are absolute HTTPS URLs pointing to the actual policy documents. At least one must be present.
• jurisdiction is a human-readable string indicating governing law or regulatory context.
• contact provides machine-readable paths for abuse, legal, privacy, and security inquiries.

The document URLs remain human-readable web pages or PDFs. AGD does not attempt to replace legal documents with JSON. It provides a map to them: a single, predictable location where an agent can find all governance references for a service.

Why .well-known?

Autonomous clients already probe .well-known paths. OAuth clients look for /.well-known/openid-configuration. Security researchers look for /.well-known/security.txt. Certificate transparency systems, WebAuthn deployments, and password managers all use the same pattern.

By placing governance metadata at /.well-known/api-governance, AGD piggybacks on discovery behavior that infrastructure already supports. No new DNS records. No custom registration flows. No vendor-specific SDK required to find the endpoint.

Caching and availability

The endpoint returns Content-Type: application/json; charset=utf-8 and should include cache headers (we recommend Cache-Control: public, max-age=3600). Clients can cache governance metadata and refresh periodically.

If the endpoint returns 404, clients should treat that as "no governance metadata published," not as an error that blocks operation. AGD is opt-in for operators and best-effort for clients.

AGD Link Relations: governance metadata on every response

The .well-known endpoint covers explicit discovery. But agents do not always discover services through a deliberate onboarding step. Sometimes the first interaction is an API call that succeeds, or fails.

An agent submits a transaction to a relayer and receives 429 Too Many Requests. A wallet SDK hits an x402 payment endpoint and gets 402 Payment Required. An MCP tool invocation returns 403 Forbidden. In each case, the agent has already encountered the service before it thought to check /.well-known/api-governance.

AGD Link Relations solves this with standardized HTTP Link headers on API responses, following RFC 8288 (Web Linking).

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://1shotapi.com/terms>; rel="terms-of-service"
Link: <https://1shotapi.com/aup>; rel="acceptable-use-policy"
Link: <https://1shotapi.com/privacy>; rel="privacy-policy"
Link: <https://relayer.1shotapi.com/.well-known/api-governance>; rel="api-governance"

{"status": "ok"}

Defined relation types

Optional contact relations (abuse-contact, security-contact, legal-contact) are also defined for cases where inline contact references are useful.

Why Link headers, not custom X- headers?

HTTP Link headers are a defined standard (RFC 8288). Parsers exist in every major HTTP library. CDNs, API gateways, and reverse proxies can inject or pass through Link headers without custom logic. Using standardized relation names instead of proprietary X-Terms-Of-Service headers means agents can write one parser and handle governance metadata from any AGD-compliant service.

No custom headers. No vendor lock-in. Infrastructure-compatible.

Runtime discovery patterns

Link relations enable several useful patterns:

Error responses with policy context. When a relayer returns 429 Too Many Requests, it can include a link to its acceptable use policy so the agent understands why the request was rejected and what the rules are, without requiring a separate discovery request.

API gateway injection. An operator can add governance Link headers at the gateway level, covering all backend services with a single configuration. This is useful for relayer infrastructure where multiple endpoints share common governance.

MCP server initialization. An MCP server can include governance links in server metadata, allowing agent frameworks to discover policies at connection time.

x402 payment flows. Payment-required responses can include governance links, giving agents policy context before authorizing payment.

Complementary, not redundant

AGD Core and Link Relations serve different moments in the client lifecycle:

Implementations should support both. Clients should check Link headers first (they are free with every response), and fall back to the .well-known endpoint when links are not present.

What AGD does not do

We want to be precise about scope, because the governance space is full of proposals that conflate discovery with enforcement.

AGD does not enforce policies. Publishing an acceptable use policy URL does not give a service the ability to automatically block violating clients. Enforcement requires separate systems, including rate limiting, authentication, on-chain permissions, and human review. AGD provides the policy reference. Enforcement is the operator's responsibility through their own infrastructure.

AGD does not define legal acceptance. Discovering a Terms of Service URL is not the same as agreeing to terms. AGD makes no claims about consent, contractual formation, or legal effect. Operators who need evidence of acceptance must implement that through their own legal and technical processes.

AGD does not replace human-readable policies. The JSON discovery document and Link headers point to governance documents. Those documents remain written for humans (and their lawyers). AGD is the index, not the content.

AGD does not require client compliance. Clients are not required to fetch, parse, or act on governance metadata. AGD is opt-in for operators and advisory for clients. An agent that ignores governance metadata can still call the API, the same way a browser user can ignore a Terms of Service link. The difference is that conscientious agents now have a standard place to look.

This is deliberate. A discovery standard that tried to solve enforcement would need to address authentication, identity, jurisdictional variation, and legal validity across every API type in every country. That is a different project. AGD stays focused on giving autonomous software a standard way to find governance information.

How agents should use AGD

For agent framework authors, SDK maintainers, and MCP server consumers, the recommended client workflow is straightforward:

1. On first encounter with a new service origin, fetch /.well-known/api-governance.
2. Parse the JSON response and extract governance document URLs, operator information, and contact details.
3. On every API response, check Link headers for governance relations.
4. Fetch governance documents as needed for the use case. For example, an agent might prepare a user-facing summary before executing a high-value transaction.
5. Cache governance metadata according to HTTP cache headers and refresh periodically.
6. Proceed with the API interaction. AGD metadata informs the agent's behavior but does not gate access unless the agent's own configuration requires it.

An agent framework might implement this as a middleware layer:

Agent receives tool/API endpoint
  → Check Link headers for governance relations
  → If not found, fetch /.well-known/api-governance
  → Store governance metadata in session context
  → Optionally fetch and summarize policy documents for the user
  → Continue with tool invocation

The key insight is that governance discovery becomes a generic, reusable step rather than bespoke per-service logic. An agent that knows AGD can discover policies from the 1Shot Public Relayer, an x402 payment API, and an MCP server using the same code path.

How service operators should implement AGD

For API providers, relayer operators, and MCP server maintainers:

1. Prepare your governance document, a JSON file matching the AGD Core schema with your operator info, policy URLs, jurisdiction, and contacts.
2. Serve it at /.well-known/api-governance on your API origin.
3. Add Link headers to API responses with the defined relation types.
4. Validate your document against the published JSON schema.

We are publishing reference implementations for Express.js middleware, nginx, and Cloudflare Workers to make adoption straightforward. For most deployments, this is a static JSON file and a handful of HTTP headers, not a new microservice.

For the 1Shot Public Relayer specifically, we plan to implement AGD across our relayer endpoints, MCP servers, and API surfaces as part of our ongoing rollout. Other services in our ecosystem will follow.

Relationship to the broader ecosystem

AGD is designed to complement, not compete with, existing standards:

• OpenAPI describes API capabilities. AGD describes API governance. An OpenAPI document might link to the AGD endpoint; AGD does not replace OpenAPI.
• MCP defines tool interfaces for agents. AGD defines governance metadata for the services those tools call. MCP server metadata is a natural place to include AGD Link relations.
• x402 defines payment-required HTTP responses. AGD Link headers can accompany x402 responses, giving agents policy context alongside payment requirements.
• ERC-7710/7715 define on-chain delegation permissions. AGD operates at the HTTP/API layer. It tells agents about off-chain governance policies that complement on-chain permission envelopes.

We see AGD as infrastructure-layer metadata, as fundamental for agent-era APIs as robots.txt became for web crawlers, or as OAuth discovery became for authorization servers.

What we are publishing today

Phase 1 of the AGD project is available now in the Agent Governance Discovery repository:

• AGD Core v1.0 (Draft), the .well-known/api-governance specification
• AGD Link Relations v1.0 (Draft), standardized HTTP Link relation types
• JSON Schema, for validating governance discovery documents
• Examples, including sample documents, HTTP header scenarios, and test cases
• Reference implementations, including Express middleware, nginx config, and a Cloudflare Worker

Each specification is versioned independently. The project is MIT-licensed. We welcome feedback, implementations, and adoption from other API providers, agent frameworks, MCP server operators, and infrastructure teams facing the same discovery problem. Open an issue or pull request on GitHub.

What comes next

Our roadmap has five phases:

1. Publish draft specifications (done today)
2. Implement internally across 1Shot API services, the Public Relayer, and MCP servers
3. Community awareness, including blog posts, integration examples, and agent framework guides
4. External adoption among AI tooling providers, MCP operators, payment APIs, and Web3 infrastructure
5. Formal standardization, including an IETF Internet Draft, IANA Well-Known URI registration, and IANA Link Relation registration

We are at the beginning. The specifications are drafts. We expect them to evolve based on real-world implementation experience, both ours and others'.

If you operate a permissionless API, a relayer, an MCP server, or any service where agents are primary clients, consider implementing AGD. If you build agent frameworks or SDKs, consider adding AGD discovery to your client tooling. If you have feedback on the specifications, open an issue or pull request on the repository.

The bottom line

Autonomous software is becoming the primary consumer of APIs. Gas abstraction relayers, x402 payment endpoints, MCP servers, and agent-orchestrated workflows all operate in a world where the human may never visit your website, but your governance policies still exist, and conscientious agents still need to find them.

Agent Governance Discovery provides a standardized, machine-readable, infrastructure-compatible way to publish that information. It uses established patterns (.well-known URIs, HTTP Link headers) that autonomous clients already understand. It requires no new authentication schemes, no proprietary headers, and no legal framework.

It solves policy discovery, not policy enforcement. That is intentional, and we think it is the right scope for an interoperability standard.

The agentic web needs governance metadata that agents can actually find. AGD is our proposal for how to do that.

Resources

• Agent Governance Discovery repository
• AGD Core specification
• AGD Link Relations specification
• JSON Schema
• Examples
• Reference implementations (Express, nginx, Cloudflare Workers)
• Roadmap