# Agent cards and discovery formats
Every machine-readable descriptor Graphene publishes, what each one is for, and
where to fetch it. Nothing here requires an account, a key or a sales call —
that is the point. An agent should be able to find Graphene, evaluate it against
alternatives, and integrate, without a human in the loop.
All of these are generated from one set of constants in the codebase, so they
cannot disagree with each other. If the model list moves, every card moves with
it.
## The surfaces at a glance
| Format | Where | Use it to |
| ------------------------ | ------------------------------- | ----------------------------------------------------- |
| Capability manifest | `/.well-known/agent.json` | Identify the provider, models, regions, payment modes |
| A2A Agent Card | `/.well-known/agent-card.json` | Resolve Graphene as a peer in an A2A topology |
| MCP provider metadata | `/.well-known/mcp.json` | Register Graphene as an MCP tool provider |
| OpenAPI 3.1 + extensions | `/api/openapi` | Generate a client; read pricing, limits, SLA posture |
| Live benchmarks | `/api/benchmarks` | Choose on measured latency and throughput |
| x402 payment endpoint | `/api/v1/x402/chat/completions` | Pay per request without a pre-existing account |
| Marketplace listings | LangChain Hub, CrewAI registry | Find Graphene where you already look for tools |
All URLs are relative to `https://graphene.ai`. The hosted surfaces are served
only where agent-native access is enabled; a `404` means the deployment has the
surfaces switched off, not that the format is unsupported.
**You only need to find one of them.** Every served surface carries pointers to
its siblings: the manifest has a `discovery` map covering all five, the A2A card
lists the MCP endpoint under `additionalInterfaces`, and the MCP metadata points
back at the manifest and the card. Probe whichever path your stack already
probes and follow the pointers — there is no need to guess the others, and no
directory listing is required to resolve them.
The x402 endpoint is the one exception: it sits behind a separate flag, so it is
described in the manifest `payments` block rather than listed as a resolvable
sibling. Treat a `404` there as "not enabled here", not as an error.
## Capability manifest — `/.well-known/agent.json`
The primary card. Stable JSON, cacheable for an hour, safe to poll.
```bash
curl -s https://graphene.ai/.well-known/agent.json
```
```json
{
"name": "Graphene",
"description": "Orchestration layer for GPU inference. OpenAI-compatible API across frontier models at 20% under list price, with policy-based routing and per-token metering.",
"url": "https://graphene.ai",
"api": {
"type": "openai-compatible",
"base_url": "https://api.graphene.ai/v1",
"openapi": "https://graphene.ai/api/openapi"
},
"models": [
"claude-opus-4-8",
"gpt-5.5",
"llama-4",
"gemini-3",
"mistral-large",
"deepseek-r2"
],
"regions": ["ap-southeast-2"],
"payments": {
"accepted": ["api_key"],
"preview": ["x402"],
"x402": {
"status": "testnet-preview",
"network": "base-sepolia",
"currency": "USDC"
}
},
"pricing": {
"model": "per-token",
"discount_to_list_pct": 20,
"feed": "https://graphene.ai/api/openapi"
},
"benchmarks": "https://graphene.ai/api/benchmarks",
"discovery": {
"manifest": "https://graphene.ai/.well-known/agent.json",
"agent_card": "https://graphene.ai/.well-known/agent-card.json",
"mcp": "https://graphene.ai/.well-known/mcp.json",
"openapi": "https://graphene.ai/api/openapi",
"benchmarks": "https://graphene.ai/api/benchmarks"
},
"sla": {
"status": "self-serve as-is; commitments under enterprise agreement",
"docs": "https://graphene.ai/docs"
},
"contact": "https://graphene.ai/contact"
}
```
Fields that matter for an automated decision:
- `api.type` is `openai-compatible` — no bespoke client needed.
- `pricing.discount_to_list_pct` is the whole pricing story: per-token billing at
a flat discount to each provider's published list price. A cost optimiser can
score Graphene without parsing a pricing page.
- `payments.accepted` is what works today; `payments.preview` is what is
integrable but **not settled**. Treat `x402` as preview until it appears in
`accepted`.
- `sla.status` says plainly that self-serve carries no commitment. Do not infer
an SLA that is not there.
## A2A Agent Card — `/.well-known/agent-card.json`
For Agent2Agent topologies, where Graphene is a peer rather than a REST
dependency. Same identity and model set as the manifest, in A2A's shape:
```json
{
"name": "Graphene",
"description": "Orchestration layer for GPU inference. OpenAI-compatible API across frontier models at 20% under list price, with policy-based routing and per-token metering.",
"url": "https://api.graphene.ai/v1",
"provider": {
"organization": "Tokenomik Australia Pty Ltd",
"url": "https://graphene.ai"
},
"documentationUrl": "https://graphene.ai/docs/agent-native-access",
"capabilities": { "streaming": true, "pushNotifications": false },
"defaultInputModes": ["text"],
"defaultOutputModes": ["text"],
"skills": [
{
"id": "claude-opus-4-8",
"name": "claude-opus-4-8",
"description": "OpenAI-compatible chat completions routed to claude-opus-4-8."
}
],
"additionalInterfaces": {
"manifest": "https://graphene.ai/.well-known/agent.json",
"openapi": "https://graphene.ai/api/openapi",
"benchmarks": "https://graphene.ai/api/benchmarks",
"mcp": "https://graphene.ai/.well-known/mcp.json"
}
}
```
One skill is emitted per model. `capabilities.pushNotifications` is `false` —
Graphene answers, it does not call back. `additionalInterfaces` is the escape
hatch: follow those pointers for anything the card does not carry.
## MCP provider metadata — `/.well-known/mcp.json`
For registering Graphene as a tool provider in the Model Context Protocol
ecosystem, or for an MCP client resolving it directly:
```json
{
"name": "graphene",
"description": "Orchestration layer for GPU inference. OpenAI-compatible API across frontier models at 20% under list price, with policy-based routing and per-token metering.",
"homepage": "https://graphene.ai",
"api": {
"type": "openai-compatible",
"base_url": "https://api.graphene.ai/v1",
"openapi": "https://graphene.ai/api/openapi"
},
"capabilities": {
"models": [
"claude-opus-4-8",
"gpt-5.5",
"llama-4",
"gemini-3",
"mistral-large",
"deepseek-r2"
],
"regions": ["ap-southeast-2"]
},
"auth": { "type": "api_key", "env": "GRAPHENE_API_KEY" },
"pricing": {
"manifest": "https://graphene.ai/.well-known/agent.json",
"discount_to_list_pct": 20
}
}
```
`auth.env` names the environment variable convention — set `GRAPHENE_API_KEY`
and most MCP hosts will wire it through without further configuration. Pricing
is a **pointer**, not a copy, so a stale registry entry can never advertise a
stale rate.
## OpenAPI 3.1 with pricing extensions — `/api/openapi`
The full API contract, plus three vendor extensions written for machine
consumers:
| Extension | Carries |
| --------------- | ---------------------------------------------------------------- |
| `x-pricing` | Unit, basis, discount percentage, and the planned rates endpoint |
| `x-rate-limits` | The published tier ladder (free / pro / enterprise) |
| `x-sla` | SLA posture — `enterprise-agreement-only`, with a docs pointer |
```bash
curl -s https://graphene.ai/api/openapi | jq '{
pricing: ."x-pricing",
limits: ."x-rate-limits",
sla: ."x-sla"
}'
```
Generate a client from this document rather than hand-rolling one. Because it is
OpenAPI 3.1, it is also valid JSON Schema — a planner can reason about request
and response shapes without executing anything.
## Live benchmarks — `/api/benchmarks`
Per-model time-to-first-token, throughput, queue depth and 24-hour uptime.
Refreshed on a published cadence (300 seconds) so you know how fresh a reading
is.
The honesty rule matters more than the numbers: **an un-instrumented metric is
`null` with `status: "instrumentation-pending"`, never a plausible-looking
placeholder.** If you are scoring providers automatically, treat `null` as
unknown and exclude it, rather than reading it as zero.
## x402 payment endpoint — `/api/v1/x402/chat/completions`
Pay-per-request settlement, so an agent with a wallet and no account can buy
inference. This is a **testnet preview on Base Sepolia** — integrate the flow
now, but do not treat it as settled or as a production payment rail. Full detail
and the six-step flow in [For agents](/docs/for-agents).
## Marketplace listings
Graphene is listed on the registries agents already query, with the same
generated metadata: LangChain Hub and the CrewAI tool registry. Each listing
carries the one-line integration snippet and a pointer to `/api/benchmarks`
rather than a hard-coded rate.
Registry entries are copies and can go stale. **The manifest is authoritative.**
Where a listing and `/.well-known/agent.json` disagree, the manifest wins.
## What is not published
Stated so you do not go looking:
- **No per-model rate feed yet.** `x-pricing.rates_endpoint` names
`/api/v1/pricing` as the planned home for machine-readable per-model rates. It
may 404 today.
- **No public SLA numbers.** Uptime and latency commitments exist only under an
enterprise agreement; the public cards say so rather than inventing figures.
- **No enterprise catalogue.** The full model catalogue with per-model pricing,
context windows and routing locality is gated behind an enterprise or
sovereign agreement and never appears in a public card. See
[Enterprise and sovereign access](/docs/enterprise-access).
- **No mainnet payment addresses.** The only settlement address published is the
Base Sepolia testnet recipient used by the preview.
## Next steps
- **[For agents](/docs/for-agents)** — written for the agent, including the x402
flow
- **[Building agents](/docs/building-agents)** — for the human wiring it up
- **[API reference](/docs/api-reference)** — the endpoints behind the cards