agentbits

Read-only explainability for Taiko + AI agents on a Type-1 EVM.

Paste a transaction hash or Uniswap v4 hook address → get a human summary, stable JSON, and a compact agentSummary string for MCP / LLM tools. Complements official taiko-ai (balances, bridge, explorer MCP) without replacing it.

Live demo: deploy to Vercel (see below) · Repo: github.com/panagot/Agentbits

---

Table of contents

• What it does
• Who it is for
• Quick start
• Web UI
• Deep links
• HTTP API
• MCP server
• Environment variables
• Deploy on Vercel
• Project structure
• Scripts
• Taiko grant fit
• What it is not
• License & disclaimer

---

What it does

Flow	Route	Behavior
Tx inspector	/	Decode Taiko mainnet (167000) or Hoodi (167013) txs via JSON-RPC
Hook decoder	/hooks	Decode Uniswap v4 hook permission bits (lowest 14 bits of address)
REST API	/api/decode, /api/hook, /api/health	Machine-readable JSON for agents
Demo mode	?demo=1 or Demo fixture button	Offline deterministic sample (source: fixture)

Every successful decode includes:

• humanSummary — plain English for people
• agentSummary — compact key=value string for agents
• explorerUrl — Taikoscan / Hoodi explorer link
• source — rpc or fixture (never faked)

---

Who it is for

• Agent builders — Cursor / Claude MCP + stable JSON shapes
• dApp & hook developers — v4 hook bit grid before trusting lifecycle callbacks
• Educators & grant reviewers — honest RPC vs fixture labeling, shareable URLs

More context: in-app /about and /faq pages.

---

Quick start

Requirements: Node.js 20+

git clone https://github.com/panagot/Agentbits.git
cd Agentbits
npm install
cp .env.example .env.local   # optional RPC overrides
npm run dev

Open http://localhost:3004

• Demo fixture — works without RPC (source: fixture)
• Decode live — paste a Taikoscan tx hash (source: rpc)

npm run typecheck
npm run test

---

Web UI

Page	Path
Tx inspector	/
Hook decoder	/hooks
API reference	/api-docs
About	/about
FAQ	/faq

Hook example: 0x0000000000000000000000000000000000000080 → mask 0x0080 → beforeSwap

---

Deep links

Shareable URLs auto-decode on load:

/?hash=0xYOUR_TX_HASH&network=mainnet
/?demo=1&network=mainnet
/hooks?address=0x0000000000000000000000000000000000000080

network is mainnet (default) or hoodi.

---

HTTP API

Full curl examples on /api-docs when the app is running.

Health

curl -s http://localhost:3004/api/health | jq

{ "ok": true, "service": "agentbits", "version": "0.1.0" }

Decode transaction

# Live RPC
curl -sG 'http://localhost:3004/api/decode' \
  --data-urlencode 'hash=0xYOUR_64_HEX_HASH' \
  --data-urlencode 'network=mainnet' | jq

# Offline fixture
curl -sG 'http://localhost:3004/api/decode' \
  --data-urlencode 'hash=0x0' \
  --data-urlencode 'demo=1' \
  --data-urlencode 'network=mainnet' | jq

POST with JSON body: { "hash": "0x…", "network": "mainnet" } or { "demo": true, "network": "mainnet" }.

Decode hook

curl -sG 'http://localhost:3004/api/hook' \
  --data-urlencode 'address=0x0000000000000000000000000000000000000080' | jq

Response contract

• Success: { "ok": true, "agentSummary": "…", "humanSummary": "…", "explorerUrl": "…", … }
• Error: { "ok": false, "error": "…" }

---

MCP server

Stdio MCP for local agents (npm run mcp):

Tool	Description
decode_taiko_tx	hash, optional network, optional demo
decode_v4_hook	Hook deploy address

Cursor (Settings → MCP):

{
  "mcpServers": {
    "agentbits": {
      "command": "npx",
      "args": ["tsx", "./mcp-server/src/index.ts"],
      "cwd": "/absolute/path/to/Agentbits"
    }
  }
}

See mcp-server/README.md, docs/agent-integration.md, and skills/agentbits/SKILL.md.

---

Environment variables

Copy .env.example → .env.local:

Variable	Description
TAIKO_MAINNET_RPC	Override default https://rpc.mainnet.taiko.xyz
TAIKO_HOODI_RPC	Override default https://rpc.hoodi.taiko.xyz
NEXT_PUBLIC_AGENTBITS_REPO	GitHub URL for footer link (e.g. this repo)

---

Deploy on Vercel

1. Push this repo to GitHub (panagot/Agentbits).

2. Import project → select Agentbits.

3. Framework preset: Next.js (auto-detected).

4. Environment variables (Production):

   Name	Value
   NEXT_PUBLIC_AGENTBITS_REPO	https://github.com/panagot/Agentbits
   TAIKO_MAINNET_RPC	(optional) your RPC URL
   TAIKO_HOODI_RPC	(optional)

5. Deploy. The app listens on port 3004 locally; Vercel uses its default HTTPS port automatically (package.json build / start scripts are compatible).

Note: Serverless routes call Taiko JSON-RPC from Vercel edge/server — ensure your RPC allows server-side requests. Demo mode (?demo=1) works without RPC for screenshots.

---

Project structure

app/                 # Next.js App Router (pages + API routes)
components/          # TxInspector, HookDecoder, Header, Footer, …
lib/                 # decode-tx, decode-hook, selectors, flags, taiko RPC
mcp-server/          # Stdio MCP (decode_taiko_tx, decode_v4_hook)
data/                # pinned-txs.json (real mainnet examples)
docs/                # agent-integration.md
skills/agentbits/    # Agent skill for MCP / Cursor
tests/               # Vitest
scripts/             # smoke-test.ps1

---

Scripts

Command	Description
npm run dev	Dev server on port 3004
npm run build	Production build
npm start	Start production server (port 3004)
npm run typecheck	tsc --noEmit
npm run test	Vitest
npm run mcp	Start MCP stdio server

---

Taiko grant fit

Problem: Agents can fetch Taiko data but often mis-explain txs and hook permissions.

Solution: Open-source read-only layer with dual human/agent output, MCP tools, and honest source labeling.

Complements: taiko-ai — not a wallet, swap router, or TaikoProofs ZK dashboard.

---

What it is not

• No wallet, signing, bridging, or custody
• No DEX / swap execution
• No TaikoProofs-style ZK batch UI
• Not a full replacement for taiko-explorer ABI decode — use both

---

License & disclaimer

MIT — see LICENSE.

Not affiliated with Taiko Labs. Complements public taiko-ai repositories.