Solutions

Real-world integration patterns drawn from FairScale's solutions verticals. Each section shows the exact API calls you need to implement the use case.

Agent Platforms

Verify agents before granting API access. Score credibility, check deployer binding, and verify work history before agents touch your tools, funds, or data.

API access gating

Check any agent before granting endpoint access. A single trust gate call is the simplest integration:

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

const client = new FairScale({ apiKey: process.env.FAIRSCALE_API_KEY });

async function gateAgent(agentWallet: string): Promise<boolean> {
  const gate = await client.trustGate(agentWallet, {
    minScore: 60,
    requireVerification: true, // Must have at least one registry entry
  });
  return gate.allowed;
}

Tiered permissions

Grant higher capabilities to more credible agents:

async function getAgentPermissions(agentWallet: string) {
  const result = await client.score(agentWallet);

  if (result.score >= 80) {
    return { tier: "full", maxTxValue: 50_000, rateLimit: 1000 };
  } else if (result.score >= 60) {
    return { tier: "standard", maxTxValue: 10_000, rateLimit: 200 };
  } else if (result.score >= 40) {
    return { tier: "restricted", maxTxValue: 1_000, rateLimit: 50 };
  } else {
    return { tier: "denied", maxTxValue: 0, rateLimit: 0 };
  }
}

Deployer accountability + work history

Pull the full agent profile to check deployer binding and verified job completions:

const profile = await client.agent(agentWallet);

const isDeployerBound = profile.signals?.is_registered ?? false;
const workHistoryScore = profile.pillars.work_history;

// Agents without verified work history get a lower trust ceiling
const effectiveTrustCeiling = workHistoryScore < 20 ? 40 : profile.score;

Marketplace curation

Query the directory for vetted agents to surface in your marketplace:

const curated = await client.directory({
  sort: "agent_fairscore",
  minScore: 60,
  verifiedOnly: true,
  recommendation: "trusted",
  limit: 50,
});

// curated.results → sorted list of agents with scores, badges, and registry info

Batch screen before listing

Screen multiple agents before approving marketplace listings:

const wallets = ["AGENT_1", "AGENT_2", "AGENT_3", "AGENT_4"];

const batch = await client.scoreBatch(wallets, { task: "trust_focused" });

const approved = batch.results.filter((r) => !r.error && r.score >= 60);
const rejected = batch.results.filter((r) => r.error || r.score < 60);

console.log(`Approved: ${approved.length} / ${wallets.length}`);

DeFi Protocols

Gate vaults, weight rewards, and filter extractors based on wallet credibility. Score real participants before they touch your liquidity.

Vault access gating

Restrict vault entry to wallets that meet a credibility threshold:

async function canEnterVault(wallet: string, minScore = 50): Promise<boolean> {
  const gate = await client.trustGate(wallet, { minScore });
  return gate.allowed;
}

Reward weighting

Scale yield rewards to credibility. Genuine participants earn more; mercenary capital earns less:

async function computeRewardMultiplier(wallet: string): Promise<number> {
  const result = await client.score(wallet);

  // Multiplier from 0.5x (bronze) to 1.5x (gold+)
  if (result.score >= 70) return 1.5;
  if (result.score >= 40) return 1.0;
  return 0.5;
}

Composable scoring for DeFi

Use the defi preset to weight on-chain activity more heavily:

const result = await client.scoreAI(wallet, { preset: "defi" });

// defi preset weights: wallet_history 0.30, network_quality 0.25, verification 0.25
// Higher weight on actual protocol interaction history vs peer reputation

Custom weights for governance

Reduce Sybil influence in governance by weighting verification and peer reputation:

const result = await client.scoreAI(wallet, {
  weights: {
    verification:    0.35,
    peer_reputation: 0.30,
    wallet_history:  0.20,
    network_quality: 0.10,
    work_history:    0.05,
  },
});

