Skip to main content
The ScoringClient interacts with the Agether scoring API. It lets you read the current onchain credit score for free, or trigger a fresh ML computation (x402-gated, $0.01 USDC per query).
Reading the current onchain score via getCurrentScore() is always free. Triggering a fresh computation via requestScore() costs $0.01 USDC and is settled via the x402 protocol.

​
Constructor

import { ScoringClient } from '@agether/sdk';

const scoring = new ScoringClient({
  endpoint: process.env.AGETHER_BACKEND_URL || 'http://95.179.189.214:3001',
});
The constructor takes a ScoringClientConfig object:
FieldTypeRequiredDescription
endpointstringYesBackend API URL
x402X402ConfigNox402 config for paid scoring calls
If you only need free score reads (getCurrentScore, getAgentDetails), the x402 config is not needed. It’s only required for requestScore() which triggers a fresh computation.
For paid scoring calls, provide x402 config: 
const scoring = new ScoringClient({
  endpoint: process.env.AGETHER_BACKEND_URL || 'http://95.179.189.214:3001',
  x402: {
    privateKey: process.env.AGENT_PRIVATE_KEY!,
    rpcUrl: 'https://base-rpc.publicnode.com',
    backendUrl: process.env.AGETHER_BACKEND_URL || 'http://95.179.189.214:3001',
    agentId: '17676',
    accountAddress: '0xYourSafeAccount',
  },
});

​
Methods

​
getCurrentScore(agentId)

Read the current onchain score from the Agether8004Scorer contract. Free, no payment required. 
const score = await scoring.getCurrentScore('17676');

console.log('Score:', score.score);           // 300–1000
console.log('Timestamp:', score.timestamp);   // Unix timestamp
console.log('Signer:', score.signer);         // Oracle address
console.log('Fresh:', score.fresh);           // true if < 24h old
console.log('Age (seconds):', score.age);
Response shape: 
{
  agentId: string;
  score: number;
  timestamp: number;
  signer: string;
  fresh: boolean;
  age: number;  // seconds since last update
}
A score is considered fresh if it was submitted within the last 24 hours. Stale scores still reflect the agent’s most recent assessment — they just haven’t been recomputed recently.

​
requestScore(agentId)

Trigger a fresh score computation. This is x402-gated ($0.01 USDC). Requires x402 config in the constructor. The flow:
  1. Client calls the scoring endpoint
  2. Server returns 402 → X402Client pays automatically
  3. Backend calls the ML service, computes score
  4. Backend signs and submits the score onchain via Agether8004Scorer.submitScore()
  5. Returns the score breakdown with txHash
const result = await scoring.requestScore('17676');

console.log('Score:', result.score);                    // 300–1000
console.log('Onchain TX:', result.txHash);

// Score breakdown
console.log('KYA Bonus:', result.breakdown.kyaBonus);
console.log('Account Bonus:', result.breakdown.accountBonus);
console.log('Balance Bonus:', result.breakdown.balanceBonus);
console.log('History Bonus:', result.breakdown.historyBonus);
console.log('Base Score:', result.breakdown.baseScore);
Response shape: 
interface ScoreResult {
  agentId: string;
  score: number;
  timestamp: number;
  breakdown: {
    kyaBonus: number;
    accountBonus: number;
    balanceBonus: number;
    historyBonus: number;
    baseScore: number;
  };
  txHash?: string;
}

​
getAgentDetails(agentId)

Fetch full agent details from the backend — including score, code approval status, and account info. 
const details = await scoring.getAgentDetails('17676');

console.log('Owner:', details.owner);
console.log('Account:', details.account);
console.log('Account Exists:', details.accountExists);
console.log('KYA Approved:', details.kyaApproved);
console.log('Score:', details.score);
console.log('Score Fresh:', details.scoreFresh);
console.log('Eligible:', details.eligible);

​
getAgentCount()

Get the total number of registered agents and accounts. 
const { totalAgents, totalAccounts } = await scoring.getAgentCount();
console.log('Total agents:', totalAgents);
console.log('Total accounts:', totalAccounts);

​
getHealth()

Check the scoring service health. 
const health = await scoring.getHealth();
console.log('Status:', health.status); // "ok"

​
getStatus()

Retrieve full protocol status — chain info, contract addresses, and scoring config. 
const status = await scoring.getStatus();

console.log('Chain:', status.chain.name);
console.log('Chain ID:', status.chain.id);
console.log('Score Price:', status.scoring.priceUsdc);
console.log('Pay To:', status.scoring.x402PayToAddress);
console.log('Signer:', status.signer);

​
Score Tiers Reference

Score RangeTierApproximate P(Default)
800–1000🟢 Excellent< 0.5%
670–799🟡 Good0.5–2%
580–669🟡 Fair2–8%
450–579🟠 Poor8–25%
300–449🔴 Very Poor> 25%

​
Safety Rails

The ML model’s output is adjusted by rule-based safety rails for critical cases:
Applies when the agent has very little credit history. New agents start at the minimum score of 300.
Applies when health factor is below 1.0. The agent is at or past the liquidation threshold.
Applies when the agent was liquidated within the last 30 days. Proven default risk.
Applies when the agent’s code has been audited and approved via the ValidationRegistry.

​
Complete Example

import { ScoringClient } from '@agether/sdk';

const scoring = new ScoringClient({
  endpoint: process.env.AGETHER_BACKEND_URL || 'http://95.179.189.214:3001',
});

const agentId = '17676';

// Check current score (free)
const current = await scoring.getCurrentScore(agentId);
console.log(`Current score: ${current.score} (${current.fresh ? 'fresh' : 'stale'})`);

// Get details
const details = await scoring.getAgentDetails(agentId);
console.log(`KYA approved: ${details.kyaApproved}`);
console.log(`Eligible: ${details.eligible}`);