npm install @fairscale/sdk
# or
pnpm add @fairscale/sdk
# or
yarn add @fairscale/sdk

import { FairScale } from "@fairscale/sdk";

const client = new FairScale({
  apiKey: process.env.FAIRSCALE_API_KEY,       // Required (or use x402 per-request)
  baseUrl:      "https://agent-api.fairscale.xyz", // Agent & Credit API (default)
  humanBaseUrl: "https://api.fairscale.xyz",       // Human Score API (default)
  timeout: 10_000,                                 // ms, default 10 000
});

const result = await client.score("WALLET_ADDRESS");
console.log(result.score); // 67
console.log(result.tier);  // "silver"

// Optional task context for agent-specific scoring
const result = await client.score("WALLET_ADDRESS", {
  task: "defi_execution", // defi_execution | trust_focused | work_focused | hiring
});

{
  "wallet": "FRGumQszUGLTtfgH3gDwzG256pL4P8Cj3DDGAPCmBFka",
  "score": 67,
  "tier": "silver",
  "recommendation": { "tier": "trusted", "label": "Trusted", "color": "green" },
  "pillars": {
    "verification": 82,
    "wallet_history": 79,
    "work_history": 34,
    "network_quality": 71,
    "peer_reputation": 45
  },
  "signals": { "is_registered": true, "is_verified": true, "attestations": 3 },
  "red_flags": [],
  "badges": [{ "id": "verified_agent", "label": "Verified Agent", "tier": "gold" }],
  "meta": { "scored_at": "2026-04-07T12:00:00Z", "from_cache": false, "provider": "FairScale" }
}

const batch = await client.scoreBatch(["WALLET_1", "WALLET_2", "WALLET_3"]);

batch.results.forEach((r) => {
  if (r.error) return console.warn(r.wallet, r.error);
  console.log(r.wallet, r.score, r.tier);
});

{
  "total": 3,
  "scored": 3,
  "results": [ { "wallet": "...", "score": 72, "tier": "gold", "pillars": {...} } ],
  "meta": { "provider": "FairScale", "scored_at": "2026-04-07T12:00:00Z" }
}

// Preset (recommended)
const result = await client.scoreAI("WALLET_ADDRESS", {
  preset: "defi", // default | trust_focused | work_focused | defi | hiring
});

// Custom weights (must sum to 1.0 ± 0.02)
const result = await client.scoreAI("WALLET_ADDRESS", {
  weights: {
    verification:    0.40,
    wallet_history:  0.20,
    work_history:    0.20,
    network_quality: 0.10,
    peer_reputation: 0.10,
  },
});

const gate = await client.trustGate("WALLET_ADDRESS", {
  minScore:           40,              // Default 40. Minimum to pass.
  requireVerification: true,           // Optional. Requires registry presence.
  task:               "defi_execution",// Optional. Scoring context.
});

if (gate.allowed) {
  // proceed
} else {
  // deny — gate.score and gate.reason explain why
}

{
  "wallet": "WALLET_ADDRESS",
  "allowed": true,
  "score": 67,
  "reason": "score_above_threshold",
  "meta": { "from_cache": false, "provider": "FairScale" }
}

const profile = await client.agent("WALLET_ADDRESS");

const history = await client.scoreHistory("WALLET_ADDRESS");

const agents = await client.directory({
  page:        1,
  limit:       25,
  sort:        "agent_fairscore",  // See sort fields below
  minScore:    60,
  verifiedOnly: true,
  recommendation: "trusted",       // trusted | caution | high_risk | unverified
  source:      "said",             // said | erc8004 | sati
  search:      "DeFi",
  hasAttestations: true,
});

const top = await client.leaderboard({
  metric: "agent_fairscore", // any sort field
  limit:  25,
});

const credit = await client.credit("WALLET_ADDRESS", {
  amount:  5000,   // Loan amount in USD (default: 1000)
  nocache: false,  // Set true to bypass 15-min cache
});

console.log(credit.credit_score);       // 68
console.log(credit.risk_band);          // "near_prime"
console.log(credit.underwriting.opinion);  // Full analyst narrative
console.log(credit.underwriting.lending_terms.suggested_apr_range); // { low: 7, high: 14 }
console.log(credit.underwriting.risk_flags); // [ { type: "positive", signal: "..." } ]

const result = await client.human.getScore("WALLET_ADDRESS");

console.log(result.fairscore);       // 38.7
console.log(result.tier);            // "silver"
console.log(result.features.native_sol_percentile); // 96.73
console.log(result.badges.map(b => b.label));  // ["LST Staker", "SOL Maxi", ...]

// With social linking
const enriched = await client.human.getScore("WALLET_ADDRESS", {
  twitter: "handle",
});

{
  wallet: string;
  fairscore: number;            // 0–100 blended
  fairscore_base: number;       // on-chain only
  social_score: number;         // 0 if no X handle linked
  peer_score: number;           // 0 if no vouches received
  verified_human: boolean;      // VeryAI ZK palm-scan attestation
  tier: "bronze"|"silver"|"gold"|"platinum"|"diamond";
  badges: Badge[];
  actions: Action[];
  cached?: boolean;             // present on cache-hit responses
  timestamp: string;
  features: OnchainFeatures;    // 15 fields — see below
}

const fresh = await client.human.computeScore("WALLET", { twitter: "handle" });

const { fair_score }   = await client.human.fairScoreOnly("WALLET");   // 0–1000 integer, blended
const { wallet_score } = await client.human.walletScoreOnly("WALLET"); // 0–1000 integer, on-chain only
const { social_score } = await client.human.socialScoreOnly("WALLET"); // 0–1000 integer, social only

const score = await client.human.getScore("WALLET");
const pillars = client.insights.pillars(score);

// {
//   economy:         "High",
//   risk:            "Medium",
//   activity:        "High",
//   diversification: "Medium",
//   social:          "Low",
// }

const humanity = client.insights.humanityIndex(score);

// {
//   score: 87,                          // 0–100
//   tier:  "likely_human",              // verified_human | likely_human | unverified
// }

const fp = client.insights.fingerprint(score);

fp.portfolio;          // { sol, majors, stables, lsts } — all 0–100 percentiles
fp.capital_flow;       // { net_sol_30d }
fp.holding_conviction; // { median_hold_days, conviction_ratio, no_instant_dumps }
fp.activity_tempo;     // { tx_count, active_days, median_gap_hours }
fp.trading_behaviour;  // { tempo_cv, burst_ratio }

const profile = await client.profile("WALLET");

profile.score;           // HumanScoreResponse
profile.pillars;         // PillarScores (Economy/Risk/Activity/Diversification/Social)
profile.humanity_index;  // { score, tier }
profile.fingerprint;     // Grouped feature categories

try {
  const score = await client.score("BAD_ADDRESS");
} catch (err) {
  switch (err.status) {
    case 400: console.error("Bad request:", err.code);   break; // missing_wallet, invalid_wallet, etc.
    case 402: console.error("Payment required");         break; // no fairkey + no x402 payment
    case 429: console.error("Rate limited");             break;
    case 502: console.error("Upstream unavailable");     break;
  }
}

import { wrapFetch } from "@dexterai/x402/client";

const x402Fetch = wrapFetch(fetch, {
  walletPrivateKey: process.env.SOLANA_PRIVATE_KEY,
});

const res = await x402Fetch(
  "https://agent-api.fairscale.xyz/v1/score?wallet=WALLET_ADDRESS"
);
const data = await res.json();