@korateams/trust-sdk

Open-source client for the Global Commerce Index Trust API. Check the reputation, identity, and risk of any machine-payable entity, endpoint, or wallet in one line — before an agent pays it.

Install

npm install @korateams/trust-sdk

Usage

import { TrustLayer } from "@korateams/trust-sdk";

const trust = new TrustLayer({
  apiKey: process.env.TRUST_API_KEY!,
  baseUrl: "https://your-deployment.example.com/v1/trust",
});

const result = await trust.check({ endpoint: "https://api.example.com/rates" });

if (!result.found) {
  // Genuinely unknown — never treated as risky, only as "insufficient data."
  console.log("No history for this endpoint yet.");
} else if (result.recommendation === "block") {
  throw new Error(`Refusing to pay — risk flags: ${result.risk.flags.join(", ")}`);
} else if (result.recommendation === "review") {
  await askHumanBeforePaying(result);
} else {
  await pay();
}

You can also check by wallet address or by the Global Commerce Index's own entity id:

await trust.check({ wallet: "0xabc..." });
await trust.check({ entityId: "some-entity-uuid" });

Response shape

{
  found: true,
  entity: { name: "Example Data Ltd.", type: "business" },
  identity: { status: "verified", domainVerified: true, walletVerified: true },
  history: { firstSeen: "2024-05-11T...", observedAgeDays: 846, transactionsObserved: 184293, uniqueCounterparties: 42000 },
  reliability: { endpointUptime: 99.8, paymentSuccessRate: 99.6 },
  risk: { level: "low", flags: [] },
  reputation: { score: 93, band: "trusted" },
  recommendation: "allow", // "allow" | "review" | "block" | "unknown"
}

A genuinely unseen identifier returns a distinct shape instead of a fabricated low score — unknown is a real, separate answer from known and risky:

{ found: false, identifier: "https://never-seen.example.com", recommendation: "unknown" }

MCP tool

For MCP-compatible agent frameworks, this package also ships an MCP server exposing the same checks as tools (trust_check_endpoint, trust_check_wallet, trust_check_entity) an agent can call directly inside its own reasoning loop.

TRUST_API_KEY=... TRUST_API_BASE_URL=https://your-deployment.example.com/v1/trust \
  npx kora-trust-mcp

Add it to your MCP client config (e.g. Claude Desktop, Claude Code) pointing at that command with the same two environment variables set.

Getting an API key

If you've already claimed and verified your entity on the Global Commerce Index dashboard, generate your own key directly — no admin step required:

curl -X POST https://your-deployment.example.com/api/v1/entities/me/api-key \
  -H "Authorization: Bearer <your dashboard session token>"

Returned once, in plaintext — store it, it can't be retrieved again (calling this again rotates it). External consumers with no entity of their own (an agent platform, a wallet provider) are still admin-issued for now.