Documentation Index
Fetch the complete documentation index at: https://docs.agentscore.sh/llms.txt
Use this file to discover all available pages before exploring further.
Installation
npm install @agent-score/sdk
Quick start
import { AgentScore } from "@agent-score/sdk";
const client = new AgentScore({ apiKey: process.env.AGENTSCORE_API_KEY });
// Summary lookup (free tier)
const summary = await client.getReputation("0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671");
console.log(summary.score.value, summary.score.grade);
// On-the-fly assessment with decision (paid tier)
const assessment = await client.assess("0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671", {
policy: { require_kyc: true },
});
if (assessment.decision === "deny") {
console.log("Denied:", assessment.decision_reasons);
}
API reference
Constructor
new AgentScore(options: {
apiKey: string;
baseUrl?: string; // default: "https://api.agentscore.sh"
timeout?: number; // default: 10000 (ms)
userAgent?: string; // custom prefix prepended to default UA, e.g. "myapp/1.0"
})
userAgent to prepend your app’s identifier to outbound requests so AgentScore support can trace traffic back to you:
const client = new AgentScore({ apiKey, userAgent: "myapp/1.0" });
// Outbound UA: "myapp/1.0 (@agent-score/sdk@2.0.0)"
client.getReputation(address, options?)
Look up a wallet’s cached reputation profile. Free tier.
// All chains (operator overview)
const result = await client.getReputation(address);
// Filtered to a specific chain
const baseResult = await client.getReputation(address, { chain: "base" });
ReputationResponse with top-level score (operator-level), verification_level ("none", "wallet_claimed", or "kyc_verified"), chains array (per-chain score and classification), and optionally operator_score, reputation, and agents. Pro tier includes full chain details (identity, activity, evidence). When chain is provided, the chains and agents arrays are filtered to that chain.
client.assess(address, options?)
On-the-fly trust assessment with policy evaluation. Paid tier only.
// With wallet address
const result = await client.assess("0x1234...", {
policy: { require_kyc: true },
chain: "base",
refresh: false,
});
// With operator credential (non-wallet agents)
const result = await client.assess(null, {
operatorToken: "opc_abc123...",
policy: { require_kyc: true, min_age: 21 },
});
if (result.decision === "deny") {
console.log("Denied:", result.decision_reasons);
}
AssessResponse with decision, decision_reasons, identity_method ("wallet" or "operator_token"), and all reputation fields (null for credential-based assessments).
Compliance assessment
Use compliance policy fields to enforce KYC, sanctions, age, and jurisdiction requirements:
const result = await client.assess("0x1234...", {
policy: {
require_kyc: true,
require_sanctions_clear: true,
min_age: 21,
blocked_jurisdictions: ["KP", "IR"],
},
});
if (result.decision === "deny") {
console.log("Denied:", result.decision_reasons);
console.log("Policy checks:", result.policy_result.checks);
// If denial is resolvable through verification, verify_url is present
if (result.verify_url) {
console.log("Verification required:", result.verify_url);
}
}
Sessions & credentials
// Create a verification session (for merchant use)
const session = await client.createSession({
context: "wine_purchase",
product_name: "Cabernet 2022",
});
// session.verify_url — give to user
// session.poll_url — URL the agent polls
// session.poll_secret — X-Poll-Secret header for the agent's polls
// Optional pre-association: attach the session to a known wallet
// (`address`) or refresh KYC for an existing credential (`operator_token`).
await client.createSession({ address: "0x..." });
await client.createSession({ operator_token: "opc_..." });
// Poll for completion
const poll = await client.pollSession(session.session_id, session.poll_secret);
if (poll.status === "verified") {
console.log("Credential:", poll.operator_token);
}
// Create a credential directly (if user already KYC'd)
const cred = await client.createCredential({ label: "claude-code", ttl_days: 1 });
console.log("Use this:", cred.credential);
// List and revoke
const list = await client.listCredentials();
await client.revokeCredential(list.credentials[0].id);
Report captured wallets
After an agent paid under a credential, report the signer wallet so AgentScore can build a cross-merchant profile:
await client.associateWallet({
operatorToken: "opc_...",
walletAddress: signerFromPayment, // EIP-3009 `from`, Tempo MPP DID, or Solana pubkey
network: "evm", // or "solana"
idempotencyKey: paymentIntentId, // optional — retries of same payment no-op
});
{ associated: true, first_seen: boolean, deduped?: true }.
Error handling
The SDK throws typed errors:
import { AgentScoreError } from "@agent-score/sdk";
try {
const rep = await client.getReputation("0xinvalid");
} catch (err) {
if (err instanceof AgentScoreError) {
console.log(err.code); // "invalid_address"
console.log(err.message); // "The provided wallet address is not a valid EVM address."
console.log(err.status); // 400
}
}
AgentScoreError with code: "timeout" or code: "network_error".
AgentScoreError.details: Record<string, unknown> carries response-body fields beyond {code, message} — verify_url, linked_wallets, claimed_operator, actual_signer, expected_signer, reasons, agent_memory — so callers can branch on granular denial codes without re-parsing:
try {
await client.assess("0xabc...", { policy: { require_kyc: true } });
} catch (err) {
if (!(err instanceof AgentScoreError)) throw err;
if (err.code === "wallet_signer_mismatch") {
const linked = err.details.linked_wallets as string[] | undefined;
// re-sign from any address in `linked`, or switch to X-Operator-Token
}
if (err.code === "token_expired") {
const verifyUrl = err.details.verify_url as string | undefined;
// surface verifyUrl to the user so they can re-verify
}
}
TypeScript types
The SDK exports all response types:
import type {
ReputationResponse,
AssessResponse,
} from "@agent-score/sdk";
Links