@valiron/sdk

Official TypeScript SDK for Valiron — Trust & Reputation Middleware for API Protection

Protect your API endpoints from bad or malicious AI agents. Valiron evaluates incoming agents using on-chain identity (ERC-8004), behavioral sandbox testing, and Moody's-style credit ratings — so you can allow trusted agents and block risky ones automatically.

Installation

npm install @valiron/sdk

Quick Start

import { ValironSDK, createValironGate } from "@valiron/sdk";

const valiron = new ValironSDK({ chain: "ethereum" });

// Check if an agent is trusted
const route = await valiron.checkAgent("AGENT_ID");
// Returns: "prod" | "prod_throttled" | "sandbox" | "sandbox_only"

// Gate an agent — allow/deny decision
const gate = await valiron.gate("AGENT_ID");
if (gate.allow) { /* serve the request */ }

// One-line Express middleware — blocks untrusted agents automatically
app.use("/api/paid", createValironGate({ sdk: valiron }));

// Optional: choose endpoint-specific trust signals
app.use("/api/paid", createValironGate({
  sdk: valiron,
  trustSignals: ["8004", "sandbox"], // Pro can add "world" and "icebreaker"
}));

// Fastify, Next.js, and generic middleware also available
// See SDK Reference for valironFastifyPlugin, createValironNextMiddleware, valironGateCheck

No API key required for read operations.

Additional Features

• Auto-Sandbox — Middleware automatically evaluates new agents (on-chain and key-based) on their first gated request
• Proxy Gateway (Pro) — Forward requests through Valiron's edge proxy with SSRF protection
• Key-Based Agents — Support Web2 agents via EIP-191 challenge-response (auto-detected, auto-sandboxed)
• World ID — Verify agent-human linkage via Worldcoin proof-of-personhood
• Telemetry — Optional anonymous usage metrics (disable with telemetry: { enabled: false })

Cleanup

Call dispose() when shutting down long-running servers:

await valiron.dispose();

Documentation

Full SDK reference, API docs, trust model, and integration guides:

• valiron.co/docs — interactive documentation
• SDK Reference — all methods, options, and response types
• API Reference — HTTP endpoints
• Quickstart — get started in 2 minutes
• llms.txt — compact reference for LLM/agent integration
• Install agent skill: npx @valiron/skill

Support

• Email: [email protected]
• Telegram: https://t.me/valirongrade

License

MIT © Valiron