Display a Wallet Trust Score with the BlackSwan SDK

Learn how to fetch and display a wallet’s trust score and tier using the BlackSwan SDK, with visual indicator and progress bar components.

Every wallet on BlackSwan has a trust score expressed as a ratio and a corresponding tier (A through E). This tutorial shows you how to fetch that data and build visual components that communicate creditworthiness at a glance.

Prerequisites

Install the BlackSwan JavaScript SDK:

npm install blackswan-sdk

Client Setup

Create a shared client instance to use across your components:

import { BlackSwanClient } from "blackswan-sdk";

const client = new BlackSwanClient({
  network: "amoy",
  rpcUrl: process.env.NEXT_PUBLIC_RPC_URL!
});

Fetching the Trust Ratio

Use getTrustRatio to retrieve the raw trust score for a wallet address:

import { BlackSwanClient } from "blackswan-sdk";

const client = new BlackSwanClient({
  network: "amoy",
  rpcUrl: process.env.NEXT_PUBLIC_RPC_URL!
});

const ratio = await client.getTrustRatio(wallet);

Visual Trust Indicator

The trust ratio maps to a letter tier. Render a colored badge that reflects that tier so users can immediately understand their credit standing:

import { useEffect, useState } from "react";
import { BlackSwanClient } from "blackswan-sdk";

const client = new BlackSwanClient({
  network: "amoy",
  rpcUrl: process.env.NEXT_PUBLIC_RPC_URL!
});

function TrustIndicator({ wallet }: { wallet: string }) {
  const [ratio, setRatio] = useState<number | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    client.getTrustRatio(wallet)
      .then(setRatio)
      .catch((err) => setError(err instanceof Error ? err : new Error("Failed to load trust ratio")))
      .finally(() => setLoading(false));
  }, [wallet]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (ratio === null) return null;

  const tier =
    ratio >= 9000 ? "A" :
    ratio >= 8000 ? "B" :
    ratio >= 7000 ? "C" :
    ratio >= 6000 ? "D" : "E";

  const color =
    tier === "A" ? "green" :
    tier === "B" ? "blue" :
    tier === "C" ? "yellow" :
    tier === "D" ? "orange" : "red";

  return (
    <div style={{ color }}>
      {tier} Tier ({ratio})
    </div>
  );
}

Trust Progress Bar

A progress bar gives users an intuitive sense of how close they are to the next tier. The trust ratio is a value from 0 to 10000, so divide by 100 to express it as a 0–100% bar width:

function TrustBar({ ratio }: { ratio: number }) {
  const percentage = ratio / 100; // 0–10000 scale → 0–100%

  return (
    <div style={{ width: "100%", background: "#eee" }}>
      <div style={{ width: `${percentage}%`, background: "#4caf50", height: 20 }} />
    </div>
  );
}