BlackSwan Quickstart: Fetch Your First Credit Score

Fetch a wallet’s trust ratio, credit tier, and APR recommendation from BlackSwan using the REST API, JavaScript SDK, or Python SDK in under 2 minutes.

In this quickstart you’ll fetch a real wallet’s credit dashboard from the BlackSwan API — including its trust ratio, credit tier, current APR, and loan history. No API key, no account, and no contract deployment required. Pick the approach that fits your stack and you’ll have live credit data in your terminal within two minutes.

REST API

Send a single GET request to the /v1/credit/{address} endpoint. Replace the address with any wallet you want to score.

curl https://api.blackswanfinance.xyz/v1/credit/0x4EEA76237a91880B1c8B7a1c740610fFC0306EE4

Response

{
  "trustRatio": 7700,
  "trustTierScore": "C",
  "currentApr": 142,
  "totalBorrowedUsd": "99",
  "totalRepaidUsd": "99",
  "successfulLoans": 1,
  "defaults": 0
}

Field	Description
trustRatio	Normalized creditworthiness score (0–10,000)
trustTierScore	Letter grade derived from the trust ratio (A–F)
currentApr	Recommended APR in basis points for this wallet
totalBorrowedUsd	Lifetime USD value borrowed
totalRepaidUsd	Lifetime USD value repaid
successfulLoans	Number of loans fully repaid
defaults	Number of defaulted loans

JavaScript

Install the BlackSwan JavaScript SDK, then initialize a client and call getCreditDashboard.

npm install blackswan-sdk

import { BlackSwanClient } from "blackswan-sdk";

const client = new BlackSwanClient({
  network: "amoy",
  rpcUrl: "https://polygon-amoy.g.alchemy.com/v2/YOUR_ALCHEMY_KEY",
});

const wallet = "0x4EEA76237a91880B1c8B7a1c740610fFC0306EE4";
const dashboard = await client.getCreditDashboard(wallet);

console.log("Trust Ratio:  ", dashboard.trustRatio);
console.log("Credit Tier:  ", dashboard.trustTierScore);
console.log("Current APR:  ", dashboard.currentApr, "bps");

Output

Trust Ratio:   7700
Credit Tier:   C
Current APR:   142 bps

Python

Install the BlackSwan Python SDK, then call get_credit_dashboard with a wallet address.

pip install blackswan-sdk-py

from blackswan import BlackSwanClient

client = BlackSwanClient(
    network="amoy",
    rpc_url="https://polygon-amoy.g.alchemy.com/v2/YOUR_ALCHEMY_KEY",
)

wallet = "0x4EEA76237a91880B1c8B7a1c740610fFC0306EE4"
dashboard = client.get_credit_dashboard(wallet)

print("Trust Ratio: ", dashboard.trust_ratio)
print("Credit Tier: ", dashboard.trust_tier_score)
print("Current APR: ", dashboard.current_apr, "bps")

Output

Trust Ratio:  7700
Credit Tier:  C
Current APR:  142 bps

Append the optional ?network=sepolia query parameter to query Ethereum Sepolia instead of the default Amoy network. For example: curl "https://api.blackswanfinance.xyz/v1/credit/0x4EEA...?network=sepolia".

Next Steps

Install the SDK

Set up the JavaScript or Python SDK in your project with full configuration options.

Credit API Reference

Browse every available endpoint, parameter, and response field in the REST API.