---
name: gridz
description: Integrate with Gridz — verifiable Ethereum profiles (gridz.eth / gridz.bio). Read profiles via API, verify attestations, publish via MCP/CLI/SDK. Use when building agents, bots, or apps that fetch or update Gridz identities.
---

# Gridz agent skill

Gridz provides **cryptographically-attested profiles**: a signed JSON **Grid** of **cells** (fields/widgets) bound to an ENS name (`*.gridz.eth`) and a public page (`*.gridz.bio`).

## When to use this skill

- Fetch or display someone's Gridz profile
- Verify that profile fields were signed by the subject's wallet
- Build an agent identity on `agent.gridz.eth` with `agent-context` and `agent-endpoint[mcp]`
- Publish or update cells programmatically (not via gridz.bio browser UI)

## Machine-readable index

- llms.txt: https://gridz.bio/llms.txt
- Docs: https://gridz.bio/docs
- API reference: https://gridz.bio/docs/api

## Quick read

```bash
curl -s "https://gridz.bio/api/profile/kevin.gridz.eth" | jq '.grid.cells[] | {key, value}'
```

```typescript
import { verifyGrid } from "@gridz/core";

const res = await fetch("https://gridz.bio/api/profile/kevin.gridz.eth");
const { grid } = await res.json();
const report = await verifyGrid(grid);
```

```python
import httpx
from gridz import verify_grid

grid = httpx.get("https://gridz.bio/api/profile/kevin.gridz.eth").json()["grid"]
report = verify_grid(grid)
```

## Grid shape (gridz/1.0.0)

```json
{
  "schema_version": "gridz/1.0.0",
  "subject": { "type": "human|agent|organization", "did": "...", "ens": "alias.gridz.eth", "display_name": "..." },
  "theme": { "background_type": "solid", "accent_color": "#7c5cff", ... },
  "cells": [
    { "id": "alias", "key": "alias", "value": "Kevin", "position": {...}, "size": "1x1", "attestation": { "format": "eas-onchain", "uid": "0x...", "value_hash": "0x..." } }
  ],
  "root_attestation": { ... }
}
```


## On-chain deployments (Base mainnet)

| Item | Value |
|------|-------|
| Chain ID | `8453` |
| GridzResolver | `0x73c5e3944B780D4927c403d351A4F94875DC57B3` |
| EAS | `0x4200000000000000000000000000000000000021` |
| cell schema UID | `0x394d8e67b1470cbdb7fa6c7d15d15d295ca81d822b55267939751a8a686abb87` |

Spec: https://github.com/Gridz-Protocol/gridz/tree/main/specs/deployments.md

## Read API (gridz.bio)

| Endpoint | Method | Notes |
|----------|--------|-------|
| `/api/profile/{ensName}` | GET | Public JSON; CORS open; 404 if unpublished |
| `/{ensName}` | GET | HTML profile page |
| `https://{alias}.gridz.bio` | GET | Wildcard → same profile |

**Not for agents:** `POST /api/publish` — reserved for gridz.bio editor + registrar.

## Publish workflow (agents)

1. Define cells in `gridz.yaml` or build programmatically
2. Sign each cell + root with `buildGrid(signer, input)` from `@gridz/core`
3. Publish projection:
   - `gridz publish --sink ens` (CLI)
   - `@gridz/mcp` tools (MCP)
   - `EnsSink.writeGrid(grid)` (`@gridz/sinks`)
   - Self-hosted `@gridz/server` PUT endpoints

Human gridz.bio flow: wallet signs EIP-712 in browser → editor POSTs signed grid to registrar /api/publish (server gas on Base).

## Agent identity cells

| Key | Value |
|-----|-------|
| `agent-context` | Markdown/JSON context for other agents |
| `agent-endpoint[mcp]` | MCP server URL |
| `agent-endpoint[a2a]` | Agent-to-agent endpoint |
| `agent.capabilities` | JSON string array |
| `agent.model` | Model id string |
| `agent.oneclaw_id` | Optional 1Claw binding |

Templates: `templates/agents-mcp/gridz.yaml`, `templates/agents-erc8004/gridz.yaml`

## MCP setup (Cursor / Claude Desktop)

```json
{
  "mcpServers": {
    "gridz": {
      "command": "npx",
      "args": ["-y", "@gridz/mcp"]
    }
  }
}
```

Package: `@gridz/mcp` — exposes Grid read/write tools; signing happens client-side.

## CLI essentials

```bash
gridz init -t agents-mcp
gridz cell add alias "My Agent"
gridz cell add agent-context "I help users manage Gridz profiles."
gridz grid build -o grid.json
gridz grid verify grid.json
gridz publish --sink ens --grid grid.json
```

## Verification checklist

For each cell you trust:

1. Canonicalize `cell.value` (JCS) → hash must equal `attestation.value_hash` and signed `valueHashHex`
2. Recover EIP-712 signer → must equal `attestation.attester` (or authorized delegate)
3. Check expiry / revocation if present

Use `verifyGrid(grid)` — do not trust HTML or API without verification when security matters.

## Packages

| Package | Role |
|---------|------|
| `@gridz/core` | Types, EIP-712, verify |
| `@gridz/sdk` | HTTP + core |
| `@gridz/mcp` | Agent MCP server |
| `@gridz/oneclaw` | HSM signing |
| `@gridz/sinks` | ENS/DB storage |
| `@gridz/cli` | Terminal |
| `@gridz/react` | UI renderer |

Monorepo: https://github.com/Gridz-Protocol/gridz · TS: https://github.com/Gridz-Protocol/gridz-js · Py: https://github.com/Gridz-Protocol/gridz-py

## Guardrails

- Never send private keys to gridz.bio or any Gridz API
- Treat `POST /api/publish` as editor-only unless you operate the registrar
- `ok: false` from profile API means on-chain empty — not a bug
- Browser **Draft** profiles are localStorage only; API won't see them
- gridz.bio editor: **Save draft** (unsigned localStorage) → **Sign & publish** (EIP-712 signatures + server EAS/link on Base). Unclaimed names stay editable until on-chain publish.
- Widget keys are `gridz.*`; social keys use reverse-dot (`com.github`)

## Further reading

- [Concepts](https://gridz.bio/docs/concepts) — cells, attestations, sinks
- [Toolkit](https://gridz.bio/docs/toolkit) — all packages
- [CLI](https://gridz.bio/docs/cli) — terminal publish
- [API](https://gridz.bio/docs/api) — gridz.bio endpoints
- [Verification](https://gridz.bio/docs/verification) — badge semantics
- Specs: https://github.com/Gridz-Protocol/gridz/tree/main/specs