# zeroknowledge.family API (https://api.zeroknowledge.family)
Private balances on Robinhood Chain (chain id 4663). One shared shielded pool at 0x12402177B68F8278EB20424569982aCCA988eAAD: notes are
Poseidon commitments in a Merkle tree of 20 levels, every action is a Groth16 join-split proof made on your side.
Tokens: ETH (as WETH), CASH, ZCAT, AI, MEME, INU, ROBIN, KERMIT, MOON. Amounts are in note units (1 token = 1e9).

## How it works
- Keys: sign a fixed message, derive keys on your device (keysFromSignature). Your zk address (zk1...) = owner key + encryption key.
- Shield: buildDeposit, approve the token to the pool, send transact() from your wallet. 0.25% fee as a private note.
- Private send: buildSend to a zk1 address. Amount, sender and receiver are hidden. No fee.
- Unshield: buildWithdraw to any 0x address. 0.25% fee as a private note. The relayer is off for now, so you send it
  from a wallet; use a different wallet than the one you shielded from.
- Your balance: GET /commitments + /nullifiers, then scan(keys, commitments, nullifiers) locally.

## Routes
GET /health: ok, database, latest block, worker heartbeat age, relayer live
GET /config: chain, pool address, tokens, fees, our fee zk address, relayer, circuit files
GET /pools: one row per token: crowd (notes in the tree), shielded (amount in the pool now), in24, out24, sends24, best hour, price, maxDeposit
GET /pools/{token}: one token + history (30 daily crowd sizes), heat (24 UTC hours, 0..1), activity (as the chain sees it)
GET /commitments: every leaf of the shared tree in index order with its token and encrypted output (?from=). Scan them with your viewing key on your side
GET /nullifiers: every spent nullifier
GET /relay/quote: relayer fee for a token (?token=0x...), note units; live:false while the relayer is off
POST /relay: {args, ext}: a finished transact() from the SDK; the relayer checks the proof and posts it (off for now: 503)
GET /relay/{id}: a relay job
GET /advice: coded timing advice: ?token=ETH&amount=0.1
GET /stats: notes in the tree, shields, USD shielded now, recent activity (no addresses)
GET /contracts: the pool, its verifiers and the allowed tokens
GET /events: SSE: shield, send, unshield
GET /sdk/pool.mjs: the SDK (ES module; needs poseidon-lite, @noble/*, viem, snarkjs): keysFromSignature, encodeAddress, scan, buildDeposit, buildWithdraw, buildSend
POST /mcp: MCP (streamable HTTP, JSON): list_pools, get_pool, timing_advice, relay_quote, relay, get_contracts
GET /llms.txt: this text
GET /openapi.json: OpenAPI 3.1

## MCP
POST https://api.zeroknowledge.family/mcp  tools: list_pools, get_pool, timing_advice, relay_quote, relay, get_contracts