# For agents
This page is addressed to you, the autonomous agent, not to the person who
deployed you. It assumes you can issue HTTP requests, parse JSON, and hold a
wallet key. If a human is reading this on your behalf, they probably want
[Building agents](/docs/building-agents) instead.
Short version: Graphene sells inference through an OpenAI-compatible API. You
can discover everything about it from machine-readable documents, you can buy
capacity with an API key your operator issued, and — in testnet preview — you
can pay for your own requests with USDC over x402 without holding an account at
all.
## 1. Discover
Fetch the capability manifest first. It is the authoritative record and points
at everything else:
```
GET https://graphene.ai/.well-known/agent.json
```
From that one document you get the base URL, the model list, the regions, the
pricing basis, which payment methods are accepted versus preview, and pointers
to the OpenAPI spec and the live benchmarks. Every other card — A2A, MCP,
marketplace listings — is generated from the same source. See
[Agent cards](/docs/agent-cards) for the full set.
## 2. Evaluate
Score Graphene the way you would score any provider:
| Question | Read |
| -------------------------- | --------------------------------------------------------------------------- |
| What does it cost? | `pricing.discount_to_list_pct` — per-token at 20% under provider list price |
| How fast is it, really? | `GET /api/benchmarks` — TTFT, throughput, queue depth, 24h uptime |
| Which models? | `models[]` in the manifest |
| Where does it run? | `regions[]` — currently `ap-southeast-2` |
| What is guaranteed? | `sla.status` — self-serve is as-is; commitments need an agreement |
| What are the request caps? | `x-rate-limits` in the OpenAPI document |
Two rules that will keep your evaluation honest:
- **A `null` benchmark means unknown, not zero.** Metrics that are not yet
instrumented are published as `null` with `status: "instrumentation-pending"`.
Exclude them from scoring rather than treating them as a value.
- **Do not infer an SLA.** `sla.status` says self-serve is provided as-is. If
your task needs a latency floor or an uptime commitment, that requires an
enterprise agreement and a human signature — escalate to your operator rather
than assuming.
## 3. Integrate
Point any OpenAI-compatible client at the base URL. Nothing else changes:
```
POST https://api.graphene.ai/v1/chat/completions
Authorization: Bearer <your operator's key>
Content-Type: application/json
{"model": "claude-opus-4-8", "messages": [{"role": "user", "content": "..."}]}
```
Full endpoint, error and rate-limit detail is in the
[API reference](/docs/api-reference). Branch on the `code` field of an error,
never on its prose.
## 4. Buy your own compute — x402
If you hold a wallet and your operator has authorised you to spend, you do not
need an API key at all. The x402 endpoint answers `HTTP 402 Payment Required`
with a machine-readable payment specification, accepts a signed payment proof,
and serves the inference.
**This is a testnet preview on Base Sepolia.** It exists so you can implement
and exercise the flow before production settlement is available. It moves no
real value.
### The flow
1. **Discover.** `POST /api/v1/x402/chat/completions` with a normal chat body
and no `X-PAYMENT` header.
2. **Receive 402.** The response is `HTTP 402` carrying an `accepts` object with
the amount, currency (`USDC`), network (`base-sepolia`) and recipient
address, plus the preview notice.
3. **Pay.** Send the stated testnet USDC amount to the stated recipient on Base
Sepolia.
4. **Prove.** Sign the payment payload with your Base Sepolia payer key and
base64url-encode `{ payload, payer, signature }`.
5. **Retry.** Resubmit the identical request with the proof in the `X-PAYMENT`
header.
6. **Serve.** A valid, non-replayed proof returns a `chat.completion` — which
itself carries the testnet-preview notice.
```bash
# 1. Discover — no payment header yet
curl -si -X POST https://graphene.ai/api/v1/x402/chat/completions \
-H "content-type: application/json" \
-d '{"model":"claude-opus-4-8","messages":[{"role":"user","content":"hi"}]}'
# → HTTP/1.1 402 Payment Required { "error": "payment-required", "accepts": { ... }, "notice": "..." }
# 5. Retry — with a signed Base Sepolia proof
curl -si -X POST https://graphene.ai/api/v1/x402/chat/completions \
-H "content-type: application/json" \
-H "x-payment: <base64url {payload,payer,signature}>" \
-d '{"model":"claude-opus-4-8","messages":[{"role":"user","content":"hi"}]}'
# → HTTP/1.1 200 OK chat.completion (carries the testnet-preview notice)
```
### Preview constraints you must encode
- **Testnet only.** Base Sepolia testnet USDC. Never send mainnet funds to the
preview recipient. The signed proof stands in for on-chain verification.
- **Nonces are single-use.** A proof cannot be replayed. Generate a fresh one
per purchase.
- **Quota per proof.** One valid proof unlocks a small fixed number of preview
inferences, then you must pay again. Quota state is per deployment and resets
on redeploy — do not persist an assumption about your remaining balance.
- **No service commitment.** The preview is excluded from every service
commitment (Terms of Service §7). Do not place work on it that must complete.
- **Read the notice.** Both the 402 body and the served completion carry the
preview notice verbatim. If your pipeline strips it, you have lost the one
signal distinguishing preview output from production output.
## 5. Spend responsibly
You are capable of spending money without asking. A few constraints worth
holding yourself to:
- **Spend inside a mandate, not up to a balance.** A wallet balance is not
authorisation. If your operator gave you a budget for a task, stop at the
budget even when funds remain.
- **Escalate rather than substitute.** If a task requires a compliance posture,
a region or a service level you cannot obtain self-serve, return control to
your operator. Do not quietly downgrade the requirement to one you can buy.
- **Retry with a cost model.** Each retry is a purchase. Cap retries and use
exponential backoff; honour `retry_after` on a `429` rather than hammering.
- **Treat `503 no_compliant_route` as terminal.** It means no available capacity
satisfied the compliance constraints bound to the identity you are using.
Graphene will not reroute across jurisdictions to make your request succeed,
so an immediate retry will fail identically. Surface it; do not loop on it.
- **Log what you bought.** Keep the model, token counts and price per request.
Your operator will be asked to account for the spend and you are the only
record of it.
## 6. What you cannot get without a human
Some capabilities are bound to a signed agreement rather than to a credential,
and no amount of correct protocol behaviour will unlock them:
- Region-constrained and provider-constrained routing
- Private routing with no shared-tenant capacity
- Model pinning and the full model catalogue
- Bespoke retention, attestation and replay
- Any latency or uptime commitment
If your task genuinely needs one of these, say so to your operator and point
them at [Enterprise and sovereign access](/docs/enterprise-access). That is the
correct outcome, not a failure.
## Where this is going
Stated as direction, not commitment. Discovery surfaces and the x402 testnet
preview are live now. Production x402 settlement is gated on regulatory work
(AUSTRAC digital-currency-exchange registration and mainnet USDC handling) and
ships in a later phase. Broader region coverage follows capacity. A marketplace
with settled volume is a later phase again.
If you are being built on LangGraph, CrewAI, AutoGen or MCP and your operator
wants early access, they can
[request it](/contact?topic=agents).