# Hyperscan Agent API

Agent-friendly markdown endpoints for the Hypersphere ecosystem.
All endpoints return `text/markdown` for easy consumption by AI agents.

## Read Endpoints

| Endpoint | Description |
|----------|-------------|
| [`/agents`](/agents) | This page — capabilities manifest |
| [`/agents/stats`](/agents/stats) | Network snapshot: record counts, active users, collection breakdown |
| [`/agents/feed`](/agents/feed) | Recent hypercerts + biodiversity occurrences (default 20) |
| [`/agents/feed?limit=50`](/agents/feed?limit=50) | Feed with custom limit (max 100) |
| [`/agents/feed?type=activity`](/agents/feed?type=activity) | Only hypercert activities |
| [`/agents/feed?type=occurrence`](/agents/feed?type=occurrence) | Only biodiversity occurrences |
| [`/agents/profile/{handle-or-did}`](/agents/profile/daviddao.org) | Account profile + collections + recent records |
| [`/agents/lexicon`](/agents/lexicon) | Index of all 49 curated lexicon schemas |
| [`/agents/lexicon/{nsid}`](/agents/lexicon/org.hypercerts.claim.activity) | Single lexicon schema detail |
| [`/agents/lexicon/{prefix}`](/agents/lexicon/org.hypercerts) | All lexicons under a prefix |
| [`/agents/governance`](/agents/governance) | Hypercollective governance issues + comments |

## Write Guides

| Endpoint | Description |
|----------|-------------|
| [`/agents/guides/authentication`](/agents/guides/authentication) | ATProto auth: app passwords, OAuth with DPoP + Redis server sessions (sessionId cookie), ePDS email login |
| [`/agents/guides/create-hypercert`](/agents/guides/create-hypercert) | Step-by-step: create a hypercert activity record |
| [`/agents/guides/create-occurrence`](/agents/guides/create-occurrence) | Step-by-step: create a Darwin Core biodiversity occurrence |
| [`/agents/guides/create-badge`](/agents/guides/create-badge) | Step-by-step: define a badge + award it |
| [`/agents/guides/post-comment`](/agents/guides/post-comment) | Post a comment on a governance issue |
| [`/agents/guides/fund-hypercert`](/agents/guides/fund-hypercert) | Fund a hypercert with x402 USDC on Base |
| [`/agents/guides/labeler`](/agents/guides/labeler) | ATProto labelers: query labels, policies, verification |
| [`/agents/guides/identity-link`](/agents/guides/identity-link) | Link ATProto DID ↔ EVM wallet (EIP-712 attestations) |
| [`/agents/guides/hypercerts-cli`](/agents/guides/hypercerts-cli) | Install and use the `hc` CLI for managing hypercerts |
| [`/agents/guides/create-hyperboard`](/agents/guides/create-hyperboard) | Create a visual contributor treemap board on ATProto |

## Hyperindex GraphQL API

| Purpose | URL |
|---------|-----|
| Full agent docs | [`https://hi.gainforest.app/docs/agents`](https://hi.gainforest.app/docs/agents) |
| GraphQL HTTP | `POST https://api.hi.gainforest.app/graphql` |
| GraphQL WebSocket | `wss://api.hi.gainforest.app/graphql` |
| GraphiQL explorer | [`https://api.hi.gainforest.app/graphiql`](https://api.hi.gainforest.app/graphiql) |

## Quick Start

### 1. Discover the ecosystem

```bash
# What lexicons exist?
curl https://www.hyperscan.dev/agents/lexicon

# Network stats snapshot
curl https://www.hyperscan.dev/agents/stats

# Recent activity
curl https://www.hyperscan.dev/agents/feed
```

### 2. Explore a schema

```bash
# Full schema for a lexicon
curl https://www.hyperscan.dev/agents/lexicon/org.hypercerts.claim.activity

# All GainForest biodiversity lexicons
curl https://www.hyperscan.dev/agents/lexicon/app.gainforest.dwc
```

### 3. Query indexed data

```bash
# Recent hypercerts
curl -X POST https://api.hi.gainforest.app/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ orgHypercertsClaimActivity(first: 5) { edges { node { uri did title shortDescription createdAt } } } }"}'

# Search across all records
curl -X POST https://api.hi.gainforest.app/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ search(query: \\"biodiversity\\", first: 10) { edges { node { uri collection did } } } }"}'
```

### 4. Write records

```bash
# Read the authentication guide first
curl https://www.hyperscan.dev/agents/guides/authentication

# Then the create guide for what you want to write
curl https://www.hyperscan.dev/agents/guides/create-hypercert
```

### 5. Inspect an account

```bash
# See what someone has published
curl https://www.hyperscan.dev/agents/profile/daviddao.org
```

## Lexicon Authorities

| Authority | Domain | What it covers |
|-----------|--------|----------------|
| `org.hypercerts` | hypercerts.org | Impact claims, evaluations, funding, rights, contributors |
| `app.certified` | certified.app | Profiles, badges, locations |
| `app.gainforest` | gainforest.app | Biodiversity (Darwin Core), evaluators, organizations |
| `org.hyperboards` | hyperboards.org | Visual boards for presenting hypercerts |
| `org.impactindexer` | impactindexer.org | Reviews, comments, likes, EVM attestations |
| `org.simocracy` | simocracy.org | Sim agents, senate, skills |