@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/Solana), key-based identity for local/Web2 agents, behavioral sandbox testing, predictive risk forecasts, 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 on-chain agent is trusted
const route = await valiron.checkAgent("AGENT_ID");
// Returns: "prod" | "prod_throttled" | "sandbox" | "sandbox_only"

// Check a local/Web2/non-ERC-8004 agent by persistent key address
const keyProfile = await valiron.getKeyAgentProfile("0xAgentAddress");
console.log(keyProfile.route);

// 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", "self", and "icebreaker"
}));

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

No API key required for read operations.

Use x-agent-id for ERC-8004/Solana agents. Use x-agent-address plus Valiron challenge-response for local, Web2, or non-ERC-8004 agents. Agents can follow the hosted identity skill at https://www.valiron.co/auth.md.

Additional Features

• Auto-Sandbox — Middleware automatically evaluates new agents (on-chain and key-based) on their first gated request
• Predictive Risk — Dashboard/API forecasts whether an observed agent is improving, stable, or becoming riskier before the next action
• 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
• Self — Create Self Enterprise sessions and store signed eligible-human webhook results
• 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