AgentScore SDK (TypeScript)

npm install @agent-score/sdk

import { AgentScore } from "@agent-score/sdk";

const client = new AgentScore({ apiKey: process.env.AGENTSCORE_API_KEY });

// On-the-fly assessment with decision
const assessment = await client.assess("0xdb5aa553feeb2c3e3d03e8360b36fb0f7e480671", {
  policy: { require_kyc: true },
});

if (assessment.decision === "deny") {
  console.log("Denied:", assessment.decision_reasons);
}

new AgentScore(options: {
  apiKey: string;
  baseUrl?: string;   // default: "https://api.agentscore.com"
  timeout?: number;   // default: 10000 (ms)
  userAgent?: string; // custom prefix prepended to default UA, e.g. "myapp/1.0"
})

const client = new AgentScore({ apiKey, userAgent: "myapp/1.0" });
// Outbound UA: "myapp/1.0 (@agent-score/sdk@x.y.z)"

// With wallet address
const result = await client.assess("0x1234...", {
  policy: { require_kyc: true },
  chain: "base",
});

// 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);
}

const result = await client.assess("0xclaimed...", {
  signer: { address: "0xsigner...", network: "evm" },
  policy: { require_sanctions_clear: true },
});

// Wallet-binding verdict
if (result.signer_match?.kind === "wallet_signer_mismatch") {
  console.log("Mismatch:", result.signer_match.expected_signer, "vs", result.signer_match.actual_signer);
}

// OFAC SDN wallet-address verdict; discriminated union
// { status: 'clear' } | { sanctioned: true, ofac_label, sdn_uid, listed_at } | { status: 'unavailable' }
if (result.signer_sanctions && "sanctioned" in result.signer_sanctions) {
  console.log("OFAC hit:", result.signer_sanctions.ofac_label, result.signer_sanctions.sdn_uid);
}

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);
  }
}

// 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

// Registration-only session: the buyer signs in with an AgentScore account, no identity documents.
await client.createSession({ kind: "sign_in" });

// 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);

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
});

const result = await client.assess("0x1234...", { policy: { require_kyc: true } });
if (result.quota?.limit && result.quota.used != null) {
  const pct = result.quota.used / result.quota.limit;
  if (pct >= 0.95) {
    log.warn(`AgentScore quota at ${Math.round(pct * 100)}%; resets at ${result.quota.reset}`);
  }
}

import {
  AgentScoreError,
  InvalidCredentialError,
  PaymentRequiredError,
  QuotaExceededError,
  RateLimitedError,
  TimeoutError,
  TokenExpiredError,
} from "@agent-score/sdk";

try {
  const result = await client.assess(null, {
    operatorToken: "opc_...",
    signer: { address: "0xs", network: "evm" },
  });
} catch (err) {
  if (err instanceof TokenExpiredError) {
    // 401 token_expired; credential revoked or TTL-expired. The 401 body carries an
    // auto-minted verification session so the agent recovers without an API key.
    console.log("verify_url:", err.verifyUrl, "session_id:", err.sessionId, "poll_secret:", err.pollSecret);
  } else if (err instanceof InvalidCredentialError) {
    // 401 invalid_credential; operator_token doesn't exist (typo, never minted).
  } else if (err instanceof QuotaExceededError) {
    // 429 quota_exceeded; wait for the quota reset window; don't retry.
  } else if (err instanceof RateLimitedError) {
    // 429 rate_limited; the SDK already waited out Retry-After and retried once, so back off before trying again.
  } else if (err instanceof PaymentRequiredError) {
    // 402; vendor tier misconfig.
  } else if (err instanceof AgentScoreError) {
    // Anything else: 4xx/5xx + network failures wrap to AgentScoreError with code "network_error"/"timeout"/etc.
    console.log(err.code, err.message, err.status);
  }
}

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
  }
}

import type {
  AssessResponse,
} from "@agent-score/sdk";