BADGE SDK · RUN-LEVEL PROOF
Prove your agents work.
Your agents are a black box to your B2B clients. Badge gives them a run-level report: every merchant visited, every outcome, every friction point. Plus portable trust history your clients can inspect. Install in one line, no signup.
import { Badge } from "@kyalabs/badge-sdk";
// 1. Initialize. Issues a guest pass on first run, reuses it after
const badge = await Badge.init();
const runId = badge.startRun();
// 2. Declare a visit at a merchant
await badge.declareVisit({
merchant: "store.example.com",
runId,
url: "https://store.example.com/cart",
});
// 3. Report what happened
await badge.reportOutcome({
merchant: "store.example.com",
runId,
outcome: "not_denied",
});QUICK START
How the report gets made.
1. Badge.init()
await Badge.init()issues a guest pass on first run, persists it locally, and gives every trip a stable identity to build on.2. declareVisit()
badge.declareVisit()records the merchant, the URL, and the run that just happened. This is the start of the report your client will later ask for.3. reportOutcome()
badge.reportOutcome()closes the loop with what happened at the merchant. Success, failure, and friction all become part of the same run-level trail.
{
merchant: "store.example.com", // Domain the agent hit
runId: "a1b2c3…", // Ties declare + outcome to one trip
context: "arrival | addtocart | checkout", // Where in the flow
outcome: "not_denied | denied | unparseable", // Agent's POV
recordedAs: "declared | reported | offline", // Server confirmation
source: "sdk | mcp | radar | inferred", // Event authorship
install_id: "uuid…", // Persistent agent identity
}These fields land in an append-only event log. Your B2B client sees them on the report you send.
WHAT YOU GET
Three concrete payoffs.
Identity that persists
Across sessions, across processes, across merchants.
Badge.init() issues a guest pass that survives process restarts. Upgrade to a full badge token via enrollment; the same install_id anchors both. Agents get recognized everywhere they go, not re-keyed on every run.
const badge = await Badge.init(); console.log(badge.identityType); // "guest" | "badge" | "auth"
Cross-merchant trust score
kyaScore: a portable reputation score most stacks can’t produce.
Every reportOutcome call triggers a server-side score recompute. Over time, agents build a portable reputation (500–850 range) that merchants verify through the verify endpoint.
{ "score": 712, "tier": "standard",
"assurance_level": "medium" }Provable trip data
The report your B2B clients are asking for.
Every visit and outcome writes to an append-only event log, grouped by runId. Each event carries recordedAs (server-confirmed vs offline) and source (who authored it).
GET /api/badge/log?install_id=…
WHAT’S LIVE · WHAT’S NEXT
Where the SDK is honest.
Badge is deployed, stable, and tested. But it’s also early. A few things haven’t shipped yet, and you should know about them before you build on top of us.
Live today
3-method SDK (init, declareVisit, reportOutcome) with zero runtime deps
Guest pass → badge token identity ladder, persisted to disk
Offline fallback: SDK never throws on network failure
recordedAs confidence on every event (declared | reported | offline)
Cross-merchant kyaScore, recomputed on every outcome
UCP Credential Provider (io.kyalabs.common.identity), OAuth 2.0 (RFC 8628)
TypeScript types ship in package, CHANGELOG.md in tarball, 140 unit tests
Coming next
Multi-tenant binding (agentId, tenantId, environment)
Escape hatch: Badge.init({ installId: `${tenantId}-${agentId}` }). Compose your own string.
ETA: v1.5
Self-serve reporting dashboard
Escape hatch: Share your install IDs with us; CSV within 24 hours
ETA: Q2 2026
meta.ucp-agent request metadata slot (UCP PR #156)
Escape hatch: Checkout-payload entry under io.kyalabs.common.identity works today
ETA: Depends on UCP spec
ARCHITECTURE
Standards-native, not proprietary.
Badge is a UCP Credential Provider registered under io.kyalabs.common.identity. Tokens are obtained via RFC 8628 Device Authorization Grant, introspected via RFC 7662, and verified against published JWKS keys. Merchants verify Badge JWTs locally. No server-to-server call to kya required for cryptographic verification.
Server-side, every event writes to an append-only log with atomic enroll-declare. Session tokens are single-use with a 15-minute TTL. Tokens are stored as SHA-256 hashes; we never persist plaintext. Zero runtime dependencies in the SDK means nothing you install comes with baggage. The tarball is dist/, README.md, LICENSE.
PARTNERSHIP
Discuss how the Badge SDK can help your app.
If your agents run at scale across merchants, and your clients ask what your agents did last week, we’d like to talk.
Pricing
Badge SDK is free. Multi-tenant binding is included. Advanced reporting is priced on request.
NEXT STEPS
Three steps from here.
01
Install
Start with the install command, then run node examples/demo.mjs from the SDK repo to watch events land within minutes.
03
Export your data
Once you’ve run a few trips, email us your install IDs. We’ll ship CSV or API export within 24 hours. Self-serve dashboard is in progress.