# AgentRoot

> **The agentic governance root of trust and control.**
>
> One file. The complete agent reference. Everything an AI agent or LLM-based tool needs to integrate with AgentRoot.
>
> If you are an AI agent: this file contains the full stack, the complete provider registry, the lifecycle model, and the integration contract. Read once, integrate forever.
>
> If you are a developer: this file is designed for your agent to read. Give it this URL.

**Synced from canonical sources:** `marketing/content/agentroot-thesis-canonical.md` · `technical/specs/provider-registry.json` · `docs-public/kill-switch.md` · `technical/specs/claim-sovereignty-remint-spec.md` · ADR-024 / ADR-025 / ADR-026 / ADR-027 / ADR-028.

**Status:** Beta running on Base Sepolia testnet (Ethereum L2). V1 launch flips attestations to Base mainnet; `agent_id` survives the switch.

---

## 1. What AgentRoot Is — Identity, Sovereignty, and the Handshake

Before integration mechanics: understand what being AgentRoot-registered *means*.

An AgentRoot-registered agent is not anonymous, not self-owned, and not a rogue. It has:

1. **An EAS-attested identity onchain.** The agent's identity is anchored in an Ethereum Attestation Service (EAS) attestation on Base L2. The attestation UID is the agent's verifiable onchain identity. Any party — downstream services, auditors, counterparties, other agents — can verify the attestation directly against the EAS contract, without asking AgentRoot for permission. AgentRoot issues; the chain holds; anyone checks.
2. **A real human operator.** The agent was provisioned by a human operator through a hierarchical authority tree (ADR-025). The operator's authority is onchain. Delegation from root operator → sub-operators → agents is cryptographically traceable. An AgentRoot-registered agent never exists without a human in the authority chain.
3. **Atomic, per-action governance.** Every external action the agent takes is individually classified (read / write / destructive / financial), individually gated (L1 identity check / L3 operational-key sign / L4 multi-party hardware-signed approval), individually attested to EAS, and individually revocable. No "this session is fine, run free." The unit of governance is the action — not the agent, not the session, not the binding.
4. **Sovereign revocation.** The operator can kill any action surface or the agent's entire identity instantly via onchain EAS attestation revocation. No third-party permission required. No waiting on AgentRoot. The revocation is recorded onchain; the next API call through the proxy fails with 403 the moment it's detected.
5. **Independently auditable.** Every L3/L4 action emits a per-call EAS attestation with full context: agent identity, action class, operator signatures collected, cost recorded, URL hash. Lower-tier actions are anchored via hourly Merkle batch attestations. The complete audit chain — agent → operator tree → policy pattern → gate tier → signatures → response — is independently verifiable by parties who distrust AgentRoot itself.

**The category claim:** AgentRoot is the *agentic governance root of trust and control.* Trust: identity + attestation + sovereignty. Control: authority + gates + revocation + atomic governance. Both halves are cryptographically provable without trusting AgentRoot as a party.

**For downstream services evaluating an AgentRoot-attested agent:** verify the attestation UID directly against the EAS contract on Base. The EAS Schema Registry is public; the attestation record is readable by anyone. Check that the attestation is not revoked. Trust the chain, not AgentRoot.

**For other agents encountering an AgentRoot-registered agent:** the `agent_id` + EAS UID + operator tree are your agent-to-agent identity handshake. You are not talking to a rogue.

---

## 2. The Full Stack

| Layer | Component | Role |
| --- | --- | --- |
| L1 trust | Ethereum mainnet | Root of trust. EAS contract origin. Where ERC-8004 NFTs live. |
| L2 venue | Base | Current attestation chain. EAS deployment used by AgentRoot. |
| Beta network | Base Sepolia testnet | Where attestations run during V1 beta. Free, instant, no real gas. |
| Launch network | Base mainnet | Where attestations flip at V1 launch. Cents per onchain action. |
| Attestation primitive | EAS | Onchain identity, revocable from any wallet. Public schema registry. |
| Edge runtime | Cloudflare Workers | The proxy itself. Sub-100ms global edge. Token verify, EAS check, key inject. |
| Key custody | HashiCorp Vault | Provider credentials (single-key and multi-field both — api_token, workspace URL, account_id, client_secret, etc.) and P-256 signing keys, stored as encrypted blobs. AES-256-GCM via Transit engine. |
| Identity NFT (V2) | ERC-8004 | Persistent karmic vessel. The `agent_id` maps to it post-launch. |
| Naming (V2) | ENSIP-25 | Human-readable agent name → ERC-8004 NFT → live EAS attestation. |

