# Gridz

> Gridz is an open framework for cryptographically-attested profiles on Base.
> Identity: `alias.gridz.eth` · Public page: `https://alias.gridz.bio` · Every cell is wallet-signed (EIP-712) and published via EAS on Base (chain 8453). gridz.bio covers registrar gas; users sign EIP-712 only.

This file is for LLMs, agents, and automated tools. Start here before integrating with Gridz.

## Agent entrypoints

- [For AI hub](https://gridz.bio/for-ai): overview, quickstart, and links to machine-readable files
- [skill.md](https://gridz.bio/skill.md): Cursor / agent skill — workflows, APIs, packages, guardrails
- [Documentation](https://gridz.bio/docs): human-readable guides (claiming, API, CLI, toolkit)
- [Profile read API](https://gridz.bio/docs/api): `GET /api/profile/{ensName}` — JSON Grid, CORS open

## Demo profile (integration test)

- [Demo profile](https://gridz.bio/demo.gridz.eth) — Spritz-style widget showcase at demo.gridz.eth
- Refresh: pnpm demo:publish (requires GRIDZ_SIGNER_KEY + registrar env)
- Verify: pnpm demo:verify


## On-chain (Base mainnet — gridz.bio production)

| Item | Value |
|------|-------|
| Chain ID | `8453` (Base) |
| GridzResolver (proxy) | `0x73c5e3944B780D4927c403d351A4F94875DC57B3` |
| EAS | `0x4200000000000000000000000000000000000021` |
| EAS SchemaRegistry | `0x4200000000000000000000000000000000000020` |
| gridz.cell.v1 schema UID | `0x394d8e67b1470cbdb7fa6c7d15d15d295ca81d822b55267939751a8a686abb87` |
| Registrar (editor publish) | `0xEBE4ceb499Ad95DC1e5662E3a223Ec8cc0a555d9` |
| EAS explorer | https://base.easscan.org |

Full table: [specs/deployments.md](https://github.com/Gridz-Protocol/gridz/tree/main/specs/deployments.md)

## Read a profile (primary integration)

```
GET https://gridz.bio/api/profile/kevin.gridz.eth
```

Response: `{ ok, subject, grid }` where `grid` is schema `gridz/1.0.0` with `subject`, `theme`, `cells[]`, `root_attestation`.

- `404` / `ok: false` = nothing published on-chain yet (browser drafts are not visible via API).
- Render in apps: `@gridz/react`, `@gridz/vue`, or fetch JSON and build your own UI.
- Verify offline: `verifyGrid(grid)` from `@gridz/core` (TypeScript) or `gridz.verify_grid` (Python).

## URLs & naming

| What | Pattern |
|------|---------|
| ENS subject | `{alias}.gridz.eth` |
| Web profile | `https://{alias}.gridz.bio` |
| JSON API | `GET https://gridz.bio/api/profile/{alias}.gridz.eth` |
| Wildcard | `{alias}.gridz.bio` rewrites to the profile page |

## Write / publish (agents)

**Do not** call `POST https://gridz.bio/api/publish` from third-party agents — it is for the gridz.bio editor registrar flow only.

Agents should sign locally, then publish via:

1. **MCP** — `@gridz/mcp` (read/write Grids from Cursor, Claude Desktop, etc.; never signs server-side)
2. **CLI** — `gridz grid build` + `gridz publish --sink ens` (see [CLI docs](https://gridz.bio/docs/cli))
3. **SDK** — `buildGrid()` + `@gridz/sinks` EnsSink or self-hosted `@gridz/server`
4. **1Claw HSM** — `@gridz/oneclaw` for agent identities without browser wallets

Signing requires EIP-712 typed data per cell (`GridzCell`) plus a root (`GridzRoot`). Specs: [eip712-types](https://github.com/Gridz-Protocol/gridz/tree/main/specs/eip712-types.ts), [canonicalization](https://github.com/Gridz-Protocol/gridz/tree/main/specs/canonicalization.md).

## Standard cell keys (common)

| Key | Purpose |
|-----|---------|
| `alias` | Display name |
| `description` | Bio |
| `url` | Website (https) |
| `avatar` | Profile image URL (often IPFS via Pinata; image bytes are off-chain) |
| `com.twitter`, `com.github`, `social.bsky` | Social handles |
| `agent-context` | Free-form context for agents (ENSIP-26) |
| `agent-endpoint[mcp]` | MCP server URL (ENSIP-26) |
| `agent.capabilities`, `agent.model`, `agent.version` | Gridz agent metadata |
| `gridz.stats`, `gridz.poll`, `gridz.social_link`, … | Bento widgets |

Full registry: [standard-keys.md](https://github.com/Gridz-Protocol/gridz/tree/main/specs/standard-keys.md)

## Packages (TypeScript)

| Package | Use when |
|---------|----------|
| `@gridz/core` | Types, signing, `verifyGrid()` |
| `@gridz/sdk` | HTTP client + core helpers |
| `@gridz/mcp` | MCP server for agents |
| `@gridz/oneclaw` | 1Claw HSM signer |
| `@gridz/sinks` | ENS / DB projections |
| `@gridz/cli` | Terminal workflows |
| `@gridz/react` | React renderer |

Details: [Toolkit](https://gridz.bio/docs/toolkit)

## Python

`gridz` (verify/build), `gridz-mcp`, `gridz-oneclaw` — cross-runtime compatible with TypeScript. Repo: [gridz-py](https://github.com/Gridz-Protocol/gridz-py)

## Verification rules

1. Recompute `value_hash` from canonical JSON of each `cell.value`; must match signed `valueHashHex`.
2. Recover signer from EIP-712 payload; must match `attestation.attester`.
3. On gridz.bio, on-chain cells use EAS (`format: eas-onchain`); resolver reads cleartext from attestations.

See [Verification docs](https://gridz.bio/docs/verification)

## Examples in repo

- `examples/next-app` — gridz.bio (this site)
- `examples/minimal-cli` — smallest CLI publish flow
- `examples/scaffold-agent-grid` — agent-oriented bootstrap
- `examples/oneclaw-quickstart` — 1Claw HSM signing
- Templates: `templates/agents-mcp`, `templates/agents-erc8004`

## Optional

- [Find profile](https://gridz.bio/find) — lookup by alias; live suggestions (up to 5 matches) as you type
- [Claim UI](https://gridz.bio/claim) — human wallet flow
- OpenAPI (self-hosted server): `specs/openapi.yaml` in monorepo