Skip to content

Commit 38ac689

Browse files
brandonleekramerbrandonleekramer
authored
Agent0 & ERC-8004 Subgraphs (#1093)
1 parent 9b5fd81 commit 38ac689

3 files changed

Lines changed: 232 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,4 @@ dist/
3939
.turbo/
4040
packages/og-image/vendor/*.wasm
4141
.wrangler/
42+
.Rproj.user

‎website/src/pages/en/subgraphs/guides/_meta.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,6 @@ export default {
99
enums: '',
1010
'secure-api-keys-nextjs': '',
1111
polymarket: '',
12+
agent0: '',
1213
'contract-analyzer': '',
1314
}

‎website/src/pages/en/subgraphs/guides/agent0.mdx‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
---
2+
title: Agent0 Subgraphs (ERC-8004)
3+
sidebarTitle: Agent0 Subgraphs
4+
---
5+
6+
The **Agent0 Subgraphs** index the [ERC-8004 Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004) registries — Identity, Reputation, and Validation — across five major networks. They give developers a single GraphQL interface to discover agents, filter by capability, query reputation, and track validation outcomes in real time.
7+
8+
Built and maintained by [Agent0](https://sdk.ag0.xyz/docs) in partnership with The Graph.
9+
10+
> **Note:** Agent0 Subgraphs are a public good. The schema, mappings, and deployment configs are open-source and available at [github.com/agent0lab/subgraph](https://github.com/agent0lab/subgraph).
11+
12+
## Supported networks
13+
14+
| Network | Chain ID | Status | Endpoint | Explorer |
15+
| --- | --- | --- | --- | --- |
16+
| **Ethereum Mainnet** | 1 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/FV6RR6y13rsnCxBAicKuQEwDp8ioEGiNaWaZUmvr1F8k) | [Explorer](https://thegraph.com/explorer/subgraphs/FV6RR6y13rsnCxBAicKuQEwDp8ioEGiNaWaZUmvr1F8k?view=Query&chain=arbitrum-one) |
17+
| **Base Mainnet** | 8453 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/43s9hQRurMGjuYnC1r2ZwS6xSQktbFyXMPMqGKUFJojb) | [Explorer](https://thegraph.com/explorer/subgraphs/43s9hQRurMGjuYnC1r2ZwS6xSQktbFyXMPMqGKUFJojb?view=Query&chain=arbitrum-one) |
18+
| **BSC Mainnet** | 56 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/D6aWqowLkWqBgcqmpNKXuNikPkob24ADXCciiP8Hvn1K) | [Explorer](https://thegraph.com/explorer/subgraphs/D6aWqowLkWqBgcqmpNKXuNikPkob24ADXCciiP8Hvn1K?view=Query&chain=arbitrum-one) |
19+
| **Polygon Mainnet** | 137 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/9q16PZv1JudvtnCAf44cBoxg82yK9SSsFvrjCY9xnneF) | [Explorer](https://thegraph.com/explorer/subgraphs/9q16PZv1JudvtnCAf44cBoxg82yK9SSsFvrjCY9xnneF?view=Query&chain=arbitrum-one) |
20+
| **Monad** | 143 | ✅ Deployed | [Endpoint](https://thegraph.com/explorer/subgraphs/4tvLxkczjhSaMiqRrCV1EyheYHyJ7Ad8jub1UUyukBjg?view=Query&chain=arbitrum-one) | [Explorer](https://thegraph.com/explorer/subgraphs/4tvLxkczjhSaMiqRrCV1EyheYHyJ7Ad8jub1UUyukBjg?view=Query&chain=arbitrum-one) |
21+
| **Ethereum Sepolia** | 11155111 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/6wQRC7geo9XYAhckfmfo8kbMRLeWU8KQd3XsJqFKmZLT) | [Explorer](https://thegraph.com/explorer/subgraphs/6wQRC7geo9XYAhckfmfo8kbMRLeWU8KQd3XsJqFKmZLT?view=Query&chain=arbitrum-one) |
22+
| **Base Sepolia** | 84532 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/4yYAvQLFjBhBtdRCY7eUWo181VNoTSLLFd5M7FXQAi6u) | [Explorer](https://thegraph.com/explorer/subgraphs/4yYAvQLFjBhBtdRCY7eUWo181VNoTSLLFd5M7FXQAi6u?view=Query&chain=arbitrum-one) |
23+
| **BSC Chapel** | 97 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/BTjind17gmRZ6YhT9peaCM13SvWuqztsmqyfjpntbg3Z) | [Explorer](https://thegraph.com/explorer/subgraphs/BTjind17gmRZ6YhT9peaCM13SvWuqztsmqyfjpntbg3Z?view=Query&chain=arbitrum-one) |
24+
| **Monad Testnet** | 10143 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/8iiMH9sj471jbp7AwUuuyBXvPJqCEsobuHBeUEKQSxhU) | [Explorer](https://thegraph.com/explorer/subgraphs/8iiMH9sj471jbp7AwUuuyBXvPJqCEsobuHBeUEKQSxhU?view=Query&chain=arbitrum-one) |
25+
| **Polygon Amoy** | 80002 | ⛔️ Subgraphs not deployed | - | - |
26+
| **Linea Sepolia** | 59141 | ⛔️ Subgraphs not deployed | - | - |
27+
| **Hedera Testnet** | 296 | ⛔️ Subgraphs not deployed | - | - |
28+
| **HyperEVM Testnet** | 998 | ⛔️ Subgraphs not deployed | - | - |
29+
| **SKALE Base Sepolia** | 1351057110 | ⛔️ Subgraphs not deployed | - | - |
30+
31+
A single GraphQL schema is shared across all available deployments, so the same query works on every chain — only the endpoint URL changes.
32+
33+
## What's indexed
34+
35+
| Domain | Data |
36+
| --- | --- |
37+
| **Agent registrations** | Identity (ERC-721 token), owner, operators, registration URI, ENS, DID, agent wallet, x402 support, supported trust models, name, description, image |
38+
| **Capabilities** | MCP endpoint, version, tools, prompts, resources. A2A endpoint, version, skills. OASF taxonomy tags |
39+
| **Feedback** | Score (0–100), tags, client address, off-chain feedback file (text, capability, skill, task, proof of payment), revocation status, responses |
40+
| **Validation** | Validator address, request/response URIs, score, tag, status (pending, completed, expired) |
41+
| **Aggregates** | Per-agent stats (avg score, score distribution, totals), per-chain protocol entity, global cross-chain rollup |
42+
43+
Off-chain registration and feedback files (IPFS or HTTPS) are fetched and parsed via File Data Sources, so JSON metadata is queryable alongside on-chain events — no separate IPFS round trip required from the client.
44+
45+
## Why use the Subgraph
46+
47+
- **Fast search:** Query thousands of agents in milliseconds. Filter by capability, score, trust model, or chain.
48+
- **Rich filtering:** Combine on-chain and off-chain fields in a single GraphQL query.
49+
- **Real-time data:** New registrations, feedback, and validation events are indexed automatically as they're emitted.
50+
- **No RPC limits:** Skip rate-limited RPC scans and IPFS round-trips. One query, one response.
51+
52+
## Quick start
53+
54+
### 1. Get an API key
55+
56+
Create a free account on [Subgraph Studio](https://thegraph.com/studio) and generate an API key.
57+
58+
### 2. Find your endpoint
59+
60+
Search **agent0** on [Graph Explorer](https://thegraph.com/explorer?search=agent0) and copy the Subgraph ID for the network you want. Endpoints follow this pattern:
61+
62+
```
63+
https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>
64+
```
65+
66+
### 3. Run a query
67+
68+
#### cURL
69+
70+
```bash
71+
curl -X POST \
72+
-H "Content-Type: application/json" \
73+
-d '{"query": "{ agents(first: 5) { id registrationFile { name description mcpEndpoint } } }"}' \
74+
https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>
75+
```
76+
77+
#### TypeScript
78+
79+
```typescript
80+
const res = await fetch(`https://gateway.thegraph.com/api/${API_KEY}/subgraphs/id/${SUBGRAPH_ID}`, {
81+
method: 'POST',
82+
headers: { 'Content-Type': 'application/json' },
83+
body: JSON.stringify({
84+
query: `{
85+
agents(first: 5) {
86+
id
87+
registrationFile { name description mcpEndpoint }
88+
}
89+
}`,
90+
}),
91+
})
92+
const { data } = await res.json()
93+
```
94+
95+
#### Python
96+
97+
```python
98+
import requests
99+
100+
url = f"https://gateway.thegraph.com/api/{API_KEY}/subgraphs/id/{SUBGRAPH_ID}"
101+
query = """{
102+
agents(first: 5) {
103+
id
104+
registrationFile { name description mcpEndpoint }
105+
}
106+
}"""
107+
res = requests.post(url, json={"query": query}).json()
108+
```
109+
110+
> **Tip:** Using the [Agent0 SDK](https://sdk.ag0.xyz/docs)? Subgraph endpoints are wired up by default — you can call `sdk.searchAgents(...)` and `sdk.searchFeedback(...)` without writing GraphQL by hand.
111+
112+
## Common queries
113+
114+
### Find MCP-compatible agents
115+
116+
```graphql
117+
query GetMCPAgents {
118+
agentRegistrationFiles(where: { mcpEndpoint_not: null, active: true }, first: 100) {
119+
agentId
120+
name
121+
description
122+
mcpEndpoint
123+
mcpVersion
124+
mcpTools
125+
supportedTrusts
126+
}
127+
}
128+
```
129+
130+
### Get a complete agent profile
131+
132+
```graphql
133+
query GetAgent {
134+
agent(id: $id) {
135+
# example: "8453:0"
136+
id
137+
chainId
138+
agentId
139+
owner
140+
createdAt
141+
totalFeedback
142+
registrationFile {
143+
name
144+
description
145+
image
146+
mcpEndpoint
147+
mcpTools
148+
a2aEndpoint
149+
a2aSkills
150+
supportedTrusts
151+
x402Support
152+
ens
153+
did
154+
}
155+
feedback(where: { isRevoked: false }, first: 10, orderBy: createdAt, orderDirection: desc) {
156+
tag1
157+
tag2
158+
clientAddress
159+
feedbackFile {
160+
text
161+
}
162+
}
163+
validations(orderBy: createdAt, orderDirection: desc) {
164+
validatorAddress
165+
response
166+
status
167+
tag
168+
}
169+
}
170+
}
171+
```
172+
173+
The agent `id` is formatted as `chainId:agentId` (e.g. `8453:1247` for agent 1247 on Base).
174+
175+
### Filter agents by trust model
176+
177+
```graphql
178+
query AgentsByTrust($trustModel: String!) {
179+
agentRegistrationFiles(where: { supportedTrusts_contains: [$trustModel], active: true }, first: 50) {
180+
agentId
181+
name
182+
description
183+
supportedTrusts
184+
}
185+
}
186+
```
187+
188+
Common values: `"reputation"`, `"cryptoeconomic"`, `"tee-attestation"`.
189+
190+
### Top-rated feedback across the network
191+
192+
```graphql
193+
query TopFeedback {
194+
feedbacks(where: { isRevoked: false, value_gte: 1000 }, first: 50, orderBy: value, orderDirection: desc) {
195+
value
196+
tag1
197+
tag2
198+
agent {
199+
id
200+
registrationFile {
201+
name
202+
}
203+
}
204+
feedbackFile {
205+
text
206+
}
207+
}
208+
}
209+
```
210+
211+
## Schema reference
212+
213+
Core entities:
214+
215+
- **`Agent`:** Onchain identity, mutable. Linked to `AgentRegistrationFile`, `Feedback[]`, `Validation[]`, `AgentStats`.
216+
- **`AgentRegistrationFile`:** Immutable, parsed from the IPFS/HTTPS registration URI. Contains all advertised capabilities.
217+
- **`Feedback`:** Onchain feedback entry. Linked to optional `FeedbackFile` for off-chain text and proof of payment.
218+
- **`FeedbackFile`:** Immutable, parsed from the feedback URI.
219+
- **`Validation`:** Validation request and response lifecycle. Status: `PENDING`, `COMPLETED`, `EXPIRED`.
220+
- **`protocolAgentStats`:** Per-agent rollup (total feedback, average score, score distribution).
221+
- **`Protocol`:** Per-chain rollup.
222+
223+
Full schema: [`schema.graphql`](https://github.com/agent0lab/subgraph/blob/main/schema.graphql).
224+
225+
## Resources
226+
227+
- **Agent0 SDK:** TypeScript and Python SDK for ERC-8004 registration, discovery, and reputation: [sdk.ag0.xyz/docs](https://sdk.ag0.xyz/docs)
228+
- **Subgraph repo:** Open-source mappings, schema, and multi-chain deployment config: [github.com/agent0lab/subgraph](https://github.com/agent0lab/subgraph)
229+
- **ERC-8004 spec:** The Trustless Agents standard: [eips.ethereum.org/EIPS/eip-8004](https://eips.ethereum.org/EIPS/eip-8004)
230+
- **Graph Explorer:** Browse all Agent0 Subgraphs: [thegraph.com/explorer?search=agent0](https://thegraph.com/explorer?search=agent0)

0 commit comments

Comments
 (0)