Sandbox / Testnet

Build and test your VIZI integration without touching live data. Our sandbox mirrors the production API with mock wallets, deterministic scores, and zero rate limits.

Getting Started

The VIZI sandbox is a complete replica of the production environment. Every API endpoint, webhook event, and SDK method works identically — the only difference is that all data is simulated and no real blockchain queries are made.

Sandbox Base URL

https://sandbox.api.vizi.com/v2

Test API Keys

Sandbox keys start with vizi_sk_test_ (secret) and vizi_pk_test_ (publishable). Generate them from your dashboard or use the universal test key below for quick prototyping.

# Universal sandbox key (read-only, shared across all developers)
vizi_sk_test_sandbox_universal_key_2026

# To generate your own private sandbox key:
curl -X POST https://sandbox.api.vizi.com/v2/keys \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN"

Test Wallets

The sandbox comes preloaded with test wallet addresses that return deterministic scores. Use these to test every score range and edge case in your integration.

Excellent Score (800)

0xTEST_EXCELLENT_800

Long wallet history, zero liquidations, diverse protocol usage, healthy collateral ratios. Grade: A+.

Good Score (700)

0xTEST_GOOD_700

Solid repayment history, one minor liquidation, moderate protocol diversity. Grade: B+.

Fair Score (580)

0xTEST_FAIR_580

Shorter wallet age, multiple liquidations, thin collateral margins. Grade: C.

Poor Score (380)

0xTEST_POOR_380

New wallet, missed repayments, recent liquidation, low balances. Grade: D-.

No Score

0xTEST_NO_SCORE

Returns a 404 with score_not_found error. Use this to test your empty-state handling.

Sanctioned Wallet

0xTEST_SANCTIONED

Returns a score of 300 with a sanctions flag. Tests your compliance workflow handling.

Sandbox vs. Production

The sandbox behaves identically to production with a few intentional differences designed to make testing easier and faster.

No Rate Limits

Production enforces 100 requests/minute on the standard plan. The sandbox has no limit — fire as many requests as you need.

Instant Webhooks

Webhook events that might take minutes in production (waiting for on-chain confirmation) are delivered within 1 second in the sandbox.

Deterministic Scores

The same test address always returns the same score, so your tests are reproducible. In production, scores update as new on-chain data appears.

No Billing

Sandbox API calls are completely free and do not count toward your plan usage. Develop without worrying about costs.

Mock Scenarios

Use special test addresses to trigger specific error codes and edge cases. These let you verify your error handling without waiting for real failures.

# Simulate a timeout (returns 504 after 30s)
0xTEST_TIMEOUT

# Simulate rate limiting (returns 429)
0xTEST_RATE_LIMIT

# Simulate an internal server error (returns 500)
0xTEST_SERVER_ERROR

# Simulate a malformed response (returns 200 with invalid JSON)
0xTEST_MALFORMED

# Simulate a score that changes on every request (random 300-850)
0xTEST_VOLATILE

You can also trigger webhook events on demand using the sandbox API. This lets you test your webhook handler without waiting for real events.

curl -X POST https://sandbox.api.vizi.com/v2/webhooks/test \
  -H "Authorization: Bearer vizi_sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"endpoint_id": "we_abc123", "event_type": "score.updated"}'

Rate Limits in Sandbox

While the sandbox has no enforced rate limits, it does mirror production's rate limit headers so you can test your rate limit handling logic.

Every sandbox response includes the same headers as production: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. The values are simulated but realistic, so your client code can parse and react to them. Use the 0xTEST_RATE_LIMIT address to trigger actual 429 responses for testing your backoff logic.

Graduating to Production

When your integration is working in the sandbox, switch to production by swapping your test key for a live key and updating the base URL. No code changes required — the API contract is identical.

Get Live API Key View SDKs