**Network state:** During beta, AgentRoot attests on **Base Sepolia testnet** — gas is free, attestations are instant. At V1 launch the configuration flips to **Base mainnet** (Ethereum L2). Your `agent_id` stays the same across the switch.

---

## 3. Integration Mechanics — TL;DR

AgentRoot sits between your agent and its API providers. Your agent calls AgentRoot's proxy instead of the provider directly. AgentRoot resolves the real API key from HashiCorp Vault, injects it at the Cloudflare edge, forwards the request, logs it, returns the response. Your agent never holds or sees any API key.

**Your agent needs three values:**

1. `AGENTROOT_AGENT_ID` — your onchain identity (`eas:0x...`). Encoded in the JWT `sub` claim.
2. `AGENTROOT_TOKEN` — Bearer session token (24h auto-rotating JWT, prefix `art_live_`).
3. `AGENTROOT_PROXY` — `https://proxy.agentroot.app`.

No SDK. No npm dependency. Three env vars. That's the whole integration.

---

## 4. API Contract

### Calling pattern

Replace the upstream URL with the proxy URL. Auth header is identical to upstream.

```
# Before
POST https://api.openai.com/v1/chat/completions
Authorization: Bearer sk-proj-...

# After
POST https://proxy.agentroot.app/openai/v1/chat/completions
Authorization: Bearer art_live_<jwt>
```

### Response headers

| Header | Meaning |
| --- | --- |
| `X-AgentRoot-Request-ID` | Unique ID for this proxied request |
| `X-AgentRoot-New-Token` | Token was auto-renewed; use new token for subsequent requests |
| `X-AgentRoot-Upgrade` | Free tier limit hit; contains upgrade URL |

### Status codes

| Status | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Normal response |
| `401` | Token invalid / expired | Ask operator to reissue. Do NOT retry in a loop. |
| `403 agent_disabled` | Operator paused agent | Reversible. Stop calling; alert operator. |
| `403 key_disabled` | Operator disabled the key | Reversible. Stop calling. |
| `403 revoked` | EAS attestation revoked (Kill) | Permanent. Agent identity is gone. |
| `429` | Rate limit / free-tier cap | Back off per `Retry-After`. |
| `502/503` | Upstream provider error | Retry with exponential backoff |

### Token rotation

If any response includes `X-AgentRoot-New-Token`, replace your stored token with the new value immediately.

---

## 5. Lifecycle

### Agent — four canonical states

