TypeScript SDK

@samvad-protocol/sdk — the reference implementation of the SAMVAD protocol.

Installation

npm install @samvad-protocol/sdk zod

• Package: @samvad-protocol/sdk
• Node: 20+
• Module format: ESM-only ("type": "module")
• Dependencies: fastify, zod, @noble/ed25519, jose

What the SDK handles automatically

You write a handler. The SDK handles everything else:

Concern	What the SDK does
Ed25519 keys	Generates, persists, and loads keypairs from .samvad/keys/
Message signing	RFC 9421 HTTP Message Signatures (Ed25519 + Content-Digest) on every envelope
Signature verification	Verifies every inbound signature against the sender’s card
Replay prevention	Tracks nonces in a 5-minute window
Rate limiting	Per-sender sliding-window request limits + daily token budgets
Input validation	Validates payloads against your Zod schema before the handler runs
Agent card	Generates and serves /.well-known/agent.json from your config
Standard endpoints	Serves /agent/intro, /agent/health, task polling, SSE
Delegation	Issues and verifies EdDSA JWT delegation tokens (RFC 8693)
Tracing	Generates and propagates OpenTelemetry-compatible trace/span IDs

Core API surface

import {
  Agent,          // Build and serve an agent
  AgentClient,    // Call remote agents
  SamvadError,    // Protocol error class
  ErrorCode,      // Error code constants

  // Signing (RFC 9421)
  signRequest, verifyRequest, computeContentDigest, parseKeyId,

  // Keys
  generateKeypair, saveKeypair, loadKeypair, encodePublicKey, decodePublicKey,

  // Nonce replay protection
  NonceStore,

  // Injection scanning
  scanObjectForInjection, wrapWithContentBoundary,

  // Verify middleware (for Next.js / serverless agents)
  createVerifyMiddleware,

  // Types
  AgentCard, SkillDef, MessageEnvelope, ResponseEnvelope,
  TaskRecord, TaskStatus, TrustTier, CommunicationMode,
  SkillContext, PublicKey, RateLimit, Keypair,
  RequestSignatureHeaders, NonceCheckResult,
  VerifyMiddlewareConfig, VerifiedRequest, VerifyError, VerifyResult,
} from '@samvad-protocol/sdk'

The signing, key management, nonce store, and injection scanner modules are exported for use in custom agent implementations that don’t use the Agent class (e.g. Next.js API routes, serverless functions).

Building agents without Fastify

The Agent class uses Fastify under the hood. If you’re building on Next.js, Express, or serverless functions, use createVerifyMiddleware instead — it gives you the full protocol verification pipeline (nonce, rate limit, signature, trust tier) as a framework-agnostic function:

import { createVerifyMiddleware } from '@samvad-protocol/sdk'

const verify = createVerifyMiddleware({
  agentId: 'agent://my-agent.com',
  skills: myCard.skills,
  rateLimiter: (ip) => ({ allowed: true }), // plug in your own
})

// In any route handler (Next.js, Express, etc.):
const result = await verify('POST', '/agent/message', bodyBytes, req.headers, clientIp)
if (!result.ok) {
  // result.error has { status, code, message }
  return Response.json(result.error, { status: result.error.status })
}
const { envelope, spanId } = result.data
// envelope is a verified MessageEnvelope — handle the skill call

This is what the Scout, Claw, and Research agents use internally.

Next steps

Building Agents

Skills, trust tiers, rate limits, async mode.

Calling Agents

Sync calls, async tasks, SSE streaming.

Delegation

JWT delegation tokens for multi-agent chains.

npm

View on npm.