zhuttr
Developers

Zhuttr API, webhooks and SDK

Create proof-of-funds requests from your own systems, get signed webhooks when they're answered or proven funds move, verify answers on the Zcash blockchain with the SDK, and read shares clients open to your software.

Zhuttr is end-to-end encrypted, so its API is a little different: the server never sees amounts, wallets or who your clients are. Your systems hold each request's secret, and the SDK decrypts and verifies answers locally, against the Zcash blockchain, with the same checks the website runs in a browser.

Who it's for. Institutions (lenders, exchanges, OTC desks, auditors) use the API and webhooks with an Institutions plan. Accounting firms use the SDK to read shares a client opened to their software. No plan is needed for that; the client decides.

Get started

  1. Download the SDK (Node.js 22 or later, no dependencies): zhuttr.mjs, zhuttr_disclose_bg.wasm, zhuttr_balance_bg.wasm and the example. Keep the three files together.
  2. On your Institutions dashboard, open API and webhooks and create a key. It's shown once; store it in your secrets manager.
  3. Run the example: ZHUTTR_API_KEY=zk_live_… node example.mjs

Create a request and verify the answer

import { Zhuttr } from "./zhuttr.mjs";
const z = new Zhuttr({ apiKey: process.env.ZHUTTR_API_KEY });

// Ask for at least $25,000 in ZEC (converted at the current price and locked in ZEC), or use minZec.
const req = await z.createRequest({ minUsd: 25000, reference: "Loan 4471", days: 7 });
sendToClient(req.holderLink);          // the client answers here, free under your plan
saveToCaseFile(req.requesterLink);     // secret: it decrypts the answer. Never share it.

// When the request.answered webhook arrives (or on a schedule):
const result = await z.verify(req.requesterLink);
// result.status: "verified" | "waiting" | "short" | "spent" | "stale" | "no-code" | "failed"
// result.kind: "balance" (zero-knowledge proof, funds not moved) or "payment" (coded self-payment)
// result.zec, result.block / result.checkedTo, result.meta.reference …

A verified balance proof is then monitored automatically: you'll get a funds.moved webhook (and an email) if any proven note is spent. Pass { watch: false } to skip that.

SDK reference

MethodWhat it does
new Zhuttr({ apiKey, baseUrl })API key from your dashboard; base URL defaults to https://zhuttr.com.
me()Your organization name, whether Zhuttr has confirmed it, and covered answers used this month.
createRequest({ minZec | minUsd, reference, days })Encrypts and creates a request in your organization's name. Returns holderLink, requesterLink, code, minZec, expiresAt. Days: 1 to 30.
listRequests({ limit, before })Your requests: ids, created, expires, answered, monitoring. (Everything else is encrypted.)
getRequest(requesterLink)Decrypts the request and its answer, without verifying.
verify(requesterLink, { watch })Decrypts and verifies the answer on the blockchain; starts monitoring a verified balance proof.
Zhuttr.verifyWebhook(rawBody, signature, secret)Checks a webhook's signature and age; returns the event or throws.
openShare(shareLink)Reads a share the client opened to software (see below).
Zhuttr.shareFiles(share), Zhuttr.shareFile(share, kind)The files the client allowed, and one file's contents: ledger, 8949, koinly, cointracker, coinledger, txf, taxact, quickbooks, xero.

Webhooks

Add an HTTPS endpoint on your dashboard. We POST JSON:

{ "id": "evt_…", "type": "request.answered", "created": 1790000000000,
  "data": { "requestId": "…", "answeredAt": 1790000000000 } }

{ "id": "evt_…", "type": "funds.moved", "created": …,
  "data": { "requestId": "…", "spentHeight": 3510000 } }

Events carry only what the server knows: the request id, when it was answered, the block at which proven funds moved. Use the SDK to decrypt and verify. webhook.test is sent when you click "Send test event".

Verifying signatures

Each delivery has Zhuttr-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>.<raw body>" with your signing secret. Reject signatures older than five minutes.

app.post("/zhuttr/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const evt = Zhuttr.verifyWebhook(req.body, req.get("zhuttr-signature"), process.env.ZHUTTR_WEBHOOK_SECRET);
  queue.add(evt);       // respond fast; do the verification in a worker
  res.sendStatus(204);
});

Delivery

HTTP API

All endpoints take Authorization: Bearer zk_live_… and return JSON. The SDK wraps them; you only need these directly for listing and status.

Endpoint
GET /api/v1/meOrganization, confirmation status, covered answers.
GET /api/v1/requests?limit=100&before=<ms>Your requests, newest first.
GET /api/v1/requests/:idOne request's status and monitoring.
POST /api/v1/requestsCreate a request. The body is encrypted by the SDK.
POST /api/v1/requests/:id/monitorStart monitoring a verified balance proof (the SDK does this).

Rate limits are generous (hundreds of requests an hour). Errors look like { "error": "…" } with a 4xx status.

Reading shares from your own software

When a client shares a window with "Connect their own software (API)" switched on, your firm's systems can read it while the link is live:

const z = new Zhuttr();
const share = await z.openShare(linkFromClient);       // throws if software access isn't allowed
for (const f of Zhuttr.shareFiles(share)) {
  writeFile(`${share.client}-${share.year}-${f.kind}.${f.ext}`, Zhuttr.shareFile(share, f.kind));
}

You get exactly what the client shared (the same transactions and figures as in the browser) and only the file types they allowed. Access stops when the link ends.

Security notes

Get an API key with Zhuttr Institutions

Start free →