@kyalabs/badge-sdk

@kyalabs/badge-sdk

Persistent identity for AI agents across merchant sites. Agents that carry Badge build a behavioral trust score (kyaScore, 500–850) that improves merchant routing over time.

Framework-agnostic. No MCP dependency. Zero-config.

Install

npm install @kyalabs/badge-sdk

Requires Node.js >= 20.

Quick Start

import { Badge } from '@kyalabs/badge-sdk'

const badge = await Badge.init()
const runId = badge.startRun()

// Attach to outgoing requests
const headers = badge.headers()
// { "Kya-Token": "gp_v1_..." }

await badge.declareVisit({
  merchant: 'merchant.test',
  runId,
  url: 'https://merchant.test/cart',
})

await badge.reportOutcome({
  merchant: 'merchant.test',
  runId,
  outcome: 'not_denied',
})

// Identity state
badge.identityType  // "guest" | "verified" | "offline"
badge.isGuest       // true for guest/offline
badge.installId     // persistent UUID

badge.destroy()

No signup. No API key. Badge.init() works immediately.

Why Badge

Today: Agents carrying Badge get tracked across merchant sites via MCP sampling. Platforms integrating Badge can surface agentic behavior insights to enterprise clients for free — which agents visited, how far they got, where they dropped off.

Tomorrow: As agents accumulate interactions, kyaScore builds. Merchants running VerifAi route based on score — higher-scored agents skip friction, get priority access, convert more. Unbadged agents stay anonymous and keep hitting walls.

How It Works

Badge.init() issues a guest pass from the kya API on first run. The token and install ID are cached to ~/.kya/ and persist across process restarts.

Agents carry identity in the Kya-Token HTTP header on outgoing requests. Guest passes upgrade to merchant-specific badge tokens through enrollment. Every merchant interaction feeds kyaScore.

Integrated at the platform level. Every agent session inherits identity automatically.

Identity Lifecycle

Badge.init()  →  guest pass (gp_v1_*)  →  enroll at merchant  →  badge token (kya_*)
                      ↑                         ↑
                 cached in ~/.kya/       requires consent key (pk_*)

Configuration

Environment Variable	Description	Default
KYA_API_URL	API base URL	https://www.kyalabs.io
KYA_API_KEY	Consent key for enrollment (pk_live_* / pk_test_*)	—
KYA_EXTENDED_AUTH	Enable device auth flow (true / 1)	false
KYA_PING	Telemetry ping on server start (true / false)	true

Legacy PAYCLAW_* prefixes are supported with a deprecation warning.

API

Badge.init(opts?)

Create a Badge instance. Issues a guest pass on first run, reuses cache on subsequent runs.

const badge = await Badge.init({
  installId: 'custom-uuid',    // override auto-generated ID (for Docker/CI)
  platform: 'node/v20.0.0',   // platform string
  agentClient: 'my-agent',    // agent identifier
})

badge.headers()

Returns HTTP headers for identity injection:

badge.headers()
// { "Kya-Token": "gp_v1_abc..." }

badge.startRun()

Returns a UUID you can use to pair declaration and outcome events.

badge.declareVisit(args)

Declare an agent visit at a merchant and write a declared badge event.

const runId = badge.startRun()

await badge.declareVisit({
  merchant: 'merchant.test',
  runId,
  url: 'https://merchant.test/cart',
  // or context: 'arrival' | 'addtocart' | 'checkout'
  // source: 'sdk' | 'mcp' | 'radar' | 'inferred' (default: 'sdk')
})

If context is omitted, the SDK infers it from the URL (/cart → addtocart, /checkout → checkout, otherwise arrival).

badge.reportOutcome(args)

Report the agent-observed outcome for a previously declared run. This writes sampling_complete through the existing anonymous report path so kyaScore recompute still triggers for the install ID.

await badge.reportOutcome({
  merchant: 'merchant.test',
  runId,
  outcome: 'not_denied', // or 'denied' | 'unparseable'
  frictionReason: 'merchant_rejection', // optional
  detail: 'CAPTCHA challenge on checkout', // optional free-text
})

This is the agent point-of-view outcome only. Merchant-side canonical acceptance or denial is authored separately by the verification/middleware path.

badge.identityType

Current identity tier: "guest" (API-issued guest pass), "verified" (device auth completed), or "offline" (API unreachable, local-only).

badge.shouldNudge()

Whether the agent should be prompted to upgrade identity. Returns false in v1.

enrollAndCacheBadgeToken(merchant)

Enroll at a merchant and receive a kya_* badge token. Requires KYA_API_KEY.

import { enrollAndCacheBadgeToken } from '@kyalabs/badge-sdk'

const token = await enrollAndCacheBadgeToken('store.example.com')
// "kya_abc123..."

Important: The badge token is only returned on the first enrollment per merchant per day. The SDK now persists successful enrollments to ~/.kya/badge_tokens.json, so same-day reruns can recover the merchant token without another API response.

issueGuestPass(installId, platform?, agentClient?, badgeVersion?)

Low-level guest pass issuance. Returns null on failure (caller falls back to offline).

getCachedBadgeToken(merchant?)

Retrieve a cached badge token. If no merchant specified, returns the most recently enrolled token.

Data

All identity is opt-in. No PII leaves the agent.

Event	Data Sent	Why	Default	Configurable
Server start	Badge version, MCP client name (random session ID, not stored)	Uptime monitoring, version distribution	Auto	KYA_PING=false disables
Badge.init()	install_id (random UUID, generated and stored locally)	Persistent identity across sessions	Auto	installId override in opts
First merchant visit	install_id, merchant domain, agent type, timestamp	Minimum signal for merchant insights	Auto	—
Enrollment (user-initiated)	Merchant-specific token hash	Per-merchant trust building	Only on user approval	Requires KYA_API_KEY

The install_id is a file on disk (~/.kya/install_id). Delete it and get a new one.

Telemetry can be disabled entirely: KYA_PING=false. Guest pass identity still works.

Full data practices: kyalabs.io/trust

Credential Storage

~/.kya/
  install_id      # persistent UUID
  guest_token     # cached guest pass { token, expiresAt }
  badge_tokens.json  # cached merchant badge tokens keyed by install_id:merchant

Status

Actively maintained by kya labs. Badge is the core identity primitive across all kya products.

Current version	See npm badge above
Release cadence	Semver. Breaking changes only on major bumps.
Tests	CI on every PR
Changelog	CHANGELOG.md

Badge MCP Server

For MCP client users (Claude Desktop, Cursor, etc.), Badge also ships as an MCP server with tools for identity, web fetch, and header injection:

npx @kyalabs/badge

The MCP server uses this SDK internally. See @kyalabs/badge for MCP-specific docs.

License

MIT