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.
Get started
- 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.
- On your Institutions dashboard, open API and webhooks and create a key. It's shown once; store it in your secrets manager.
- 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
| Method | What 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
- Any 2xx response counts as delivered. We don't follow redirects.
- Failures are retried after 1, 5, 30, 120, 360 and 720 minutes, then marked failed. Deliveries appear on your dashboard for 30 days.
- Endpoints must be HTTPS on the public internet. Events can arrive more than once or out of order; use
idto deduplicate.
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/me | Organization, confirmation status, covered answers. |
GET /api/v1/requests?limit=100&before=<ms> | Your requests, newest first. |
GET /api/v1/requests/:id | One request's status and monitoring. |
POST /api/v1/requests | Create a request. The body is encrypted by the SDK. |
POST /api/v1/requests/:id/monitor | Start 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
- API keys act for your organization: keep them server-side, one per system, and revoke any you don't use.
- Requester links and share links contain decryption secrets after
#. Store them like passwords. - The SDK talks only to zhuttr.com (the API and its blockchain relay). Verification runs on your machine.
Get an API key with Zhuttr Institutions
Start free →