API & integrations

gridz.bio exposes a simple read API for public profiles. For write flows, you sign locally with your wallet (or CLI/SDK) — the server never holds your private key.

gridz.bio Profile API

Read any published profile as JSON. CORS is open; safe to call from browsers and servers.

Get a profile

GET https://gridz.bio/api/profile/{ensName}

# Example
GET https://gridz.bio/api/profile/kevin.gridz.eth

Success response

{
  "ok": true,
  "subject": "kevin.gridz.eth",
  "grid": {
    "schema_version": "gridz/1.0.0",
    "subject": {
      "type": "human",
      "did": "did:ens:kevin.gridz.eth",
      "ens": "kevin.gridz.eth",
      "display_name": "Kevin"
    },
    "theme": { ... },
    "cells": [
      {
        "id": "alias",
        "key": "alias",
        "value": "Kevin",
        "attestation": { "format": "eas-onchain", "uid": "0x...", ... }
      }
    ],
    "root_attestation": { ... }
  },
  "api": {
    "docs": "https://gridz.bio/docs",
    "render": "https://gridz.bio/kevin.gridz.eth"
  }
}

Not found

{
  "ok": false,
  "subject": "kevin.gridz.eth",
  "grid": null,
  "error": "Profile not found"
}

A 404 means nothing is published on-chain for that name yet (a local browser draft does not count).

Publishing via gridz.bio

The claim UI handles publish for you. Under the hood:

Draft locally — Save draft stores unsigned field edits in localStorage (no wallet). Not visible via this API.
You sign — Sign & publish prompts your wallet for only changed cells plus the grid root (EIP-712). Unchanged cells reuse prior attestations.
Server attests — POST /api/publish takes your signed Grid, writes new EAS attestations for changed cells, then calls GridzResolver setCellAttestation directly (one registrar tx per field). Uses a registrar key on the server; you do not sign those transactions.
Public read — this API and profile pages read attestations back from the resolver. Use Query & verify on any profile for fetch + verify instructions.

POST /api/publish is called by the gridz.bio editor, not meant for arbitrary third-party writes. To publish programmatically, use the CLI or @gridz/sdk with your own signer and sink.

On-chain (Base mainnet)

gridz.bio reads and publishes via Base (chain 8453).

Item	Address
GridzResolver (proxy)	`0x73c5e3944B780D4927c403d351A4F94875DC57B3`
EAS	`0x4200000000000000000000000000000000000021`
gridz.cell.v1 schema UID	`0x394d8e67b1470cbdb7fa6c7d15d15d295ca81d822b55267939751a8a686abb87`

Full deployment table: specs/deployments.md.

Reference API server (`@gridz/server`)

The open-source @gridz/server package implements a full Gridz API (Fastify + OpenAPI 3.1). Self-host it if you want your own write/read endpoints — for example behind an agent or internal tool.

Endpoint	What it does
`GET /grids/{subject}`	Fetch a full Grid by ENS name or DID.
`POST /grids/{subject}`	Upsert a Grid — requires a signed root attestation in the body.
`GET /grids/{subject}/cells/{key}`	Fetch one cell.
`PUT /grids/{subject}/cells/{key}`	Upsert one cell — requires a signed cell attestation.
`POST /verify`	Verify a Grid or attestation server-side.

The server validates signatures and never custodies keys. OpenAPI spec: specs/openapi.yaml in the gridz repo.

TypeScript SDK

import { GridzClient, verifyGrid, buildGrid } from "@gridz/sdk";

// Read from any Gridz-compatible API
const client = new GridzClient({ baseUrl: "https://gridz.bio" });
const grid = await client.getGrid("kevin.gridz.eth");

// Verify locally
const report = await verifyGrid(grid);

@gridz/sdk re-exports @gridz/core build/verify helpers so you can sign locally and push with one import. See Toolkit.

Python

from gridz import verify_grid
import httpx

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