@oilflow/sdk

Official Node.js SDK for the OilFlow Network compliance APIs.

• ✅ Regulatory Matrix (235 jurisdictions, product tradability rules)
• ✅ KYC-as-API + UBO graph traversal + Adverse Media (multilingual)
• ✅ Scam Cluster Intelligence Feed
• ✅ Webhooks with HMAC verification helper (raw / Slack Block Kit / Teams Adaptive Card formats)
• ✅ Regulator-ready reports (FATF Rec.10, FinCEN CDD, EU 6AMLD, FCA SYSC 18, MAS 626, OFSI)
• ✅ LC discrepancy detection (UCP 600)
• ✅ Customer watchlist sync
• ✅ Audit export (paginated streaming via for await)

Built-in retry with jittered exponential backoff for 5xx + 429 responses (respects Retry-After). Strict TypeScript types. Works on Node ≥18 and modern browsers via fetch.

Install

npm install @oilflow/sdk

Quick start

import OilFlow from "@oilflow/sdk";

const client = new OilFlow({ apiKey: process.env.OILFLOW_API_KEY });

const result = await client.kyc.screen({
  company_name: "Acme Trading FZE",
  country: "UAE",
  directors: ["Jane Doe"],
});

console.log(result.verdict, result.verdict_reasoning);
// → "pass" or "fail" + reasoning string

Regulatory check

const check = await client.regulatory.check({
  country: "Kenya",
  product: "crude",
  listing_type: "demand",
});

if (!check.allowed) {
  console.log("Blocked:", check.blockers.map((b) => b.reason).join("; "));
}

Verify a webhook delivery

import { verifyWebhookSignature } from "@oilflow/sdk";

// In your webhook handler:
const valid = verifyWebhookSignature(
  rawBody,                      // Buffer or string — the unparsed body
  req.headers["x-oilflow-signature"],
  process.env.OILFLOW_WEBHOOK_SECRET!,
);
if (!valid) return res.status(401).end();

Stream the audit log

for await (const page of client.audit.pages({ days: 90 })) {
  console.log(`page: ${page.count} rows`);
  // ship rows somewhere
}

Subscribe to webhook events

const { id, secret } = await client.webhooks.create({
  url: "https://your-app.example.com/webhooks/oilflow",
  events: ["kyc.match_detected", "cluster.entity_added"],
  description: "Compliance war-room",
});
// secret is shown once; store it in your secret manager

For Slack/Teams native rendering, set delivery_format: "slack" (URL must be a hooks.slack.com incoming webhook) or "teams" (a webhook.office.com URL). OilFlow renders the payload as Block Kit / Adaptive Card on the server — no HMAC secret is issued (the URL is the auth).

Configuration

new OilFlow({
  apiKey: "oilflow_live_...",       // or OILFLOW_API_KEY env var
  baseUrl: "https://oilflow.us",    // or OILFLOW_BASE_URL env var
  maxRetries: 5,                    // default 5
  baseRetryDelayMs: 250,            // default 250
  timeoutMs: 30_000,                // per-request, default 30s
});

Error handling

import { OilFlowApiError } from "@oilflow/sdk";

try {
  await client.kyc.screen({ company_name: "..." });
} catch (e) {
  if (e instanceof OilFlowApiError) {
    console.error(e.statusCode, e.errorCode, e.requestId);
  }
}

error.errorCode is a stable, branchable identifier (auth_required, scope_denied, rate_limited, invalid_param, etc.). error.requestId is the value of X-Request-Id on the response, useful in support tickets.

Sandbox

Get a free sandbox key (7-day, 100 calls/day, read-only) without signup at https://oilflow.us/sandbox. Pass it as apiKey to evaluate the API end-to-end before upgrading to production.

Documentation

• Full API reference: https://oilflow.us/api-docs
• OpenAPI 3.1 spec: https://oilflow.us/openapi.yaml
• Postman collection: https://oilflow.us/oilflow.postman_collection.json

License

Apache-2.0.