The Score Lender Integration Partner Benefits API Access Research Get API Key
API Reference v1

VIZI® Score
REST API

RESTful. JSON. Under 15 seconds. Score any wallet address across 9+ chains with a single authenticated POST request.

REST / JSON
TLS 1.3
99.9% uptime SLA
Sandbox available
Python / Node / Go SDKs
Getting Started

Authentication

All API requests require a bearer token in the Authorization header. API keys are issued after partner approval. Apply here to receive sandbox and production credentials.

# All requests require this header Authorization: Bearer vizi_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx # Sandbox (no real data, deterministic responses) Authorization: Bearer vizi_test_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Sandbox keys return deterministic scores for any valid-format wallet address. Use vizi_test_sk_* during development. Never expose API keys in client-side code or public repositories.

Getting Started

Base URL

# Production https://api.vizi.com/v1 # Sandbox https://sandbox.api.vizi.com/v1

All endpoints accept and return application/json. All timestamps are ISO 8601 UTC. The API version is pinned at v1 — breaking changes will be versioned.

Getting Started

Quickstart

Score a wallet in under 2 minutes with cURL, Python, or Node.js.

curl -X POST https://api.vizi.com/v1/score \ -H "Authorization: Bearer vizi_live_sk_xxxx" \ -H "Content-Type: application/json" \ -d '{ "wallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "chain": "ethereum", "include_signals": true, "include_sanctions": true }'
import vizi client = vizi.Client(api_key="vizi_live_sk_xxxx") score = client.score.get( wallet="0x71C7656EC7ab88b098defB751B7401B5f6d8976F", chain="ethereum", include_signals=True, include_sanctions=True ) print(score.value) # 724 print(score.grade) # "Very Good" print(score.sanctions.status) # "clear"
import Vizi from '@vizi/node' const client = new Vizi({ apiKey: 'vizi_live_sk_xxxx' }) const score = await client.score.get({ wallet: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F', chain: 'ethereum', includeSignals: true, includeSanctions: true }) console.log(score.value) // 724 console.log(score.grade) // "Very Good"
package main import ( "fmt" vizi "github.com/vizi-com/vizi-go" ) func main() { client := vizi.NewClient("vizi_live_sk_xxxx") score, err := client.Score.Get(vizi.ScoreRequest{ Wallet: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", Chain: "ethereum", IncludeSignals: true, IncludeSanctions: true, }) if err != nil { panic(err) } fmt.Println(score.Value) // 724 fmt.Println(score.Grade) // "Very Good" }
Getting Started

SDKs

Official SDKs are available for Python, Node.js, and Go. Community SDKs for Ruby and Rust are maintained by partner contributors.

Python
vizi-python
pip install vizi
Node.js
@vizi/node
npm i @vizi/node
Go
vizi-go
go get github.com/vizi-com/vizi-go
Endpoints

POST /v1/score

Score a single wallet address. Returns a 300–850 VIZI® Score with optional signal breakdown and sanctions screening. Typical response time under 15 seconds.

POSThttps://api.vizi.com/v1/score

Request parameters

Parameter
Type
Required
Description
walletreq
string
required
Wallet address. Supports hex addresses, ENS names, and Solana base58 addresses.
chainreq
string
required
Chain identifier. See Supported Chains for valid values.
include_signals
boolean
optional
Return per-signal scores and weights. Default: false
include_sanctions
boolean
optional
Run and return real-time OFAC/OFSI screening. Default: true
cross_chain
boolean
optional
Aggregate on-chain data across all supported chains for this address. Default: false
idempotency_key
string
optional
UUID for idempotent retries. Same key returns the cached response within 10 minutes.
Reference

Response schema

All successful responses return HTTP 200 with the following JSON structure.

{ "wallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "chain": "ethereum", "score": 724, // 300–850 "grade": "Very Good", // Poor | Fair | Building | Good | Very Good | Excellent "signals": { // present if include_signals: true "repayment_history": { "score": 88, "weight": 0.28, "events": 14 }, "liquidation_record": { "score": 95, "weight": 0.19, "liquidations": 0 }, "wallet_age": { "score": 76, "weight": 0.15, "age_months": 38 }, "collateral_health": { "score": 71, "weight": 0.12 }, "avg_balance": { "score": 69, "weight": 0.10 }, "sanctions_exposure": { "score": 100, "weight": 0.09 }, "income_consistency": { "score": 55, "weight": 0.05 }, "protocol_diversity": { "score": 72, "weight": 0.02 } }, "sanctions": { // present if include_sanctions: true "status": "clear", // "clear" | "flagged" | "review" "screened_at": "2025-09-14T18:22:01Z", "lists_checked": ["OFAC_SDN", "OFSI", "Chainalysis", "Chainabuse"] }, "scored_at": "2025-09-14T18:22:12Z", "latency_ms": 11342, "request_id": "req_01HXZ7K9P2MNVB3Q4RSTVW6XYZ" }
Endpoints

POST /v1/score/batch

Score up to 500 wallets in a single async request. Results delivered via webhook or polled via the batch status endpoint. Ideal for pre-screening applicant pools.

POSThttps://api.vizi.com/v1/score/batchUp to 500 wallets
📋
Batch requests are processed asynchronously. The endpoint returns a batch_id immediately. Results are delivered to your configured webhook URL, or polled via GET /v1/score/batch/{batch_id}. Average batch processing: 2–8 minutes depending on chain mix and size.
Endpoints

GET /v1/score/history

Retrieve historical score records for a wallet address. Returns score values at each pull, sorted newest first. Requires the wallet to have been scored at least once via your API key.

GEThttps://api.vizi.com/v1/score/history?wallet=0x...&chain=ethereum&limit=30
Reference

Error codes

All errors return a JSON body with error and message fields.

Status
Code
Meaning
200
ok
Score successfully returned.
400
invalid_wallet
Wallet address format not recognized. Check chain and address format.
400
invalid_chain
Chain identifier not in supported list. See /v1/chains.
401
unauthorized
Missing or invalid API key. Check Authorization header.
402
quota_exceeded
Monthly pull quota reached. Upgrade tier or contact support.
429
rate_limited
Too many requests. See rate limit headers for reset time.
503
chain_unavailable
Chain data source temporarily unavailable. Retry with exponential backoff.
Reference

Rate limits

⏱
Standard: 10 requests/second, 5,000/month. Growth: 50 req/s, 50,000/month. Enterprise: Custom. Rate limit headers are returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Reference

Supported chains

Ethereum
ethereumLive
Solana
solanaLive
Base
baseLive
Polygon
polygonLive
Bitcoin
bitcoinLive
Arbitrum
arbitrumLive
Avalanche
avalancheLive
BNB Chain
bnbLive
XRP Ledger
xrpBeta
Sui
suiBeta
Aptos
aptosBeta
Reference

Webhooks

Configure a webhook endpoint to receive score events. Events are sent as HTTP POST with a JSON body and an X-VIZI-Signature HMAC-SHA256 header for verification.

Supported webhook events: score.completed, score.changed, sanctions.flagged, batch.completed.

🔒
Always verify the X-VIZI-Signature header before processing webhook payloads. Webhooks without a valid signature should be rejected. Retry logic: 3 attempts with exponential backoff (5s, 30s, 5m). Failed deliveries are logged in the partner dashboard.

Ready to build?

Apply for API access. Sandbox credentials issued in 48 hours.

Get API Key → Lender Integration Guide