Fintech SDKv0.2.0

Official TypeScript SDK for AEVION fintech modules. Wraps REST APIs with types, retries, and HMAC webhook validation.

npm package ↗API reference ↗Error codes ↗Changelog ↗

Published packages· 101 dl/wk total

@aevion-io/fintech-sdkv0.2.07 dl/wk1mo ago @aevion-io/catalog-clientv0.8.112 dl/wk1mo ago @dosymbek/qpaynet-clientv1.0.472 dl/wk1mo ago @dosymbek/qcoreai-clientv1.0.010 dl/wk1mo ago

Installation

npm install @aevion-io/fintech-sdk
# or
yarn add @aevion-io/fintech-sdk
# or
pnpm add @aevion-io/fintech-sdk

Initialization

import { AevionFintech } from "@aevion-io/fintech-sdk";

const fintech = new AevionFintech({
  apiKey: process.env.AEVION_API_KEY!,  // aev_live_... or aev_test_...
  baseUrl: "https://api.aevion.app",     // optional, defaults to prod
});

QPayNet — Wallets

// Create a wallet
const wallet = await fintech.qpaynet.wallets.create({
  name: "Customer wallet",
  currency: "KZT",
});

// Transfer between wallets
const tx = await fintech.qpaynet.transfer({
  fromWalletId: wallet.id,
  toWalletId: "wallet_recipient_id",
  amount: 5000,          // KZT in tiin (×100)
  description: "Order #123 payment",
});

// Create payment request (generates shareable link)
const req = await fintech.qpaynet.requests.create({
  toWalletId: wallet.id,
  amount: 12500,
  description: "Invoice #456",
  expiresAt: new Date(Date.now() + 86400_000).toISOString(),
});
console.log(req.payUrl); // https://aevion.app/qpaynet/r/TOKEN

VeilNetX — Settlement

// Subscribe to waitlist
const entry = await fintech.veilnetx.waitlist.subscribe({
  email: "ops@company.com",
  useCase: "settlement-routing",
});

// Check ledger status
const status = await fintech.veilnetx.ledger.status();
console.log(status.blockHeight, status.tps);

Z-Tide — Reputation

// Get reputation score for a user
const score = await fintech.ztide.scores.get(userId);
console.log(score.total, score.rank, score.tier);

// Submit a contribution event
await fintech.ztide.events.submit({
  userId,
  type: "task_completed",
  weight: 1.0,
  metadata: { taskId: "task_123" },
});

// Get leaderboard
const board = await fintech.ztide.leaderboard({ limit: 10, category: "global" });

Webhooks

// All fintech modules fire events to your webhook URL
// Set endpoint in: https://aevion.app/qpaynet/settings/webhooks

// Validate HMAC signature (Express example)
import crypto from "node:crypto";

app.post("/webhooks/aevion", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.headers["x-aevion-signature"] as string;
  const expected = crypto
    .createHmac("sha256", process.env.AEVION_WEBHOOK_SECRET!)
    .update(req.body)
    .digest("hex");
  if (sig !== `sha256=${expected}`) return res.status(401).end();

  const event = JSON.parse(req.body.toString());
  // event.type: "transfer.completed" | "request.paid" | "score.changed" | ...
  res.status(200).end();
});

Error handling

import { AevionFintechError } from "@aevion-io/fintech-sdk";

try {
  await fintech.qpaynet.transfer({ ... });
} catch (err) {
  if (err instanceof AevionFintechError) {
    console.error(err.code);    // "insufficient_balance" | "rate_limited" | ...
    console.error(err.status);  // 400 | 402 | 429 | 500
    console.error(err.module);  // "qpaynet" | "veilnetx" | ...
  }
}

Rate limits & retry policy

The SDK auto-retries on 429 and 5xx with exponential backoff (3 attempts, max 8s delay). Use { retries: 0 } to disable. See tier limits →