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.

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 { VeriaddClient } from "@veriadd/js";

const client = new VeriaddClient({
  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 { VeriaddClient, VeriaddError } from "@veriadd/js";

try {
  const result = await client.verifyAddress({ ... });
} catch (err) {
  if (err instanceof VeriaddError) {
    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 { VeriaddClient } from "@veriadd/js";
import { NextRequest, NextResponse } from "next/server";

const veriadd = new VeriaddClient({ apiKey: process.env.VERIADD_KEY! });

export async function POST(req: NextRequest) {
  const body = await req.json();
  const result = await veriadd.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

Pure-Dart client for mobile, server and CLI apps — no Flutter SDK required. Install from pub.dev: pub.dev/packages/veriadd. A ready-made postcode picker widget ships in v0.2.0.

Installation

terminal
bash
dart pub add veriadd

Usage

kyc_service.dart
dart
import 'package:veriadd/veriadd.dart';

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

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

if (result.status == 'verified' && result.confidence >= 80) {
  // proceed to onboarding — result.auditId is your CBN trail
} else {
  // manual review queue, or reject and re-collect
}

Go

Zero-dependency Go module with per-service packages sharing one transport. 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/veriadd-go-sdk

Usage

main.go
go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    veriadd "github.com/veriadd/veriadd-go-sdk"
    "github.com/veriadd/veriadd-go-sdk/service/verify"
)

func main() {
    client, err := veriadd.New(os.Getenv("VERIADD_KEY"))
    if err != nil {
        log.Fatal(err)
    }

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

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

Python

Sync and async (httpx) Python client with typed dataclasses. Compatible with Django, FastAPI, Flask and plain scripts. Install from PyPI: pypi.org/project/veriadd.

Installation

bash
pip install veriadd

Sync usage

verify.py
python
import os
from veriadd import VeriaddClient

client = VeriaddClient(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 AsyncVeriaddClient

async def run():
    async with AsyncVeriaddClient(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