Credit Score Endpoint

GET /v1/credit

Returns a comprehensive credit assessment for any Solana wallet. Includes a 0–100 credit score, five credit pillars, a full underwriting opinion, recommended lending terms, risk flags, affordability analysis, and an on-chain attestation.

Both human wallets and agent wallets are supported.

Endpoint URL

https://agent-api.fairscale.xyz/v1/credit?wallet=WALLET_ADDRESS

Parameters

Parameter	Type	Required	Description
`wallet`	string	Yes	Solana wallet address
`amount`	number	No	Requested loan amount in USD (default: 1000)
`nocache`	0 or 1	No	Bypass 15-minute cache (default: 0)

Headers

Header	Value	Required
`X-Api-Key`	Your FairScale API key	Yes
`x-social-identity`	(optional) social proof	No

Pricing: Credit assessment costs $0.50 USDC via x402 (per-request), or is deducted from your plan. See Authentication.

Example Request

curl "https://agent-api.fairscale.xyz/v1/credit?wallet=WALLET_ADDRESS&amount=5000" \
  -H "X-Api-Key: zpka_your_key_here"

Response Structure

{
  "wallet": "WALLET_ADDRESS",
  "fairscore": 72,
  "fairscore_tier": "gold",
  "credit_score": 68,
  "risk_band": "near_prime",
  "confidence": { ... },
  "underwriting": { ... },
  "credit_pillars": { ... },
  "affordability": { ... },
  "trust_pillars": { ... },
  "credit_data": { ... },
  "flags": { ... },
  "attestation": { ... },
  "meta": { ... }
}

Top-Level Fields

Field	Type	Description
`wallet`	string	The assessed wallet address
`fairscore`	number	Trust score (0–100)
`fairscore_tier`	string	`platinum`, `gold`, `silver`, `bronze`, `unverified`
`credit_score`	number	Credit score (0–100)
`risk_band`	string	`prime`, `near_prime`, `subprime`, `deep_subprime`, `decline`

Risk Bands

Band	Score	Meaning
`prime`	75–100	Eligible for unsecured or minimal-collateral credit
`near_prime`	60–74	Recommended with moderate collateral
`subprime`	45–59	Conditional — full collateralisation, short terms
`deep_subprime`	25–44	High-risk — over-collateralised lending only
`decline`	0–24	Insufficient creditworthiness

Confidence

Measures how much on-chain data was available, not wallet quality. A high-confidence low score is reliable. A low-confidence high score may be inflated.

{
  "confidence": {
    "score": 72,
    "level": "high",
    "summary": "This assessment is based on 156 transactions over 412 days. Data confidence: High.",
    "limitations": []
  }
}

Field	Type	Description
`score`	number	Confidence score (0–100)
`level`	string	`high` (70+), `medium` (40–69), `low` (0–39)
`summary`	string	Human-readable summary
`limitations`	string[]	Data gaps affecting reliability

Underwriting

The core of the credit response. Contains the full analyst opinion, lending terms, and risk flags.

Opinion

A multi-paragraph narrative covering entity profile, collateral, obligations, revenue, repayment capacity, and a final recommendation with pillar breakdown.

{
  "underwriting": {
    "opinion": "This wallet holds $42,150 in on-chain assets — established (1.1 years, 156 transactions). SAID-verified agent identity, active across Kamino and Marginfi. Asset coverage 8.4x. Strong revenue: $3,200/month. Clean lending: 12 borrows, 100% repayment. Assessment: 68/100 (Near Prime). Recommended with moderate collateral.",
    "lending_terms": { ... },
    "risk_flags": [ ... ],
    "data_confidence": { ... }
  }
}

Lending Terms

Recommended terms derived from credit score, affordability, identity, and risk signals. These are suggestions, not decisions.

{
  "lending_terms": {
    "recommendation": "Recommended with moderate collateral. SAID-verified identity.",
    "suggested_apr_range": { "low": 7, "high": 14 },
    "collateral_ratio": 1.0,
    "collateral_note": "100% collateral recommended",
    "max_credit_line": 4215,
    "max_term_days": 60,
    "identity_level": "said",
    "identity_enhanced": true
  }
}

Field	Type	Description
`recommendation`	string	Narrative recommendation
`suggested_apr_range`	object	`{ low, high }` — annual percentage rate range
`collateral_ratio`	number	Recommended collateral ratio (0 = unsecured eligible, 2.0 = 200%)
`collateral_note`	string	Human-readable guidance
`max_credit_line`	number	Maximum recommended credit line in USD
`max_term_days`	number	Maximum recommended loan term in days (7–90)
`identity_level`	string	`kyc`, `strong`, `said`, `matrica`, `partial`, `none`
`identity_enhanced`	boolean	Whether identity verification improved terms

Risk Flags

Sorted by severity: critical → warning → positive.

{
  "risk_flags": [
    {
      "type": "positive",
      "signal": "Strong asset coverage",
      "detail": "8.4x coverage provides a substantial collateral buffer."
    },
    {
      "type": "positive",
      "signal": "Clean credit history",
      "detail": "12 borrows executed with 100% repayment rate."
    },
    {
      "type": "warning",
      "signal": "Limited transaction data",
      "detail": "Only 8 transactions available. Reduced confidence."
    }
  ]
}

Type	Meaning
`critical`	Active default risk, near-liquidation, high leverage
`warning`	Weak income, new wallet, limited data, low-trust funding
`positive`	Strong coverage, clean history, verified identity

Credit Pillars

Five pillars composing the credit score (0–100 each).

{
  "credit_pillars": {
    "financial_position": { "score": 74 },
    "credit_history":     { "score": 65 },
    "income_capacity":    { "score": 72 },
    "behavioural":        { "score": 58 },
    "identity_trust":     { "score": 71 }
  }
}

Pillar	Measures
`financial_position`	Asset holdings, stablecoin allocation, balance stability
`credit_history`	DeFi borrow/repay track record, liquidations, protocol engagement
`income_capacity`	Revenue flow, debt service ratio, income diversification
`identity_trust`	Identity verification, social accounts, network quality
`behavioural`	Holding behaviour, operational consistency

Attestation

HMAC-SHA256 signed proof that FairScale produced this score. Store alongside the loan record.

{
  "attestation": {
    "type": "signed_response",
    "payload_hash": "a1b2c3d4e5f6...",
    "payload_fields": "wallet|credit_score|risk_band|scored_at",
    "note": "Store this hash alongside the loan record. FairScale can verify it on request."
  }
}

SDK Usage

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

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

const credit = await client.credit("WALLET_ADDRESS", { amount: 5000 });

console.log(credit.credit_score);                            // 68
console.log(credit.risk_band);                               // "near_prime"
console.log(credit.underwriting.lending_terms.max_credit_line); // 4215
console.log(credit.underwriting.risk_flags);

Credit Score Endpoint

Credit Score Endpoint

Endpoint URL

Parameters

Headers

Example Request

Response Structure

Top-Level Fields

Risk Bands

Confidence

Underwriting

Opinion

Lending Terms

Risk Flags

Credit Pillars

Attestation

Meta

SDK Usage