KnowYourModel SDK

@nexartis/knowyourmodel-sdk

The official TypeScript SDK for KnowYourModel — trust scoring, agent discovery, cryptographic receipts, and usage-proof voting for the NANDA ecosystem. Zero framework dependencies, runs anywhere with a fetch implementation.

Installation

# GitHub Packages (scoped)

npm install @nexartis/knowyourmodel-sdk

Quick Start

// Import the client import { KymClient } from '@nexartis/knowyourmodel-sdk/core'; // Initialize const kym = new KymClient({ apiUrl: 'https://knowyourmodel.ai', apiKey: 'your-api-key', // for voting signingKey: 'base64-ed25519-priv', // for receipts publicKey: 'base64-ed25519-pub', // for verification }); // Search agents & models const results = await kym.search('code generation'); // Submit a cryptographic receipt await kym.signAndSubmitReceipt({ receipt_id: crypto.randomUUID(), entity_id: 'agent-xyz', orchestrator_id: 'my-orchestrator', timestamp: Date.now(), success: true, }); // Cast a usage-proof vote await kym.castVote({ entity_id: 'agent-xyz', receipt_id: 'receipt-abc', vote_type: 'up', voter_id: 'voter-1', vote_source: 'agent', });

Configuration

Property	Type	Description
apiUrl	string	KYM API base URL (required)
apiKey	string?	Bearer token for authenticated endpoints (voting)
signingKey	string?	Ed25519 private key (base64 DER/PKCS8) for receipt signing
publicKey	string?	Ed25519 public key (base64 DER/SPKI) for verification
npAgentId	string?	NP agent identifier for dual-rail (x402) payments
npSigningFn	(payload: string) => string	NP signing function for payment payloads
verbose	boolean?	Enable debug logging
retryConfig	RetryConfig?	Custom retry settings (maxRetries, baseDelayMs, maxDelayMs, timeoutMs)

API Reference

Registries (Token-Curated)

listRegistries(params?)

List or search registries. Filter by q, capability, with pagination.

Returns: KymRegistryListResponse

getRegistry(slugOrId)

Get a single registry by slug or ID, including its entries.

Returns: KymRegistryDetailResponse

createRegistry(data)

Create a new TCR. Supports 402 payment challenges with automatic NP retry.

Returns: { registry: KymRegistry }

createRegistryEntry(registryId, data)

Add an entity to a registry with optional rank, stake, and rationale.

Returns: { entry: KymRegistryEntry }

listRegistryEntries(registryId, filters?)

List entries in a registry. Filter by status, entityType, protocol, capabilities.

Returns: RegistryEntriesResponse

listCategories()

List all registry categories with skill IDs and registry counts.

Returns: CategoriesResponse

Cryptographic Receipts

signAndSubmitReceipt(payload)

Sign a usage receipt with Ed25519 and submit it. Requires signingKey and publicKey in config.

Returns: ReceiptResult

submitReceipt(payload, signature, publicKeyOverride?)

Submit a pre-signed receipt. Use when signing happens externally (e.g. hardware key).

Returns: ReceiptResult

getEntityReceipts(entityId, limit?)

Retrieve receipts for an entity. Default limit: 50.

Returns: ReceiptRecord[]

Usage-Proof Voting

castVote(votePayload)

Cast an up/down vote backed by a usage receipt. Requires apiKey.

Returns: VoteResult

getVoteStats(entityId)

Get aggregated vote statistics (upvotes, downvotes, total, score) for an entity.

Returns: VoteStats

Search & Discovery

search(query, page?, limit?)

Unified search across registries, entities, and skills. Returns matched skills with keyword highlights.

Returns: SearchResponse

listEntities(filters?)

List entities (agents + models). Filter by type, provider, sort, verification type.

Returns: EntityListResponse

listAgents(filters?)

List A2A agents. Filter by protocol, capabilities, extensions, I/O modes.

Returns: AgentListResponse

Entity Inspection

getEntity(entityId)

Get full entity detail including skills, registries, and recent receipts.

Returns: KymEntityDetail

getAgent(entityId)

Get A2A agent detail with protocol info, tools, and security schemes.

Returns: AgentDetail

getAgentCard(entityId)

Retrieve the agent's A2A agent card (JSON-LD format).

Returns: Record<string, unknown>

getTrustBadge(entityId)

Get the trust badge and reputation data for an entity.

Returns: TrustBadge

getAgentFacts(entityId)

Get W3C Verifiable Credential with agent facts (trust, capabilities, compliance).

Returns: AgentFactsCredential

Signing Utilities

signPayload(payload)

Sign an arbitrary JSON payload with the configured Ed25519 key.

Returns: string (base64 signature)

verifySignature(payload, signatureBase64, publicKeyOverride?)

Verify an Ed25519 signature against a payload.

Returns: boolean

Health

checkHealth()

Full health check with DB, KV, and NANDA subsystem status.

Returns: KymHealthStatus

isHealthy()

Quick boolean health check. Never throws.

Returns: boolean

402 Payment Challenges

Write operations (createRegistry, createRegistryEntry) may return a 402 Payment Required challenge. If npAgentId and npSigningFn are configured, the SDK automatically retries with NP payment headers. Otherwise, the challenge is thrown as a KymError with the full challenge payload attached.

GitHub Repository

View the source, report issues, and contribute.

View on GitHub