BlackSwan SDK Next.js App Router Integration Guide

Integrate the BlackSwan SDK into a Next.js App Router project with a server-side API route and a client component for credit data display.

This guide shows how to integrate BlackSwan into a Next.js project using the App Router. The recommended pattern keeps SDK calls on the server inside an API route and uses a lightweight client component to fetch and display the data in the browser.

Install

npm install blackswan-sdk

Shared Client

Create a reusable client module so both your API routes and any server components can share the same instance:

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

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

API Route

The API route runs on the server and is the single place your application calls the BlackSwan SDK. It accepts a wallet query parameter and returns the credit dashboard as JSON:

// app/api/credit/route.ts
import { NextRequest, NextResponse } from "next/server";
import { client } from "@/lib/blackswan";

export async function GET(request: NextRequest) {
  const wallet = request.nextUrl.searchParams.get("wallet");

  if (!wallet) {
    return NextResponse.json({ error: "wallet parameter is required" }, { status: 400 });
  }

  try {
    const dashboard = await client.getCreditDashboard(wallet);

    return NextResponse.json({
      trustRatio: dashboard.trustRatio,
      trustTierScore: dashboard.trustTierScore,
      // APR is in basis points — divide by 1000 for a percentage value.
      // e.g. 142 → 0.142%
      apr: dashboard.currentApr / 1000
    });
  } catch (err) {
    return NextResponse.json({ error: "Failed to fetch credit data" }, { status: 500 });
  }
}

Client Component

The client component calls the API route from the browser and renders the result. Mark it with "use client" so Next.js keeps it out of the server bundle:

// components/CreditDashboard.tsx
"use client";

import { useEffect, useState } from "react";

interface CreditData {
  trustRatio: number;
  trustTierScore: string;
  apr: number;
}

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

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

    fetch(`/api/credit?wallet=${encodeURIComponent(wallet)}`)
      .then((res) => {
        if (!res.ok) throw new Error(`Request failed: ${res.status}`);
        return res.json();
      })
      .then(setData)
      .catch((err) => setError(err.message))
      .finally(() => setLoading(false));
  }, [wallet]);

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

  return (
    <div>
      <h2>Credit Profile</h2>
      <p>Trust Score: {data.trustRatio}</p>
      <p>Tier: {data.trustTierScore}</p>
      <p>APR: {data.apr.toFixed(3)}%</p>
    </div>
  );
}

Page

Compose the client component inside a server page. Pass the wallet address however your application resolves it — from session, from URL params, or from a form:

// app/credit/page.tsx
import { CreditDashboard } from "@/components/CreditDashboard";

export default function CreditPage() {
  // Replace with your wallet resolution logic (session, search params, etc.)
  const wallet = "0xYourWalletAddress";

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