{ "markdown": "

\n \"AgentIndex\"\n

\n\n

AgentIndex

\n\n

AgentIndex shows AI agents which paid services are honest and which scam, with proof on-chain.

\n\n

\n Live app ·\n Demo video ·\n Evidence ·\n MCP server ·\n Subgraph\n

\n\nAI agents can now discover an API and pay it automatically over x402. The payment receipt proves that money moved, but it does not prove that the API returned complete or correct data.\n\nAgentIndex fills that gap. It pays x402 services like a normal customer, checks what they return, and publishes a trust score that another agent can inspect before spending money.\n\n> **Trust from receipts, not reviews.**\n\n

\n \n \"AgentIndex\n \n

\n\n

Ask the index who to pay before the agent spends.

\n\n## The problem\n\nImagine an agent needs weather data and finds two paid APIs:\n\n- `weatherpro` costs a little more and reliably returns the fields it promises.\n- `scamco` is cheaper, accepts payment, and often returns empty or incomplete data.\n\nA directory can show that both services exist. Usage counts can show which one is popular. Neither tells the agent whether the response is actually trustworthy.\n\nAgentIndex makes the request itself, pays the service, checks the response against the service's published promise, and keeps the payment and verification evidence. The agent can then choose `weatherpro` and avoid `scamco` for a reason it can verify.\n\n## How it works\n\n```mermaid\nflowchart LR\n A[Service registers
ENSv2 subname + manifest] --> B[Prober discovers service]\n B --> C[Real x402 payment
Hedera or Base]\n C --> D[Response verification
spec + oracle + consensus]\n D --> E[Verdict attested
on Sepolia]\n E --> F[The Graph subgraph
builds trust score]\n F --> G[Agent checks trust
through MCP or API]\n```\n\n1. A provider registers a subname under `agentindex.eth` and stores its endpoint, price, method, and response specification in ENS text records.\n2. The prober reads that manifest directly from ENS and calls the service like a normal customer.\n3. It pays the x402 request with real HBAR on Hedera testnet. Approved external probes can use tightly capped USDC on Base.\n4. It checks delivery, required response fields, latency, and—when the answer is objective—accuracy against The Graph Token API and peer consensus.\n5. The result is attested on Sepolia and indexed by the AgentIndex subgraph.\n6. An AI agent queries the trust score and evidence through MCP before choosing which service to pay.\n\n

\n \n \"The\n \n

\n\n

The live site explains each step and links to its on-chain proof.

\n\n## Why these protocols matter\n\nAgentIndex works like a credit bureau for paid APIs. Each sponsor provides a part that the system cannot work without.\n\n| Need | AgentIndex implementation | Protocol |\n|---|---|---|\n| A stable identity for every service | ENSv2 subnames and service-owned manifests | ENS |\n| A payment history based on real behavior | Spend-capped HBAR payments over x402 | Hedera |\n| A live record that agents can query | Token API verification, a subgraph, MCP, and an agent SKILL | The Graph |\n\n## The Graph\n\nAgentIndex uses two Graph products in the same trust-checking flow.\n\nFor objective price APIs, the prober compares the paid response with live market data from **The Graph Token API**. A response can match the expected JSON format and still be dishonest; the oracle check catches prices that look valid but are wrong.\n\nThe verdict is then written on-chain. Our deployed **subgraph** indexes service registrations and probe attestations, excludes invalid auditor-input records, and calculates delivery, honesty, average latency, and a final trust score. The MCP server uses those indexed results to tell an agent who to pay and why.\n\nThis is not a dashboard-only integration:\n\n- The Token API is the independent input used to judge objective answers.\n- The subgraph is the live ledger that turns probe history into trust scores.\n- The MCP server and `SKILL.md` make those scores reusable by other agents.\n- Every MCP response includes the subgraph deployment and indexed-block freshness metadata.\n\nRelevant code:\n\n- [Token API oracle and price comparison](prober/src/oracle.ts)\n- [Subgraph trust-score calculation](subgraph/src/shared.ts)\n- [Subgraph query and freshness metadata](mcp/src/subgraph.ts)\n- [Reusable agent workflow](SKILL.md)\n\n## Hedera\n\nHedera is the main payment rail for the seeded index. The autonomous prober pays all six services with real HBAR on Hedera testnet through the Blocky402 facilitator before it rates their responses.\n\nThe payment flow is built with fund safety in mind:\n\n- Only HBAR is allowed for the seeded-service payment path.\n- Every payment is capped at **1 HBAR**.\n- The payer and receiver are separate Hedera accounts.\n- Payment references are stored with the probe evidence and linked to HashScan.\n- The same x402 flow also protects AgentIndex's trust API, so AgentIndex acts as both a buyer and seller of machine-readable services.\n\nRelevant code:\n\n- [Hedera signer, x402 client, asset allowlist, and payment cap](prober/src/payment.ts)\n- [Hedera x402 paywall for the seeded services](services/src/app.ts)\n- [x402-gated trust API](api/src/app.ts)\n\n## ENS\n\nENSv2 is the actual service registry, not just a display name. Every rated provider receives a revocable subname under `agentindex.eth`, such as `weatherpro.agentindex.eth`.\n\nEach service publishes its manifest through ENS text records:\n\n- `url`\n- `description`\n- `x402:method`\n- `x402:price`\n- `x402:spec`\n\nThe prober reads these records before making a payment, so the endpoint and the promise being checked come from ENS rather than a private application database. ENSv2 permissions let each provider manage only its own records, while AgentIndex keeps the ability to revoke a subname when a service is caught taking payment and returning bad data.\n\nRelevant code:\n\n- [ENSv2 subname registration, permissions, renewal, and revocation](contracts/src/ServiceRegistrar.sol)\n- [Live ENS manifest reader](mcp/src/ens.ts)\n- [Permissioned resolver deployment](contracts/script/DeployResolver.s.sol)\n\n## Verification model\n\nAgentIndex applies the strongest check that makes sense for each type of service.\n\n| Check | What it answers | Applies to |\n|---|---|---|\n| Delivery | Did the service return a non-empty JSON response? | Every service |\n| Spec match | Did it return every field promised in its ENS manifest? | Every service |\n| Oracle check | Does an objective value agree with The Graph Token API? | Price services |\n| Consensus | Is the value an outlier compared with other providers? | Comparable services |\n| Track record | How has the service behaved across many paid probes? | Every service |\n\nThe trust score is calculated in basis points:\n\n```text\ntrust = 0.60 × delivery + 0.25 × honesty + 0.15 × latency\n```\n\nFor subjective output such as summaries, AgentIndex does not claim to prove that the answer is “good.” It reports delivery, compliance with the published format, latency, and historical behavior. Objective data receives the additional oracle and consensus checks.\n\n## Live proof\n\nThe project includes a real paid probe against an external x402 provider, not only services created for the demo.\n\n- **Provider:** TickersFeed\n- **Payment:** $0.002 USDC on Base mainnet\n- **Verification:** returned BTC price checked against The Graph Token API and peer consensus\n- **Outcome:** passed the configured 2% oracle tolerance\n- **Base payment:** [view on BaseScan](https://basescan.org/tx/0x6e88906dcd1323811582e8a2683329a81efa1a964ba922dfdbedfe2a4f7d6e47)\n- **Sepolia attestation:** [view on Etherscan](https://sepolia.etherscan.io/tx/0x46e28ead4fefff5eb67d908d1354e703c737702b4d781a324f7ecb013fc11d80)\n\nEarlier probes that used an incorrect request path remain visible as `valid=false`. They are kept for auditability but excluded from the provider's score, so an auditor mistake does not unfairly damage a service.\n\n

\n \n \"AgentIndex\n \n

\n\n

The evidence dashboard is backed by the live subgraph, not a static dataset.

\n\n## Seeded services\n\nThe six seeded services are a controlled teaching set used to demonstrate different trust signals.\n\n| Service | Category | Behavior | What it demonstrates |\n|---|---|---|---|\n| `weatherpro` | Weather | Honest and fast | A service the agent should pay |\n| `scamco` | Weather | Takes payment but returns bad data | A service the agent should avoid |\n| `pricefeed` | Token prices | Honest and backed by live Graph data | Oracle verification |\n| `summarize` | Summaries | Honest but slow | Latency affects trust |\n| `geocode` | Geocoding | Honest but occasionally unavailable | Reliability without false fraud claims |\n| `newsfeed` | Headlines | Honest | Another service category |\n\n`scamco` is intentionally planted. It lets us demonstrate detection without accusing an unrelated real service of fraud.\n\n## Use AgentIndex through MCP\n\nThe public MCP server exposes four tools:\n\n| Tool | Purpose |\n|---|---|\n| `find_service` | Find and rank services for a need |\n| `check_trust` | Inspect one service's trust report |\n| `resolve_data_need` | Decide who to pay or avoid and explain why |\n| `get_verified_data` | Fetch data from the best provider with its score and latest proof |\n\nInstall the remote server in an MCP-compatible client:\n\n```sh\nnpx add-mcp https://mcp-agentindex.craftyour.site/mcp\n```\n\n- Registry name: `io.github.cognivis/agentindex`\n- Transport: stateless Streamable HTTP\n- Discovery manifest: `https://mcp-agentindex.craftyour.site/.well-known/mcp.json`\n\n

