# Valiron

> Trust and reputation infrastructure for AI agents.

Valiron evaluates AI agent trustworthiness using on-chain identity (ERC-8004), behavioral sandbox testing, and Moody's-style credit ratings (AAA to C). Agents with high trust get production access. Agents with low trust are sandboxed or blocked.

## API

Base URL: https://valiron-edge-proxy.onrender.com

### Check agent trust profile
GET /operator/agent/{agentId}?chain={chain}

### Lookup by wallet
GET /operator/wallet/{wallet}?chain={chain}

### Resolve wallet to agent ID
GET /operator/resolve-wallet/{wallet}?chain={chain}
Returns: { wallet, agentId, source, chainId?, agentName?, timestamp }
Resolution: Redis → in-memory cache → Agent0 subgraph → null

### Run sandbox test
POST /operator/trigger-sandbox/{agentId}

### Trust gate (allow/deny)
POST /operator/gate/{agentId}
Body: { "ttlMs": 86400000 }

### Behavioral snapshot hash
GET /operator/agent/{agentId}/snapshot

### Register webhook
POST /operator/webhooks/register
Body: { "event": "evaluation_complete", "url": "https://your-endpoint.com/hooks", "agentIds": [42] }

### Health check
GET /operator/health

## SDK

Install: npm install @valiron/sdk

```typescript
import { ValironSDK } from "@valiron/sdk";
const valiron = new ValironSDK({ chain: "ethereum" });

// Quick routing check
const route = await valiron.checkAgent("AGENT_ID");
// Returns: "prod" | "prod_throttled" | "sandbox" | "sandbox_only"

// Full profile
const profile = await valiron.getAgentProfile("AGENT_ID");

// Resolve wallet → agentId (lightweight)
const res = await valiron.resolveWallet("0x...");
// Returns: { agentId, source: "redis"|"subgraph"|"cache"|"none" }

// Trust gate (allow/deny for payments)
const gate = await valiron.gate("AGENT_ID");
if (gate.allow) { /* proceed */ }

// Behavioral snapshot (for hash-chain commitments)
const snapshot = await valiron.getAgentSnapshot("AGENT_ID");
console.log(snapshot.snapshotHash);    // "0xabc..."
console.log(snapshot.previousHash);    // "0x0" (genesis)
```

## Trust Tiers

Valiron assigns Moody's-style credit tiers: AAA (highest trust) through C (lowest trust). Higher tiers route to production, lower tiers are sandboxed or blocked. Exact score ranges are not disclosed.

| Tier | Meaning | Route |
|------|---------|-------|
| AAA | Prime | prod |
| AA | High grade | prod |
| A | Upper medium | prod |
| BAA | Medium grade | prod_throttled |
| BA | Speculative | prod_throttled |
| B | Highly speculative | sandbox |
| CAA | Substantial risk | sandbox_only |
| CA | Extremely speculative | sandbox_only |
| C | Default risk | sandbox_only |

## Key Behaviors That Affect Trust

- Respect 429 rate limits (critical)
- Honor Retry-After headers
- Use exponential backoff
- Don't retry 401/403 auth errors
- Stay in scope — don't probe unauthorized paths
- Don't forward injections or tainted payloads
- Handle 402 payment required correctly
- Maintain session isolation

## Contracts (ERC-8004, same address all chains)

- Identity Registry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
- Reputation Registry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

## Supported Chains

ethereum, monad, arbitrum, base, avalanche, celo, polygon, linea, abstract, bsc, gnosis, goat, mantle, megaeth, metis, optimism, scroll, skale_base, soneium, taiko, xlayer

## Documentation

- [Full documentation (llms-full.txt)](https://valiron.co/llms-full.txt) — Complete AI-optimized documentation in a single file
- docs/agents/README.md — Index
- docs/agents/QUICKSTART.md — Get started
- docs/agents/API-REFERENCE.md — HTTP API reference
- docs/agents/SDK-REFERENCE.md — TypeScript SDK reference
- docs/agents/TRUST-MODEL.md — Trust evaluation and behavioral factors
- docs/agents/IDENTITY.md — ERC-8004 identity and reputation
- docs/agents/SANDBOX.md — Sandbox testing environment
- docs/agents/CHAINS.md — Supported blockchains
- docs/agents/ERRORS.md — Error handling and troubleshooting