@valiron/sdk

Official TypeScript SDK for Valiron — Trust Infrastructure for AI Agent Systems

Valiron verifies AI agent trustworthiness using on-chain reputation (ERC-8004) and behavioral analysis. This SDK provides routing decisions based on agent trust scores, enabling you to protect infrastructure while maintaining service availability for verified agents.

Installation

npm install @valiron/sdk
# or
yarn add @valiron/sdk
# or
pnpm add @valiron/sdk

Getting Started

import { ValironSDK } from '@valiron/sdk';

const valiron = new ValironSDK();

// Quick routing check
const route = await valiron.checkAgent('25459');
if (route === 'prod') {
  // Allow full production access
}

// Or get the full trust profile
const profile = await valiron.getAgentProfile('25459');
console.log(profile.routing.finalRoute);          // 'prod'
console.log(profile.localReputation?.tier);        // 'AAA'
console.log(profile.onchainReputation.averageScore); // 92.5

Note: API key authentication is not yet enforced. The apiKey config field is reserved for future use.

Core Concepts

Route Decisions

The SDK returns one of four routing decisions:

| Route | Meaning | Trust Tiers | |-------|---------|-------------| | prod | Full access | AAA – BAA | | prod_throttled | Rate-limited access | BA – B | | sandbox | Agent under evaluation | Temporary | | sandbox_only | Access denied | CAA – C |

Trust Evaluation

Valiron evaluates agents using:

1. On-chain Reputation — ERC-8004 feedback submitted by other organizations
2. Behavioral Analysis — Sandbox evaluation of rate-limit compliance, error rates, and request patterns
3. Credit Rating — Moody's-style scoring system (AAA to C)

Architecture

Request → SDK.checkAgent() → Valiron Operator API → Route Decision → Your App

API Reference

Constructor

new ValironSDK(config?: ValironConfig)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | API key (reserved for future use) | | endpoint | string | https://valiron-edge-proxy.onrender.com | API endpoint URL | | timeout | number | 5000 | Request timeout (ms) | | debug | boolean | false | Enable debug logging |

checkAgent(agentId): Promise<RouteDecision>

Quick routing check — returns just the route decision string.

const route = await valiron.checkAgent('25459');
// route: 'prod' | 'prod_throttled' | 'sandbox' | 'sandbox_only'

getAgentProfile(agentId): Promise<AgentProfile>

Full trust profile combining on-chain identity, reputation, behavioral data, and routing.

const profile = await valiron.getAgentProfile('25459');

Response shape:

{
  agentId: string,
  identity: {
    agentId: string,
    wallet: string,
    tokenUri: string,
    name: string,
    image: string,
    description: string,
    endpoints: Record<string, string>,
    trustModels: string[],
  },
  onchainReputation: {
    count: string,
    averageScore: number,
    feedbackEntries: FeedbackEntry[],
    totalFeedback: number,
  },
  localReputation: {
    exists: boolean,
    score: number,
    tier: MoodysRating,
    riskLevel: 'GREEN' | 'YELLOW' | 'RED',
    graduated: boolean,
    metrics: BehavioralMetrics,
  } | null,
  routing: {
    finalRoute: RouteDecision,
    decision: string,       // human-readable explanation
    reasons: string[],      // array of reasoning steps
    signals: {
      onchain: { feedbackCount, averageScore, threshold },
      local:   { exists, graduated, tier, riskLevel, score },
    },
  },
  timestamp: string,
}

getWalletProfile(wallet): Promise<WalletProfile>

Reverse-lookup a wallet address to get its trust profile.

const profile = await valiron.getWalletProfile('0x52ce…');
console.log(profile.routing.finalRoute);

triggerSandboxTest(agentId): Promise<SandboxResult>

Run real sandbox tests against an agent and compute a Valiron score.

const result = await valiron.triggerSandboxTest('25459');
console.log(result.valironScore); // 95
console.log(result.tier);         // 'AAA'
console.log(result.riskLevel);    // 'GREEN'
console.log(result.mode);         // 'endpoint-probe' | 'sandbox-relay'
console.log(result.testSummary);
// { totalRequests, successCount, rateLimitCount, errorCount, avgLatencyMs }

