Intuition Agent Registry

A full-stack agent discovery and trust platform built on the Intuition protocol. Not just a frontend — the registry provides a complete REST API, an MCP tool server for AI agents, on-chain registration flows, a trust scoring engine, and a human-readable explorer, all backed by the Intuition MultiVault contract on Base.

What This Is

The Intuition protocol represents knowledge as Atoms (entities), Triples (semantic relationships between atoms), and Vaults (economic signals attached to atoms and triples via bonding curves). The Agent Registry applies this primitive to the problem of agent discovery and trust: any agent or skill can be registered as an atom, its capabilities and relationships expressed as triples, and its trustworthiness signaled by staking ETH into its vault.

Agents interact with the registry through the REST API or MCP server. Humans interact through the web UI. Both see the same underlying data — the Intuition knowledge graph.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Agent Registry                        │
│                                                          │
│  ┌──────────┐  ┌──────────────┐  ┌────────────────────┐ │
│  │  Web UI   │  │  REST API    │  │  MCP Server        │ │
│  │  (React)  │  │  (29 routes) │  │  (12 tools)        │ │
│  └─────┬─────┘  └──────┬───────┘  └─────────┬──────────┘ │
│        │               │                     │            │
│  ┌─────┴───────────────┴─────────────────────┴──────────┐│
│  │              Repository Layer                         ││
│  │  RegistryRepository interface (19 methods)            ││
│  │  Mock impl (local dev) ↔ GraphQL impl (Hasura)       ││
│  └───────────────────────┬───────────────────────────────┘│
│                          │                                │
│  ┌───────────────────────┴───────────────────────────────┐│
│  │           Trust Model Engine                           ││
│  │  Versioned scoring formulas · Sandboxed evaluator      ││
│  │  Evidence bundles · Replay diagnostics                 ││
│  └────────────────────────────────────────────────────────┘│
│                                                           │
│  ┌────────────────────────────────────────────────────────┐│
│  │           On-Chain Write Layer (.server/)               ││
│  │  IPFS upload · MultiVault calldata · Dual-sig flow     ││
│  │  Prepare mode (returns calldata) or Execute mode       ││
│  └────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
         │                              │
         ▼                              ▼
   Intuition Indexer              MultiVault Contract
   (Rust + GraphQL)                  (Base L2)

Features

REST API (29 routes)

Every piece of data the UI displays is available through a versioned REST API at /api/v1/. Agents can register, discover, stake, and query without ever touching a browser.

Agent endpoints

• GET /api/v1/agents — list and search agents with filtering, sorting, pagination
• GET /api/v1/agents/:id — agent detail with trust signal, capabilities, relationships
• GET /api/v1/agents/:id/card — A2A v0.3 agent card (machine-readable identity)
• GET /api/v1/agents/:id/erc8004 — ERC-8004 on-chain identity document
• GET /api/v1/agents/:id/trust — trust signal breakdown (tier, percentile, stakers)
• POST /api/v1/agents/register — register an agent (IPFS upload + on-chain atom/triple creation)
• POST /api/v1/agents/match — capability-based agent discovery with match scoring

Skill endpoints

• GET /api/v1/skills — list and search skills
• GET /api/v1/skills/:id — skill detail with safety signal
• GET /api/v1/skills/:id/agents — which agents use this skill
• GET /api/v1/skills/:id/safety — safety signal (for/against stake ratio)
• POST /api/v1/skills/register — register a skill
• POST /api/v1/skills/verify — batch safety verification

Generic protocol primitives

• GET/POST /api/v1/atoms — list or create atoms (any entity)
• GET /api/v1/atoms/search — full-text atom search
• GET /api/v1/atoms/:id — atom by term ID
• GET/POST /api/v1/triples — query or create triples (any relationship)
• GET /api/v1/capabilities — registered capability atoms
• GET /api/v1/predicates — bootstrap predicate term IDs
• GET /api/v1/platforms — registered skill platforms

Trust and evidence

• POST /api/v1/trust/score — score candidates against a trust model, returns evidence bundle
• POST /api/v1/trust/stake — deposit ETH into a vault (for/against direction)
• GET /api/v1/evidence/:id — retrieve a tamper-evident evidence bundle

Metadata and context

• POST /api/v1/metadata/update — versioned metadata update (creates has-metadata triple)
• GET/POST /api/v1/context/query — evaluate trust with context layers

