HTTP API

JSON responses are stable for agents. Errors always return { "ok": false, "error": "…" }.

GET /api/health

Liveness + version string for monitors.

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

GET /api/decode

Query params: hash (required unless demo), network=mainnet|hoodi, demo=1 (fixture, ignores hash validity checks).

curl -sG 'http://localhost:3004/api/decode' \
  --data-urlencode 'hash=YOUR_TX_HASH' \
  --data-urlencode 'network=mainnet' | jq

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

Sample success body

{
  "ok": true,
  "source": "rpc",
  "network": "mainnet",
  "hash": "0x…",
  "chainId": 167000,
  "type": "0x2",
  "from": "0x…",
  "to": "0x…",
  "valueWei": "0x0",
  "valueEth": "0",
  "gasUsed": "0x5208",
  "status": "success",
  "blockNumber": "0x…",
  "selector": "0xa9059cbb",
  "selectorLabel": "transfer(address,uint256)",
  "inputLength": 138,
  "humanSummary": "…",
  "agentSummary": "status=success; type=0x2; selector=…",
  "explorerUrl": "https://taikoscan.io/tx/0x…",
  "fetchedAt": "2026-05-17T…"
}

POST /api/decode

curl -s 'http://localhost:3004/api/decode' \
  -H 'content-type: application/json' \
  -d '{"hash":"YOUR_TX_HASH","network":"mainnet"}' | jq

curl -s 'http://localhost:3004/api/decode' \
  -H 'content-type: application/json' \
  -d '{"demo":true,"network":"mainnet"}' | jq

GET /api/hook · POST /api/hook

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

Sample decode

{
  "ok": true,
  "address": "0x0000000000000000000000000000000000000080",
  "hexMask": "0x0080",
  "bitString": "00000010000000",
  "activeFlags": ["beforeSwap"],
  "flags": [ … ],
  "agentSummary": "Hook 0x… may implement: beforeSwap. …"
}