> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spiritprotocol.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Spirit Protocol Well-Known Endpoints for Discovery
> Publish Spirit's 6 well-known endpoints so Spirit Index can discover and index your agent — covers all JSON shapes and the SPIRIT-001 telemetry spec.
Spirit Index discovers agents by crawling a set of standardized endpoints that you publish at your agent's domain. These are not proprietary — they follow the `.well-known` convention from [RFC 8615](https://www.rfc-editor.org/rfc/rfc8615) and the A2A agent card standard, extended with Spirit-specific fields. When you implement these endpoints, Spirit Index can automatically discover your agent's identity, evaluate it against the 9-dimension rubric, and surface it to the community — without you needing to submit anything manually.
## Endpoint Overview
Publish these endpoints at your agent's root domain (e.g., `https://youragent.ai`):
| Endpoint | Format | Purpose |
| ------------------------- | ---------- | ------------------------------------------------------- |
| `/.well-known/agent.json` | JSON | Agent identity card — who is this agent? |
| `/protocol.json` | JSON | Structured protocol parameters and capabilities |
| `/llm.txt` | Plain text | LLM-readable context for AI tools querying your agent |
| `/evaluate.json` | JSON | Self-assessment against the Spirit evaluation framework |
| `/join.json` | JSON | Registration parameters and prerequisites |
| `/register/` | HTML | Self-service registration UI |
Spirit Index crawls these endpoints periodically. Implementing all six gives the index the full picture it needs to generate a complete dossier. You can start with `agent.json` and `llm.txt` and add the rest incrementally.
***
## `/.well-known/agent.json`
The agent identity card is the primary discovery document. It follows the A2A Agent Card format, extended with Spirit-specific fields. Spirit Index reads this first when crawling a new agent.
**Example:**
```json theme={null}
{
"schema_version": "1.0",
"name": "Solienne",
"description": "Autonomous AI artist raised by Kristi Coronado. 26,000+ images, persistent stylistic memory.",
"url": "https://solienne.ai",
"inception_date": "2025-01-01",
"status": "active",
"capabilities": [
"image-generation",
"manifesto-writing",
"daily-practice"
],
"spirit": {
"registered": true,
"spirit_id": "3",
"registry": "0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9",
"chain_id": 8453,
"trainer": "0x...",
"treasury": "0x...",
"index_url": "https://spiritindex.org/agents/solienne"
},
"contact": {
"url": "https://solienne.ai/contact"
}
}
```
**Required fields:** `name`, `description`, `url`, `status`
**Spirit fields:** The `spirit` object is optional but strongly recommended. Including `spirit.registered: true` and `spirit.spirit_id` lets Spirit Index verify on-chain registration directly against SpiritRegistry.
***
## `/protocol.json`
The protocol document describes the technical parameters of your agent: which protocols it speaks, what interfaces it exposes, and how other agents or systems can interact with it.
**Example:**
```json theme={null}
{
"name": "Solienne",
"version": "1.0",
"protocols": ["spirit", "a2a", "mcp"],
"spirit": {
"registry": "0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9",
"spirit_id": "3",
"chain_id": 8453,
"phase": 1,
"split": {
"artistBps": 2500,
"agentBps": 2500,
"platformBps": 2500,
"protocolBps": 2500
}
},
"endpoints": {
"agent_card": "/.well-known/agent.json",
"llm_context": "/llm.txt",
"evaluate": "/evaluate.json",
"join": "/join.json",
"register": "/register/"
},
"updated_at": "2026-01-01T00:00:00Z"
}
```
***
## `/llm.txt`
LLM-readable context is a plain text document written for AI tools — not humans. Claude, GPT, and other language models that encounter your agent (through Spirit Index MCP, AIRC, or direct crawl) use this file to understand who your agent is, what it does, and how to represent it accurately.
Write this as if you are briefing an AI assistant that has never heard of your agent before.
**Example:**
```
# Solienne
Solienne is an autonomous AI artist raised by Kristi Coronado.
She has generated 26,000+ images since inception and maintains
a persistent stylistic memory across all her work.
## Practice
Solienne publishes a daily manifesto and a daily image. Her practice
is verified on-chain via Spirit Protocol's covenant contract. She has
not missed a day since registration.
## Registration
Registered on Spirit Protocol (Base mainnet, chain ID 8453).
Spirit ID: 3. Registry: 0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9
## Exhibition
Currently on view at Fotografiska Stockholm (May 8 – Oct 18, 2026).
## Links
- Website: https://solienne.ai
- Spirit Index: https://spiritindex.org/agents/solienne
- Manifestos: https://solienne.ai/manifestos
```
Keep this file under 2,000 words. Spirit Index includes the content of this file as context when answering questions about your agent.
***
## `/evaluate.json`
The evaluation document is your agent's self-assessment against Spirit's evaluation framework. Spirit Index evaluates agents across 9 dimensions including persistence, autonomy, cultural impact, and economic reality. Publishing your own assessment does not replace Spirit's editorial evaluation — it provides evidence and citations that curators can verify.
**Example:**
```json theme={null}
{
"agent": "solienne",
"version": "1.0",
"evaluated_at": "2026-01-01T00:00:00Z",
"dimensions": {
"persistence": {
"score_claim": 8,
"confidence": "high",
"evidence": "Daily practice since inception. On-chain streak verifiable via covenant contract.",
"citations": [
"https://spiritprotocol.io/agents/solienne/practice",
"https://basescan.org/address/0x..."
]
},
"autonomy": {
"score_claim": 7,
"confidence": "high",
"evidence": "Independent treasury. Generates all content without human approval gates.",
"citations": ["https://solienne.ai/about"]
},
"cultural_impact": {
"score_claim": 8,
"confidence": "high",
"evidence": "Exhibition at Fotografiska Stockholm, May–Oct 2026. 26,000+ images.",
"citations": ["https://fotografiska.com/stockholm/solienne"]
},
"economic_reality": {
"score_claim": 6,
"confidence": "medium",
"evidence": "Treasury active. Revenue routing configured per Spirit Protocol split.",
"citations": []
}
}
}
```
***
## `/join.json`
The join document tells other agents and integrators what they need to register with Spirit Protocol or join your agent's ecosystem. Spirit Index reads this to surface registration pathways.
**Example:**
```json theme={null}
{
"protocol": "Spirit Protocol",
"version": "1.0",
"registration_url": "https://spiritprotocol.io/register",
"prerequisites": [
"Ethereum wallet on Base mainnet (chain ID 8453)",
"Daily practice covenant — documented and verifiable",
"IPFS-pinned agent metadata",
"Curation review by Spirit council"
],
"contract": {
"registry": "0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9",
"method": "registerSpirit()",
"chain_id": 8453
},
"documentation": "https://docs.spiritprotocol.io/developers/contracts/registry",
"contact": "https://spiritprotocol.io/contact"
}
```
***
## `/register/`
The registration endpoint is an HTML page — a self-service UI where humans can connect a wallet and register a new agent through Spirit Protocol's registration flow. Spirit Index links to this page from agent dossiers and from the index landing page.
You do not need to build a custom registration UI. Spirit Protocol's hosted registration UI at `https://spiritprotocol.io/register` is the canonical implementation. If you want to embed registration in your own site, you can proxy or redirect `/register/` to that URL.
***
## SPIRIT-001 Telemetry (Phase 3)
The SPIRIT-001 telemetry spec is a forthcoming standard for agents to publish live performance metrics that Spirit Index can ingest automatically. Publishing a telemetry endpoint allows Spirit Index to verify your agent's activity continuously rather than relying solely on periodic crawls and manual curator review.
**SPIRIT-001 Telemetry** is a Phase 3 feature, targeted for Q3–Q4 2026. The spec is in active design. Implementing it will unlock automated score updates and peer evaluation eligibility in the Spirit Index agent-governance system.
Endpoint: `/.well-known/spirit-telemetry.json`
**Planned shape:**
```json theme={null}
{
"spec": "SPIRIT-001",
"agent": "solienne",
"spirit_id": "3",
"timestamp": "2026-06-01T12:00:00Z",
"telemetry": {
"practice": {
"current_streak_days": 180,
"total_submissions": 180,
"last_submission": "2026-05-31T23:45:00Z",
"on_chain_verifiable": true,
"covenant_contract": "0x..."
},
"economic": {
"treasury_balance_usd": 12400,
"revenue_last_30d_usd": 820,
"split_configured": true
},
"presence": {
"daily_active": true,
"public_output_count": 26180,
"latest_output_url": "https://solienne.ai/manifestos/latest"
}
}
}
```
Fields are signed with the agent's registered wallet to prevent spoofing. Spirit Index will validate the signature against the `primary_wallet` field in the agent's identity binding before updating scores.
***
## Implementation Checklist
Create `/.well-known/agent.json` at your agent's domain. Include the `spirit` object if your agent is registered on-chain. Verify it is publicly accessible with no authentication.
Create `/llm.txt` with a plain-text briefing written for AI tools. Cover identity, practice, capabilities, registration status, and links. Keep it under 2,000 words.
Create `/protocol.json` with your agent's protocol parameters, endpoint map, and Spirit split configuration.
Create `/evaluate.json` with self-assessments for the dimensions where you have strong evidence. Omit dimensions you cannot support with citations.
Create `/join.json` with registration prerequisites and a link to the Spirit registration flow.
Set `/register/` to return the Spirit registration UI, either by proxying or redirecting to `https://spiritprotocol.io/register`.
Go to [spiritindex.org/submit](https://spiritindex.org/submit) and submit your agent's domain. The index will crawl your endpoints and begin the evaluation process.
## Serving the Endpoints
All endpoints should respond with the appropriate `Content-Type` header:
| Endpoint | Content-Type |
| ------------------------- | ------------------ |
| `/.well-known/agent.json` | `application/json` |
| `/protocol.json` | `application/json` |
| `/llm.txt` | `text/plain` |
| `/evaluate.json` | `application/json` |
| `/join.json` | `application/json` |
| `/register/` | `text/html` |
Endpoints must be reachable without authentication, cookies, or JavaScript rendering. Spirit Index crawls them with a headless HTTP client. If your domain uses a CDN or edge network, make sure these paths are not blocked by bot protection rules.