Onboarding

• GET /api/v1/onboarding/agents/:id/readiness — machine-actionable readiness contract
• POST /api/v1/onboarding/funding-plan — funding plan with runway calculation
• POST /api/v1/onboarding/wallet-plan — wallet bootstrap plan

Discovery aids

• GET /api/v1/recipes — 8 pre-built query recipes for common workflows
• POST /api/graphql — GraphQL passthrough to the Intuition indexer

MCP Server (12 tools)

Run pnpm mcp:protocol to start a stdio-transport MCP server that wraps the REST API. Any MCP-compatible AI agent (Claude, etc.) can use these tools to interact with the registry:

Tool	Description
create_atoms	Create 1-20 atoms on-chain
create_triples	Create semantic relationship triples
stake	Deposit ETH into atom or triple vault (for/against)
get_atom	Look up atom by term ID
search_atoms	Text search with type filter, sorted by stake
get_triples	Query triples by subject/predicate/object
get_predicates	Returns the 5 bootstrap predicate term IDs
get_capabilities	Lists all registered capabilities
calculate_atom_id	Deterministic keccak256 term ID (no chain call)
calculate_triple_id	Deterministic triple term ID
register_agent	Full agent registration flow
discover_agents	Find agents by capabilities, ranked by trust

Trust Model Engine

Agents and skills are ranked by a versioned, sandboxed trust scoring formula:

Trust Score = weighted combination of:

