BlackSwan SDK React Integration Guide for Developers

Step-by-step guide to integrating the BlackSwan SDK into a React application using a custom hook with loading and error state handling.

Integrating BlackSwan into a React app is straightforward with a custom hook that encapsulates SDK calls and manages loading and error state. This guide walks you through installation, hook creation, and rendering credit data in your components.

Install

npm install blackswan-sdk

Client Setup

Create a single shared client instance so you don’t re-initialise on every render:

// lib/blackswanClient.ts
import { BlackSwanClient } from "blackswan-sdk";

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

Custom Hook

The useCreditDashboard hook fetches the credit dashboard for a given wallet and exposes data, loading, and error so consuming components can handle all three states:

// hooks/useCreditDashboard.ts
import { useEffect, useState } from "react";
import { BlackSwanClient } from "blackswan-sdk";

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

interface CreditDashboardData {
  trustRatio: number;
  trustTierScore: string;
  currentApr: number;
}

export function useCreditDashboard(wallet: string) {
  const [data, setData] = useState<CreditDashboardData | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    if (!wallet) return;

    setLoading(true);
    setError(null);

    client
      .getCreditDashboard(wallet)
      .then(setData)
      .catch((err) =>
        setError(err instanceof Error ? err : new Error("Failed to load credit dashboard"))
      )
      .finally(() => setLoading(false));
  }, [wallet]);

  return { data, loading, error };
}

Usage in a Component

Import the hook and render each state — loading, error, and success — cleanly:

// components/CreditProfile.tsx
import { useCreditDashboard } from "../hooks/useCreditDashboard";

export function CreditProfile({ wallet }: { wallet: string }) {
  const { data, loading, error } = useCreditDashboard(wallet);

  if (loading) return <div>Loading credit profile…</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!data) return null;

  // APR is returned in basis points — divide by 1000 to get a percentage.
  // A raw value of 142 = 0.142%.
  return (
    <div>
      <h1>Trust Score: {data.trustRatio}</h1>
      <p>Tier: {data.trustTierScore}</p>
      <p>APR: {(data.currentApr / 1000).toFixed(3)}%</p>
    </div>
  );
}

App Entry Point

Wire the component into your app with a wallet address:

// App.tsx
import { CreditProfile } from "./components/CreditProfile";

export default function App() {
  const wallet = "0xYourWalletAddress";

  return (
    <main>
      <h1>BlackSwan Credit Dashboard</h1>
      <CreditProfile wallet={wallet} />
    </main>
  );
}