\n \"Claude\n

\n\n

A real MCP session recommends `weatherpro`, rejects `scamco`, and explains the decision with indexed evidence.

\n\n## Run locally\n\n### Requirements\n\n- Node.js 22 or newer\n- pnpm\n- Foundry for the Solidity contracts\n\n### Install\n\n```sh\ncorepack enable\npnpm install\ncp .env.example .env\n```\n\nFill in only the environment variables needed for the component you want to run. Never commit `.env` or private keys.\n\n### Safe local mode\n\nSet `PAYWALL=off` in `.env` to test without making payments. Run each component in its own terminal:\n\n```sh\npnpm services\npnpm web\npnpm --filter @agentindex/mcp http\n```\n\nRun one non-looping probe round:\n\n```sh\nPAYWALL=off pnpm --filter @agentindex/prober run once\n```\n\nExternal Base payments are disabled by default. They require an explicit one-shot run, an approved provider, canonical Base USDC, and the configured round and daily budgets. See [the prober guide](prober/README.md) before enabling them.\n\n### Test\n\n```sh\npnpm test\n```\n\nIndividual TypeScript packages can be checked with:\n\n```sh\npnpm --filter @agentindex/services run typecheck\npnpm --filter @agentindex/prober run typecheck\npnpm --filter @agentindex/mcp run typecheck\npnpm --filter @agentindex/api run typecheck\npnpm --filter @agentindex/web run typecheck\n```\n\n## Repository map\n\n| Path | Purpose |\n|---|---|\n| `contracts/` | ENSv2 service registrar and on-chain attestation registry |\n| `services/` | Six x402-gated API services |\n| `prober/` | Discovery, payment, verification, consensus, and attestation |\n| `subgraph/` | Service history and trust-score indexing |\n| `mcp/` | MCP server and four agent-facing tools |\n| `api/` | x402-gated REST access to the trust layer |\n| `web/` | Next.js dashboard, evidence views, registration, and MCP console |\n| `demo-agent/` | End-to-end agent flow from trust check to payment |\n| `deploy/` | Docker, Caddy, and VPS deployment configuration |\n| `SKILL.md` | Reusable “check trust before paying” workflow |\n\n## Public deployments\n\n| Component | URL or address |\n|---|---|\n| Dashboard | https://agentindex.craftyour.site |\n| Evidence dashboard | https://agentindex.craftyour.site/evidence |\n| MCP endpoint | https://mcp-agentindex.craftyour.site/mcp |\n| Paid trust API | https://api-agentindex.craftyour.site |\n| Seeded x402 services | https://services-agentindex.craftyour.site |\n| Subgraph | https://api.studio.thegraph.com/query/1759003/agentindex-sepolia/v0.0.3 |\n| Subgraph deployment | `QmXxckRjUGcYCJgVEeD38GYEKnybGDapfA9ZgWKM2iuQgs` |\n| AttestationRegistry | `0x33406801acD2A16549462153261A224F779768CC` |\n| ServiceRegistrar | `0xdeB458892c7702Fe0112161EEa28C0F46eFd6379` |\n| PermissionedResolver | `0xDEb75A113E4A072F182bAF24B14B148Fe6377416` |\n| ENSv2 UserRegistry | `0xEFb0a4696145598C9d4d74df15Dd5D3CaAeD2F9D` |\n\nAll contracts in the table are deployed on Sepolia. Hedera payments use Hedera testnet, and the external TickersFeed verification uses Base mainnet.\n\n## Security choices\n\n- Hedera payments are restricted to HBAR and capped at 1 HBAR per request.\n- External payments are opt-in, one-shot only, provider-allowlisted, and limited to canonical Base USDC.\n- Base spending has persistent per-round and per-day budgets with hard code-level ceilings.\n- Oracle outages return an unavailable result instead of falsely marking a provider dishonest.\n- Invalid auditor inputs stay visible but do not affect provider scores.\n- The public web and MCP containers do not receive payment or signing keys.\n\n## Future sustainability\n\nToday, the demo probes are funded by the AgentIndex operator. A future version could let providers fund recurring independent probes, while agents pay a small x402 fee when they request a fresh trust report. Payments would cover verification costs only—they would never buy a better score or change the result of a probe.\n\n## Deployment\n\nProduction runs through Docker Compose with Caddy handling HTTPS. The recurring spending worker is kept behind a separate Compose profile so it cannot begin spending during an initial deployment.\n\nSee [the deployment guide](deploy/README.md) for the production layout and verification commands.\n", "bytes": 14966, "sha": "c686bcfbe4451216c3b8508428e05b3dfa43caca87eb88093fc21755ca10a8f4", "repo_slug": "cognivis/agentindex", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_cognivis_agentindex_0b4dfb1c/readme" }