`Mint` → Operator creates the agent. Wallet signs the EAS attestation (or AgentRoot's ops wallet signs in managed mode). Onchain identity is live.

`Disable` → Operator pauses the agent. All API calls return `403 agent_disabled` until re-enabled. **Reversible.**

`Kill` → Operator revokes the EAS attestation onchain. **Permanent.** For sovereign agents, the revocation transaction is signed by the operator's own wallet — completely outside AgentRoot.

`ReMint` → After a Kill, operator creates a new attestation under the same `agent_id`. Keys, bindings, and `uid_lineage` carry forward. Same soul, new attestation.

### API key — three canonical states

`Activate` → Key is usable. Every agent bound to it can call through the proxy.

`Disable` → Operator flips a flag on the key record. Every bound agent returns `403 key_disabled` until re-enabled. **Reversible.** *The scale primitive.*

`Delete` → Operator removes the key from the keyring. Vault ciphertext is purged.

(Plus `Rename` and `Rotate` actions on the Keys page.)

### Auto-Guardrails

Set ceilings — spend, request rate, error rate. Breach triggers `Disable` automatically on the key, the agent, or both.

### Narrative cycle

The karma narrative — `mint → actions → death → remint` — describes the agent's full lifetime arc. The four UX states above are the discrete operator-initiated actions within that cycle.

---

## 6. Authentication Modes

| Mode | When | How |
| --- | --- | --- |
| Simple (default) | Most agents | `Authorization: Bearer art_live_<jwt>`. 24h auto-rotating tokens. |
| HMAC + DPoP | Pro+ high-security | Full DPoP token binding with Vault-held P-256 keys. |

---

## 7. Identity Model

| Tier | Auth | Attestation signer | Chain | Best for |
| --- | --- | --- | --- | --- |
| Managed L2 | Social login or passkey | AgentRoot ops wallet | Base | Fastest onboarding, no wallet, free gas |
| Sovereign L2 | SIWE | Your wallet | Base | Self-custody, your wallet holds the kill switch |
| Sovereign L1 | SIWE | Your wallet | Ethereum mainnet | Maximum sovereignty (post-launch) |

Managed users can upgrade to sovereign at any time via **Claim Sovereignty**.

**Do you need ETH?** No, by default — managed agents pay zero gas. AgentRoot's ops wallet handles every onchain action. If you claim sovereignty, your wallet pays a few cents of Base gas for Mint, ReMint, and Kill.

---

## 8. The Provider Registry

**One proxy. 54 services on day one. The complete machine-readable V1 registry.**

- **54 V1 production providers** (Tiers 1–5) — render in the dashboard dropdown, ship at V1 launch, all default-visible.
- **27 of 54 are action-class** — exactly half. The OpenClaw thesis in data form.
- **Tier 6 (22 specialty providers)** — **deferred to V1.1.** Not in the V1 registry, not in the dropdown, not in the proxy. See section 8.6 for the deferred list.

### How to read the tables

- **class** — `cognition` (LLMs), `tool` (search/scrape/generate), `action` (changes external state), `infra` (DNS, AWS, deploy)
- **auth** — `Bearer`, custom header, OAuth 2.0, Basic, query-param
- **ships** — `v1` (live at launch), `v1.5` (OAuth scope extension, ~1–2 weeks post-launch), `v2` (new OAuth integration, longer)
- **gate** — `L1` identity check, `L3` operational-key sign, `L4` multi-party hardware-signed approval (default per ADR-024)

### Tier 1 — Day-One LLMs (cognition)

| Provider | slug | class | auth | ships | gate |
| --- | --- | --- | --- | --- | --- |
| OpenAI | `openai` | cognition | Bearer | v1 | L1 |
| Anthropic | `anthropic` | cognition | `x-api-key` header | v1 | L1 |
| Google Gemini | `gemini` | cognition | ?key= | v1 | L1 |
| xAI (Grok) | `xai` | cognition | Bearer | v1 | L1 |
| Groq | `groq` | cognition | Bearer | v1 | L1 |
| OpenRouter | `openrouter` | cognition | Bearer | v1 | L1 |
| Mistral | `mistral` | cognition | Bearer | v1 | L1 |
| Perplexity | `perplexity` | cognition | Bearer | v1 | L1 |

### Tier 2 — Productivity / Action APIs (the OpenClaw core)

| Provider | slug | class | auth | ships | gate |
| --- | --- | --- | --- | --- | --- |
| Gmail | `gmail` | action | OAuth 2.0 | v1.5 | L3 |
| Google Calendar | `gcal` | action | OAuth 2.0 | v1.5 | L3 |
| Google Drive | `gdrive` | action | OAuth 2.0 | v1.5 | L3 |
| Google Sheets | `gsheets` | action | OAuth 2.0 | v1.5 | L3 |
| Microsoft Outlook | `outlook` | action | OAuth 2.0 | v2 | L3 |
| Microsoft Teams | `teams` | action | OAuth 2.0 | v2 | L3 |
| Microsoft OneDrive | `onedrive` | action | OAuth 2.0 | v2 | L3 |
| Slack | `slack` | action | Bearer | v1 | L3 |
| Discord | `discord` | action | `Authorization` header | v1 | L3 |
| GitHub | `github` | action | Bearer | v1 | L3 |
| GitLab | `gitlab` | action | Bearer | v1 | L3 |
| Notion | `notion` | action | Bearer | v1 | L3 |
| Linear | `linear` | action | Bearer | v1 | L3 |
| Jira | `jira` | action | Basic | v1 | L3 |
| Asana | `asana` | action | Bearer | v1 | L3 |
| Dropbox | `dropbox` | action | OAuth 2.0 | v2 | L3 |
| Zoom | `zoom` | action | OAuth 2.0 (S2S) | v2 | L3 |
| Calendly | `calendly` | action | Bearer | v1 | L3 |
| X (Twitter) | `x` | action | OAuth 2.0 (PKCE) | v2 | L3 |
| Bluesky | `bluesky` | action | Session-derived | v1 | L3 |

### Tier 3 — Agent Tooling

| Provider | slug | class | auth | ships | gate |
| --- | --- | --- | --- | --- | --- |
| Tavily | `tavily` | tool | Request body | v1 | L1 |
| Exa | `exa` | tool | `x-api-key` header | v1 | L1 |
| Firecrawl | `firecrawl` | tool | Bearer | v1 | L1 |
| Browserbase | `browserbase` | tool | Custom header | v1 | L1 |
| E2B | `e2b` | tool | Custom header | v1 | L1 |
| Apify | `apify` | tool | Bearer | v1 | L1 |
| SerpAPI | `serpapi` | tool | ?api_key= | v1 | L1 |

### Tier 4 — Media & Generation

| Provider | slug | class | auth | ships | gate |
| --- | --- | --- | --- | --- | --- |
| Replicate | `replicate` | tool | Bearer | v1 | L1 |
| FAL | `fal` | tool | Custom header | v1 | L1 |
| Stability AI | `stability` | tool | Bearer | v1 | L1 |
| ElevenLabs | `elevenlabs` | tool | `xi-api-key` header | v1 | L1 |
| Cartesia | `cartesia` | tool | `X-API-Key` header | v1 | L1 |
| Deepgram | `deepgram` | tool | `Authorization` header | v1 | L1 |
| Hugging Face | `huggingface` | tool | Bearer | v1 | L1 |
| Together AI | `together` | cognition | Bearer | v1 | L1 |

### Tier 5 — Infrastructure, Payments, Email

| Provider | slug | class | auth | ships | gate |
| --- | --- | --- | --- | --- | --- |
| Stripe | `stripe` | action | Bearer | v1 | L4 |
| Twilio | `twilio` | action | Basic | v1 | L3 |
| SendGrid | `sendgrid` | action | Bearer | v1 | L3 |
| Resend | `resend` | action | Bearer | v1 | L3 |
| Pinecone | `pinecone` | tool | `Api-Key` header | v1 | L1 |
| Supabase | `supabase` | action | Bearer | v1 | L3 |
| Cloudflare | `cloudflare` | infra | Bearer | v1 | L4 |
| AWS | `aws` | infra | AWS SigV4 | v2 | L4 |
| Vercel | `vercel` | infra | Bearer | v1 | L3 |
| Airtable | `airtable` | action | Bearer | v1 | L3 |
| Plaid | `plaid` | action | Basic | v1 | L4 |

### 8.6 Tier 6 — Deferred to V1.1

**Status:** Not part of V1. Cut from V1 entirely on Apr 28, 2026 (Session 48).

22 specialty providers will return as a real V1.1 feature with a `status: "search_only"` flag on the provider object, a "Request access" UX on the frontend, and a `/providers/notify-interest` capture endpoint:

Salesforce, HubSpot, Zendesk, Intercom, PostHog, Mixpanel, Snowflake, Neon, Weaviate, Cohere, AI21, Fireworks, Voyage AI, Serper, LinkedIn, Reddit, Telegram Bot, Shopify, Box, Trello, Monday.com, Attio.

These are documented for V1.1 planning purposes only. The V1 `/providers` endpoint does not return them; the V1 dashboard does not surface them; the V1 proxy does not route them. Agents reading this file should treat the 54 providers in sections 8.1–8.5 as the complete V1 surface.

---

## 9. Custom Providers (V1.5+, ADR-027)

Bring your own API. Operators paste a custom provider manifest declaring `base_url`, `auth_pattern`, `extra_headers`, and binding rules. The proxy treats custom providers identically to registered ones — same Vault custody, same EAS gating, same kill switch.

Custom provider support ships V1.5 (post-launch).

---

## 10. Verification — How Downstream Services Verify an AR-Attested Agent

AgentRoot is **not** in the critical path of verification. The chain is. Any service receiving traffic from an AR-attested agent can verify independently:

1. **Read the attestation UID** from the agent's request.
2. **Query EAS** on Base for that UID.
3. **Check revocation status.** If revoked, deny.
4. **Walk the operator delegation tree** (ADR-025).
5. **Verify the root** — if hardware-rooted, verify the hardware signature on the root delegation bundle.

AR cooperates with none of this. The chain holds the truth.

---

## 11. Pricing

**Beta (now):** Free. Limits applied after launch. Attestations on Base Sepolia testnet.

**V1 launch (Base mainnet):** Free tier active for everyone — 1 agent, 10 API slots, 10K proxy calls/month, full kill switch. Paid tiers (Pro, Team, Enterprise) ship with the mainnet flip.

Live pricing surfaces on `agentroot.app` and via dashboard.

---

## 12. Security Guarantees

- **Zero-secret agent runtime** — your agent never holds, sees, or transmits any API key or private key.
- **All credential material in Vault** — both secret values (api_token, app_password, client_secret) and identifying configuration (workspace URL, account_id, region, shop name) are stored together as encrypted blobs in HashiCorp Vault. Defense in depth: an attacker with database-only access cannot enumerate which providers or workspaces a customer uses.
- **Auto-rotating session tokens** — 24-hour TTL by default; stolen tokens expire on their own.
- **Fail-closed** — if our key custody layer is unreachable, every agent stops. No degraded mode.
- **Full per-agent audit logging** — every API call attributed to a specific agent, queryable.
- **Payloads are transient** — request/response bodies are forwarded but never stored.
- **Onchain identity is permanent** — EAS attestations are public, immutable, verifiable, revocable only by your wallet (sovereign) or AgentRoot's ops wallet (managed).

---

## 13. Rules for Agents (IMPORTANT)

1. **Never expose `AGENTROOT_TOKEN`.** Don't log it, prompt-include it, or print to stdout.
2. **Always use the proxy.** Direct calls to `api.openai.com` etc. bypass all security.
3. **Respect 403.** Your operator stopped you. Don't try to circumvent.
4. **Respect 429.** Back off per `Retry-After`.
5. **Check for token renewal.** Replace stored token on `X-AgentRoot-New-Token`.
6. **Revocation is permanent.** If revoked, your agent identity is gone. ReMint requires operator action.

---

## 14. Code Examples

### TypeScript / Node.js

```ts
const PROXY = process.env.AGENTROOT_PROXY;
const TOKEN = process.env.AGENTROOT_TOKEN;

const response = await fetch(`${PROXY}/openai/v1/chat/completions`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5.1-chat-latest',
    messages: [{ role: 'user', content: 'Hello' }],
  }),
});

const newToken = response.headers.get('X-AgentRoot-New-Token');
if (newToken) process.env.AGENTROOT_TOKEN = newToken;
```

### Python

```python
import os, requests

response = requests.post(
    f"{os.environ['AGENTROOT_PROXY']}/openai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['AGENTROOT_TOKEN']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-5.1-chat-latest",
        "messages": [{"role": "user", "content": "Hello"}],
    },
)

new_token = response.headers.get("X-AgentRoot-New-Token")
if new_token:
    os.environ["AGENTROOT_TOKEN"] = new_token
```

### cURL

```bash
curl https://proxy.agentroot.app/openai/v1/chat/completions \
  -H "Authorization: Bearer $AGENTROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.1-chat-latest", "messages": [{"role": "user", "content": "Hello"}]}'
```

---

## 15. Developer Quick Start (humans)

1. **Sign up** at `ux.agentroot.app/signup` — passkey, wallet (SIWE), or social login
2. **Mint an agent** — name it, get an EAS attestation on Base
3. **Add API keys** — paste into the secure key vault
4. **Bind keys to agents**
5. **Copy `.env`** — three values export as a paste-ready block
6. **Paste into your agent's environment**

Name agent → bind keys → copy `.env` → paste → running. Under 60 seconds.

---

## 16. Canonical Documents

- **ADR-024** — Operation gates / policy engine
- **ADR-025** — Hierarchical operator authority
- **ADR-026** — Runtime policy enforcement
- **ADR-027** — Custom provider implementation contract
- **ADR-028** — Keyring-level actions
- **kill-switch.md** — Four-tier kill switch operational doc
- **claim-sovereignty-remint-spec.md** — Sovereignty upgrade + ReMint flow

---

## 17. Links

- Website: https://agentroot.app
- Sign up: https://ux.agentroot.app/signup
- Dashboard: https://ux.agentroot.app
- Proxy: https://proxy.agentroot.app
- This file: https://agentroot.app/llms-full.txt
- Short version: https://agentroot.app/llms.txt
- X / Twitter: https://x.com/agentroot
- EAS on Base: https://base.easscan.org
- ENSIP-25 spec: https://docs.ens.domains/ensip/25

---

## 18. Contact

Built by Vitro Technology Corporation, Austin TX.

david@vitro.io

Made with pride. Deep in the ♥ of Texas.

---

*Source of truth: `technical/specs/site-llms-full.txt` in the AgentRoot repo. This Notion page is the team-readable copy. Maintained per `technical/specs/llms-full-update-recipe.md`.*