SDKs & Client Libraries

Official and community SDK clients for the Veriadd API. All SDKs wrap the same REST API with idiomatic interfaces, built-in retry logic, and typed responses.

Note:All SDKs are in early development. The REST API is stable — you can integrate directly while SDKs are being published. Track releases on the changelog.

JavaScript / TypeScript

Server-side Node.js client with full TypeScript types. Works in Next.js API routes, Express, Fastify, Cloudflare Workers and any modern JS runtime.

Installation

terminal

bash

npm install @veriadd/js

Usage

verify.ts

typescript

import { VeriaClient } from "@veriadd/js";

const client = new VeriaClient({
  apiKey: process.env.VERIADD_KEY!,
  // baseUrl: "https://api.veriadd.tech",  // optional override
  // timeout: 10_000,                    // ms, default 10s
});

// Verify address (L3 — BVN + phone cross-check)
const result = await client.verifyAddress({
  postcode:   "LA-11-W06-TC-10",
  state:      "LAGOS",
  first_name: "Adaeze",
  last_name:  "Okafor",
  bvn:        "22233344455",
  phone:      "08031234567",
  level:      3,
});

console.log(result.status);      // "verified" | "partial" | "failed" | "invalid"
console.log(result.confidence);  // 0–100
console.log(result.reasons);     // string[]

// Lookup only (free, no identity)
const lookup = await client.lookup("LA-11-W06-TC-10", 1);

// Autocomplete
const suggestions = await client.autocomplete("LA-11");

// Wallet balance
const wallet = await client.wallet();
console.log(wallet.balance_ngn);  // e.g. 1500

Error handling

error.ts

typescript

import { VeriaClient, VeriaError } from "@veriadd/js";

try {
  const result = await client.verifyAddress({ ... });
} catch (err) {
  if (err instanceof VeriaError) {
    console.error(err.code);     // "insufficient_credits"
    console.error(err.status);   // 402
    console.error(err.message);  // "top up your Veriadd wallet..."
  }
}

Next.js API route example

app/api/kyc/route.ts

typescript

import { VeriaClient } from "@veriadd/js";
import { NextRequest, NextResponse } from "next/server";

const veria = new VeriaClient({ apiKey: process.env.VERIADD_KEY! });

export async function POST(req: NextRequest) {
  const body = await req.json();
  const result = await veria.verifyAddress({
    postcode:   body.postcode,
    state:      body.state,
    bvn:        body.bvn,
    phone:      body.phone,
    level:      3,
  });

  if (result.status !== "verified" || result.confidence < 80) {
    return NextResponse.json({ error: "Address verification failed" }, { status: 422 });
  }

  return NextResponse.json({ verified: true, auditId: result.audit_id });
}

Flutter / Dart

Dart package for mobile and web apps. Includes a ready-made postcode picker widget with autocomplete.

Installation

pubspec.yaml

yaml

dependencies:
  veriadd: ^0.1.0

Usage

kyc_service.dart

dart

import 'package:veriadd/veriadd.dart';

final client = VeriaClient(apiKey: const String.fromEnvironment('VERIADD_KEY'));

// Verify address
final result = await client.verifyAddress(
  postcode:  'LA-11-W06-TC-10',
  state:     'LAGOS',
  firstName: 'Adaeze',
  lastName:  'Okafor',
  bvn:       '22233344455',
  phone:     '08031234567',
  level:     3,
);

switch (result.status) {
  case VerificationStatus.verified:
    // proceed to onboarding
  case VerificationStatus.partial:
    // manual review queue
  case VerificationStatus.failed:
  case VerificationStatus.invalid:
    // reject or re-collect
}

Postcode picker widget

address_form.dart

dart

import 'package:veriadd/widgets.dart';

VeriaddPostcodePicker(
  apiKey: const String.fromEnvironment('VERIADD_KEY'),
  onSelected: (postcode) {
    setState(() => _postcode = postcode);
  },
  placeholder: 'Enter Nigerian postcode...',
)

Go

Zero-dependency Go module. Suitable for backend services and CLI tools built with the same Go stack as the Veriadd server itself.

Installation

bash

go get github.com/veriadd/go-veriadd

Usage

main.go

package main

import (
    "context"
    "fmt"
    "os"

    veria "github.com/veriadd/go-veriadd"
)

func main() {
    client := veria.New(os.Getenv("VERIADD_KEY"))

    result, err := client.VerifyAddress(context.Background(), veria.VerifyRequest{
        Postcode:  "LA-11-W06-TC-10",
        State:     "LAGOS",
        FirstName: "Adaeze",
        LastName:  "Okafor",
        BVN:       "22233344455",
        Phone:     "08031234567",
        Level:     3,
    })
    if err != nil {
        var veriaErr *veria.Error
        if errors.As(err, &veriaErr) {
            fmt.Fprintf(os.Stderr, "code=%s status=%d\n", veriaErr.Code, veriaErr.Status)
        }
        os.Exit(1)
    }

    fmt.Printf("status=%s confidence=%d\n", result.Status, result.Confidence)
}

Python

Sync and async (httpx) Python client with Pydantic models. Compatible with Django, FastAPI, Flask and plain scripts.

Installation

bash

pip install veriadd

Sync usage

verify.py

python

import os
from veriadd import VeriaClient

client = VeriaClient(api_key=os.environ["VERIADD_KEY"])

result = client.verify_address(
    postcode="LA-11-W06-TC-10",
    state="LAGOS",
    first_name="Adaeze",
    last_name="Okafor",
    bvn="22233344455",
    phone="08031234567",
    level=3,
)

print(result.status)      # "verified"
print(result.confidence)  # 92
print(result.reasons)     # [...]

Async usage

verify_async.py

python

from veriadd import AsyncVeriaClient

async def run():
    async with AsyncVeriaClient(api_key=os.environ["VERIADD_KEY"]) as client:
        result = await client.verify_address(
            postcode="LA-11-W06-TC-10",
            state="LAGOS",
            bvn="22233344455",
            level=3,
        )
        return result

Using the REST API directly

No SDK? No problem. The API is a plain JSON REST API with predictable conventions. See the full API Reference for every endpoint, parameter and response schema.

verify.sh

bash

curl -s -X POST https://api.veriadd.tech/v1/verify/address \
  -H "X-API-Key: $VERIADD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postcode": "LA-11-W06-TC-10",
    "state": "LAGOS",
    "bvn": "22233344455",
    "level": 3
  }' | jq .data.status