SDKs & Libraries

Integrate VIZI scoring into your application in minutes. Official client libraries for Python, Node.js, Go, and Rust — all open source, fully typed, and production-ready.

Quick Start

Each SDK wraps the VIZI REST API with idiomatic patterns for your language. Install the one that fits your stack, set your API key, and start querying scores immediately.

Python — vizi

Supports Python 3.8+. Async-ready with asyncio support. Ships with full type hints and Pydantic models.

pip install vizi

Node.js — @vizi/sdk

Works with Node 18+ and all major runtimes (Bun, Deno). Full TypeScript definitions included.

npm install @vizi/sdk

Go — vizi-go

Idiomatic Go module with context support, structured errors, and zero external dependencies.

go get github.com/vizi-score/vizi-go

Rust — vizi

Async-first with tokio. Fully typed request/response structs. no_std-compatible core.

cargo add vizi

Usage Examples

Every SDK follows the same pattern: initialize a client with your API key, then call methods that map directly to API endpoints. Here are complete working examples for each language.

Python

from vizi import ViziClient

client = ViziClient(api_key="vizi_sk_live_your_key_here")

# Look up a VIZI Score by wallet address
score = client.scores.get("0x1234...abcd")
print(f"Score: {score.value}")       # 300-850
print(f"Grade: {score.grade}")       # A+ through F
print(f"Factors: {score.factors}")   # Breakdown of scoring signals

# Batch lookup (up to 100 addresses)
results = client.scores.batch([
    "0x1234...abcd",
    "0x5678...efgh",
])
for r in results:
    print(f"{r.address}: {r.value}")

Node.js / TypeScript

import { ViziClient } from '@vizi/sdk';

const vizi = new ViziClient({ apiKey: 'vizi_sk_live_your_key_here' });

// Look up a VIZI Score
const score = await vizi.scores.get('0x1234...abcd');
console.log(`Score: ${score.value}`);       // 300-850
console.log(`Grade: ${score.grade}`);       // A+ through F
console.log(`Factors:`, score.factors);     // Breakdown

// Subscribe to score changes
const subscription = await vizi.monitoring.create({
  address: '0x1234...abcd',
  webhookUrl: 'https://your-app.com/webhook',
  threshold: 50,  // notify on 50+ point change
});

Go

package main

import (
    "context"
    "fmt"
    "github.com/vizi-score/vizi-go"
)

func main() {
    client := vizi.NewClient("vizi_sk_live_your_key_here")

    score, err := client.Scores.Get(context.Background(), "0x1234...abcd")
    if err != nil {
        panic(err)
    }

    fmt.Printf("Score: %d\n", score.Value)
    fmt.Printf("Grade: %s\n", score.Grade)
}

Rust

use vizi::ViziClient;

#[tokio::main]
async fn main() -> Result<(), vizi::Error> {
    let client = ViziClient::new("vizi_sk_live_your_key_here");

    let score = client.scores().get("0x1234...abcd").await?;
    println!("Score: {}", score.value);   // 300-850
    println!("Grade: {}", score.grade);   // A+ through F

    Ok(())
}

Authentication

All SDKs authenticate using your VIZI API key. Secret keys (starting with vizi_sk_) should only be used server-side. Publishable keys (vizi_pk_) are safe for client-side widget embeds.

# Environment variable (recommended)
export VIZI_API_KEY="vizi_sk_live_your_key_here"

# The SDK auto-detects the environment variable
from vizi import ViziClient
client = ViziClient()  # reads VIZI_API_KEY automatically

# Or pass explicitly
client = ViziClient(api_key="vizi_sk_live_your_key_here")

API keys are scoped to your organization. You can create multiple keys with different permissions (read-only, read-write, admin) from your VIZI dashboard. Rotate keys at any time without downtime — old keys remain valid for 24 hours after rotation to give you time to deploy.

Error Handling

Every SDK provides typed error classes so you can handle failures precisely. All errors include a machine-readable code, a human-readable message, and the HTTP status.

from vizi import ViziClient, ViziError, NotFoundError, RateLimitError

client = ViziClient()

try:
    score = client.scores.get("0xINVALID")
except NotFoundError:
    print("Wallet not found or has no score yet")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ViziError as e:
    print(f"API error {e.code}: {e.message}")

Typed Exceptions

Each error type maps to an HTTP status: NotFoundError (404), RateLimitError (429), ValidationError (400), AuthError (401).

Automatic Retries

Transient errors (429, 500, 502, 503) are retried automatically with exponential backoff and jitter. Configurable max retries and timeout.

Rate Limits

VIZI enforces rate limits per API key to ensure fair usage. All SDKs include built-in rate limit handling with automatic retry and backoff.

Standard Plan

100 requests per minute, 10,000 requests per day. Batch endpoint counts as 1 request regardless of address count (up to 100).

Enterprise Plan

Custom rate limits based on your needs. Dedicated infrastructure, priority support, and SLA guarantees. Contact sales for details.

Rate Limit Headers

Every response includes X-RateLimit-Remaining, X-RateLimit-Limit, and X-RateLimit-Reset headers for your own tracking.

Sandbox: No Limits

The sandbox environment has no rate limits at all. Fire as many requests as you need during development and testing.

Community SDKs

In addition to our official SDKs, the VIZI community maintains client libraries for other languages. These are not officially supported but are actively maintained and widely used.

Ruby

gem install vizi-ruby — Maintained by the Rails community. Supports Rails integration with ActiveRecord callbacks and model concerns.

PHP

composer require vizi/vizi-php — Laravel and Symfony compatible. Includes Blade components for widget rendering.

Java / Kotlin

Maven: com.vizi:vizi-java:2.4.0 — Spring Boot starter included. Kotlin coroutine support via vizi-kotlin artifact.

Elixir

{:vizi, "~> 1.0"} — OTP-native with GenServer-based connection pooling and Telemetry instrumentation.

Start Building Today

Get your API key and start integrating VIZI scores into your application. Full documentation, sandbox access, and community support included.

Get API Key Try the Sandbox