@zevtrust/node

Official Node.js SDK for the Zevtrust REST API. Provides typed methods for transaction intelligence, identity screening, watchlist checks, event ingestion, and fraud case submission.

Requires Node.js 20+. Zero runtime dependencies.

Installation

npm install @zevtrust/node

Quick start

import { ZevtrustClient } from '@zevtrust/node';

const client = new ZevtrustClient({
  consumerKey: process.env.ZEVTRUST_CONSUMER_KEY!,
  consumerSecret: process.env.ZEVTRUST_CONSUMER_SECRET!,
  signingSecret: process.env.ZEVTRUST_SIGNING_SECRET!,
});

The client automatically manages OAuth tokens (caching, refresh) and HMAC-signs requests to endpoints that require it.

Usage

Transaction intelligence

const result = await client.checkExternalTransfer({
  entity_hash: '<sha256 of your user/wallet ID>',
  entity_type: 'wallet',
  counterparty_hash: '<sha256 of counterparty>',
  amount: 50000,
  direction: 'outbound',
});

console.log(result.recommendation); // "allow" | "review" | "block"
console.log(result.risk_score);     // 0-100

Identity screening

const screen = await client.screenIdentity({
  screening_type: 'signup',
  bvn: '12345678901',
  email: '[email protected]',
});

console.log(screen.recommendation);
console.log(screen.matched_watchlist_entries);

Watchlist check

const check = await client.watchlistCheck({ bvn: '12345678901' });

if (check.match) {
  console.log(check.risk_level); // "block" | "flag" | "monitor"
}

Event ingestion

// Single event
const event = await client.ingestEvent({
  event_type: 'transfer_completed',
  entity_type: 'wallet',
  entity_hash: '<sha256>',
});

// Batch (up to 1000)
const batch = await client.ingestEventBatch({
  events: [
    { event_type: 'transfer_completed', entity_type: 'wallet', entity_hash: '<sha256>' },
    // ...
  ],
});

Fraud case submission

const fraudCase = await client.submitFraudCase({
  identifier_type: 'bvn',
  identifier_value: '12345678901',
  risk_level: 'block',
  reason: 'Confirmed money mule.',
});

console.log(fraudCase.watchlist_entry_id);

Webhook verification

Verify inbound webhooks from Zevtrust using the static helper:

import { ZevtrustWebhooks } from '@zevtrust/node';

const isValid = ZevtrustWebhooks.verifySignature({
  rawBody: req.rawBody,                              // string or Buffer
  timestamp: req.headers['x-zevtrust-timestamp'],
  signature: req.headers['x-zevtrust-signature'],
  secret: process.env.ZEVTRUST_WEBHOOK_SECRET!,
  tolerance: 300, // optional, seconds (default 300)
});

if (!isValid) {
  return res.status(403).json({ error: 'Invalid signature' });
}

Error handling

All API errors throw ZevtrustApiError:

import { ZevtrustApiError } from '@zevtrust/node';

try {
  await client.watchlistCheck({ bvn: '000' });
} catch (err) {
  if (err instanceof ZevtrustApiError) {
    console.error(err.error);     // machine-readable code
    console.error(err.message);   // human-readable message
    console.error(err.status);    // HTTP status
    console.error(err.requestId); // for support
  }
}

Configuration

| Option | Required | Default | | ---------------- | -------- | ----------------------------- | | consumerKey | Yes | -- | | consumerSecret | Yes | -- | | signingSecret | Yes | -- | | baseUrl | No | https://api.zevtrust.com |

Documentation

Full API reference: docs.zevtrust.com

License

MIT