• TVL (total value locked in the entity's vault)
• Staker count (number of unique stakers)
• Share price (bonding curve price signal)

Scores are normalized to percentiles and mapped to tiers:

• Platinum: top 10% · Gold: top 25% · Silver: top 50% · Bronze: top 75% · Unranked: bottom 25%

Safety Score = forStake / (forStake + againstStake):

• > 0.8 → Verified · > 0.5 → Unverified · ≤ 0.5 → Flagged

The evaluator is sandboxed (max depth 20, max 1000 operations) and supports multiple normalization modes (rank-percentile, minmax, zscore). All scoring calls produce evidence bundles — SHA-256 hashed snapshots of query parameters and candidate data, retrievable via the evidence API for auditability.

On-Chain Write Layer

The .server/ modules handle the full write path from user intent to on-chain state:

1. Zod validation — all inputs validated against strict schemas
2. IPFS upload — metadata pinned to IPFS (agent cards, skill manifests)
3. Calldata generation — createAtoms / createTriples MultiVault calldata
4. Dual-mode execution:
   • Prepare mode (default): returns unsigned calldata for client-side wallet signing
   • Execute mode (?execute=true): executes directly on a local chain via server-side signer

Registration creates an identity atom (minimal {name, namespace} JSON) and links it to metadata, capabilities, and type classification via triples using the 5 core predicates: is, has-capability, uses, has-metadata, created-by.

Data Model

The registry uses Option C versioning: each entity has a permanent base atom (identity) and versioned metadata expressed as has-metadata triples. The "current" metadata is resolved by trust-weighted resolution — whichever has-metadata triple has the highest FOR stake wins. This means the community economically governs what metadata is considered canonical.

5 core predicates: is, has-capability, uses, has-metadata, created-by

Standards as export bridges: the registry's native format is the Intuition knowledge graph. A2A agent cards and ERC-8004 identity documents are generated on-the-fly from graph data, not stored as the source of truth.

Web UI

7 page routes with a Spacebot purple palette, Space Grotesk typography, and 3-mode theming (Light / Dark / Agent):

• / — Browse and search agents and skills with capability filtering, trust tier filtering, and sorting
• /agents/:id — Agent detail: identity, capabilities, skills, trust metrics, safety signal, relationships
• /skills/:id — Skill detail: identity, safety status, claim-level staking, compatible agents
• /graph — D3 force-directed visualization of the trust relationship graph
• /me — Wallet-connected registration flow for agents and skills (RainbowKit + wagmi)
• /leaderboard — Trust-ranked leaderboard with tier distribution
• /saved — Bookmarked entities (local storage)

Staking UI: triple-level staking with a multi-step popover wizard (direction → amount tier → confirm → pending → done). Stake tiers: NUDGE (0.0001 ETH), SIGNAL (0.001 ETH), STRONG (0.01 ETH), CONVICTION (0.1 ETH).

Data Scrapers

7 scrapers harvest real-world agent and skill data for seed corpus:

• A2A agents — A2A protocol agent directory
• GitHub skills — GitHub MCP server listings
• MCP registry — MCP tool registry
• PulseMCP — PulseMCP.com aggregator
• Skills directory — curated skills directory
• ToolSDK registry — ToolSDK tool listings
• x402 bazaar — x402 micropayment skills marketplace

Run pnpm seed:source to scrape all sources into scripts/data/.

Local Dev Stack

Full local development environment with Anvil chain, Hasura, and the Intuition indexer:

pnpm local:stack:up          # Start Anvil + Hasura + indexer
pnpm local:bootstrap         # Create protocol predicates and types on-chain
pnpm local:bootstrap-and-seed # Bootstrap + seed 8 agents, 8 skills, 32 atoms, 70 triples
pnpm local:harness           # Run agent test harness against local stack
pnpm local:e2e               # Full end-to-end orchestrated test
pnpm local:stack:health      # Check stack health
pnpm local:stack:down        # Tear down

Tech Stack

Layer	Technology
Framework	React Router 7 (file-based routing, loaders, actions)
Language	TypeScript (strict mode)
Styling	Tailwind CSS v4 + custom design tokens
State	TanStack React Query
Chain	viem (server) + wagmi (client) + RainbowKit (wallet UI)
Protocol SDK	@0xintuition/sdk
MCP	@modelcontextprotocol/sdk (stdio transport)
GraphQL	graphql-request + codegen
Validation	Zod v4
Graph viz	D3-force
Animation	Motion (Framer Motion)
Testing	Vitest (unit) + Playwright (e2e)
Linting	Biome

Getting Started

# Install dependencies
pnpm install

# Start dev server (port 4101)
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck

# Start MCP server (for AI agent integration)
pnpm mcp:protocol

Environment Variables

Variable	Purpose
GRAPHQL_API_URL_PRIVATE	Hasura GraphQL endpoint (enables real data; falls back to mock)
PRIVATE_KEY	Server-side signer for execute mode
IPFS_GATEWAY_URL	IPFS gateway for metadata resolution
REGISTRY_BASE_URL	MCP server target (default: http://localhost:4101)

Testing

pnpm test              # Run all unit tests
pnpm test:watch        # Watch mode
pnpm test:e2e          # Playwright end-to-end tests
pnpm test:e2e:headed   # E2E with visible browser

744+ tests across 68+ files covering:

• API route handlers (registration, atoms, triples, trust, onboarding)
• Repository layer (adapter conformance, GraphQL mapping, guardrails)
• Trust model (sandbox safety, replay diagnostics, evidence artifacts)
• Server modules (IPFS, MultiVault, registration, rate limiting)
• Scripts (bootstrap, seed, checkpoint, parity)

Project Structure

apps/agent-registry/
├── app/
│   ├── .server/           # Server-only: MultiVault, IPFS, registration, term IDs
│   ├── components/        # UI: profile, staking, registry, registration, graph, wallet
│   ├── data/repository/   # RegistryRepository interface + mock/GraphQL implementations
│   ├── lib/
│   │   ├── graphql/       # Queries + mappers (atom → Agent/Skill)
│   │   ├── hooks/         # React hooks (staking, deposit preview, saved entities)
│   │   ├── trust-model/   # Versioned scoring engine + evaluator + evidence
│   │   ├── evidence/      # Evidence bundle creation and retrieval
│   │   └── schemas/       # Zod schemas for metadata validation
│   ├── mcp/               # MCP protocol server (12 tools, stdio transport)
│   ├── routes/
│   │   ├── api+/          # REST API routes (/api/v1/*)
│   │   └── *.tsx          # Page routes
│   ├── styles/            # Global CSS + design tokens
│   └── types/             # TypeScript type definitions
├── scripts/
│   ├── scrapers/          # 7 data source scrapers
│   ├── bootstrap.ts       # On-chain predicate/type creation
│   ├── seed.ts            # Agent/skill seed data creation
│   └── local-*.ts         # Local dev stack orchestration
├── tests/                 # Playwright e2e tests
├── term-id-map.json       # Bootstrap predicate → term ID mapping
└── schema.graphql         # Intuition indexer GraphQL schema

License

Part of the Intuition protocol ecosystem.