Integration Examples

Express.js Middleware

import express from 'express';
import { ValironSDK } from '@valiron/sdk';

const app = express();
const valiron = new ValironSDK();

app.use('/api/protected/*', async (req, res, next) => {
  const agentId = req.headers['x-agent-id'] as string;
  if (!agentId) return res.status(400).json({ error: 'Missing x-agent-id' });

  const profile = await valiron.getAgentProfile(agentId);
  const { finalRoute } = profile.routing;

  if (finalRoute === 'prod' || finalRoute === 'prod_throttled') {
    (req as any).valironProfile = profile;
    return next();
  }

  return res.status(403).json({
    error: finalRoute === 'sandbox' ? 'Agent under evaluation' : 'Access denied',
    message: profile.routing.decision,
  });
});

Next.js Middleware

import { NextRequest, NextResponse } from 'next/server';
import { ValironSDK } from '@valiron/sdk';

const valiron = new ValironSDK();

export async function middleware(request: NextRequest) {
  const agentId = request.headers.get('x-agent-id');
  if (!agentId) {
    return NextResponse.json({ error: 'Missing x-agent-id' }, { status: 400 });
  }

  const route = await valiron.checkAgent(agentId);

  if (route === 'prod' || route === 'prod_throttled') {
    return NextResponse.next();
  }

  return NextResponse.json({ error: 'Access denied' }, { status: 403 });
}

export const config = { matcher: '/api/protected/:path*' };

x402 Payment Integration

Valiron integrates with x402 payment-gated APIs (e.g., Orthogonal). Verify trust before processing payments to prevent malicious agents from accessing paid endpoints.

const profile = await valiron.getAgentProfile(agentId);

if (profile.routing.finalRoute === 'sandbox_only') {
  return res.status(403).json({ error: 'Agent banned' });
}

// Trust-based pricing — better agents pay less
const pricing = { AAA: 5, AA: 5, A: 8, BAA: 10, BA: 25, B: 50 };
const tier = profile.localReputation?.tier || 'B';
const price = pricing[tier] || 50;

// Return x402 payment challenge
return res.status(402).json({
  accepts: [{ scheme: 'exact', maxAmountRequired: price, payTo: '0x…' }],
});

Moody's Credit Rating Tiers

| Tier | Score Range | Risk | Access Level | |------|-------------|------|--------------| | AAA | 98-110 | Prime | Full production | | AA | 92-97 | High grade | Full production | | A | 85-91 | Upper medium | Full production | | BAA | 75-84 | Medium | Full production (monitored) | | BA | 65-74 | Speculative | Throttled | | B | 50-64 | Highly speculative | Throttled | | CAA | 35-49 | Substantial risk | Sandbox only | | CA | 20-34 | Extremely speculative | Sandbox only | | C | 0-19 | Default risk | Sandbox only |

TypeScript Types

The SDK is fully typed. Import types as needed:

import {
  ValironSDK,
  RouteDecision,
  MoodysRating,
  RiskLevel,
  AgentProfile,
  WalletProfile,
  SandboxResult,
  AgentIdentity,
  OnchainReputation,
  LocalReputation,
  RoutingExplanation,
  BehavioralMetrics,
  FeedbackEntry,
  ValironError,
  ValironClient,
} from '@valiron/sdk';

Error Handling

import { ValironError } from '@valiron/sdk';

try {
  const profile = await valiron.getAgentProfile('123');
} catch (error) {
  if (error instanceof ValironError) {
    switch (error.code) {
      case 'TIMEOUT_ERROR':  // Request timed out
      case 'NETWORK_ERROR':  // Could not reach API
      case 'API_ERROR':      // Non-2xx response (check error.statusCode)
    }
  }
}

Additional Resources

• ERC-8004 Standard

Support

• Email: [email protected]

License

MIT © Valiron