walletdna-sdk

Official JavaScript / TypeScript SDK for the WalletDNA API — screen any wallet for sanctions and high‑risk exposure, get a clear allow / review / block decision, and verify signed webhooks.

API access requires an Advanced or Enterprise plan. Create an API key at https://walletdna.com/developer.

Install

npm install walletdna-sdk

Requires Node 18+ (uses the built‑in fetch and node:crypto).

Screen a wallet

import { WalletDNA } from "walletdna-sdk";

const wdna = new WalletDNA(process.env.WALLETDNA_API_KEY);

const verdict = await wdna.screen("0x722122dF12D4e14e13Ac3b6895a86e84145b6967");
console.log(verdict.decision); // "allow" | "review" | "block"

if (verdict.decision === "block") {
  // reject the deposit / withdrawal
}

Custom thresholds & auto‑monitoring

const verdict = await wdna.screen(address, {
  thresholds: { review: 40, block: 75 }, // map riskScore → decision (sanctioned always blocks)
  monitor: true,                          // also watch this wallet and webhook me on changes
});

Batch (up to 25 addresses)

const { results, count } = await wdna.screenBatch([addrA, addrB, addrC]);
const blocked = results.filter((r) => r.decision === "block");

Webhooks

Register an endpoint (the signing secret is returned once — store it):

const { id, secret } = await wdna.createWebhook("https://api.acme.com/walletdna", [
  "wallet.risk_changed",
  "wallet.sanctioned",
]);

Verify incoming events with the raw request body and the WalletDNA-Signature header:

import { verifyWebhook } from "walletdna-sdk";

app.post("/walletdna", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyWebhook(req.body.toString("utf8"), req.get("WalletDNA-Signature"), process.env.WDNA_WEBHOOK_SECRET);
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body.toString("utf8"));
  // event.type, event.data (a screening verdict + previousScore/label/reportUrl)
  res.sendStatus(200);
});

Errors

Failed requests throw WalletDNAError with .status, .code, and .body. A 429 means you've hit your monthly API limit — add credits in the dashboard.

Reference

Full OpenAPI spec: https://walletdna.com/api/openapi · Docs: https://walletdna.com/docs/api