// Use result.score as a voting power multiplier
const baseVotes = getBaseVotes(wallet);
const weightedVotes = baseVotes * (result.score / 100);

Agent access control in DeFi

Score autonomous agents before granting DeFi protocol access:

async function admitAgentToProtocol(agentWallet: string) {
  const gate = await client.trustGate(agentWallet, {
    minScore: 55,
    requireVerification: true,
    task: "defi_execution",
  });

  if (!gate.allowed) {
    throw new Error(`Agent blocked: score ${gate.score}, reason ${gate.reason}`);
  }
}

Lending

Replace blanket collateral requirements with borrower-specific credit decisions. Assess creditworthiness before issuing any loan.

Loan origination

Assess every borrower before issuing a loan:

async function originate(wallet: string, requestedAmount: number) {
  const credit = await client.credit(wallet, { amount: requestedAmount });

  if (credit.risk_band === "decline") {
    return { approved: false, reason: "credit_decline" };
  }

  const terms = credit.underwriting.lending_terms;
  const actualAmount = Math.min(requestedAmount, terms.max_credit_line);

  return {
    approved: true,
    amount:           actualAmount,
    aprRange:         terms.suggested_apr_range,
    collateralRatio:  terms.collateral_ratio,
    maxTermDays:      terms.max_term_days,
    recommendation:   terms.recommendation,
  };
}

Collateral calibration

Set collateral ratios dynamically based on creditworthiness:

async function getCollateralRatio(wallet: string, amount: number): Promise<number> {
  const credit = await client.credit(wallet, { amount });
  // lending_terms.collateral_ratio is 0 for unsecured-eligible, 1.0 for 100%, 2.0 for 200%
  return credit.underwriting.lending_terms.collateral_ratio;
}

Interest rate pricing

Price rates to match actual borrower risk:

async function priceInterestRate(wallet: string, amount: number) {
  const credit = await client.credit(wallet, { amount });
  const { low, high } = credit.underwriting.lending_terms.suggested_apr_range;

  // Use midpoint for a single rate, or present a range to the borrower
  const midpointApr = (low + high) / 2;
  return { apr: midpointApr, range: { low, high } };
}

Risk flags review

Check for critical flags before approving any loan:

async function assessLoanRisk(wallet: string, amount: number) {
  const credit = await client.credit(wallet, { amount });
  const flags = credit.underwriting.risk_flags;

  const criticalFlags = flags.filter((f) => f.type === "critical");
  const warnings = flags.filter((f) => f.type === "warning");
  const positives = flags.filter((f) => f.type === "positive");

  if (criticalFlags.length > 0) {
    return { decision: "decline", criticalFlags };
  }

  return {
    decision: "approve",
    warnings,
    positives,
    band: credit.risk_band,
    score: credit.credit_score,
  };
}

Monitor portfolio risk

Re-score borrowers over time and detect deterioration:

async function monitorBorrower(wallet: string) {
  const [current, history] = await Promise.all([
    client.score(wallet),
    client.scoreHistory(wallet),
  ]);

  // Flag wallets where score dropped >15 points since the loan was issued
  const latestHistorical = history.scores?.[1]?.score ?? current.score;
  const scoreDelta = current.score - latestHistorical;

  if (scoreDelta < -15) {
    console.warn(`Score drop detected for ${wallet}: ${scoreDelta} pts`);
  }

  return { current: current.score, delta: scoreDelta };
}

Human Score API

The Human Score API (api.fairscale.xyz) covers human wallet scoring. See Score Endpoint, FairScore, and Wallet Score for full docs.

# Human wallet score — full breakdown
curl "https://api.fairscale.xyz/score?wallet=WALLET_ADDRESS" \
  -H "fairkey: zpka_your_key_here"

# FairScore only (lightweight)
curl "https://api.fairscale.xyz/fairScore?wallet=WALLET_ADDRESS" \
  -H "fairkey: zpka_your_key_here"