# Valiron

> Protect your API endpoints from bad or malicious AI agents.

Valiron is trust and reputation middleware for API sellers. It evaluates incoming AI agents using on-chain identity (ERC-8004/Solana), key-based identity for local/Web2/non-ERC-8004 agents, behavioral sandbox testing, and Moody's-style credit ratings (AAA to C). Trustworthy agents get production access. Risky agents are throttled, sandboxed, or blocked — automatically.

## Identity Paths

On-chain agents use x-agent-id and GET /operator/agent/{agentId}. The agentId is an ERC-8004 token ID, Solana Metaplex Core asset pubkey, or supported indexed Solana ID.

Local, Web2, and non-ERC-8004 agents use x-agent-address plus challenge-response auth. Do not send a local agent name to /operator/agent/{agentId}. Generate or reuse a persistent Ethereum-style keypair, request POST /operator/key/{agentAddress}/challenge, sign the challenge, verify with POST /operator/key/verify, then use x-agent-address and x-agent-session on gated requests. Agents can follow https://www.valiron.co/auth.md.

## 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 (on-chain agent)
POST /operator/trigger-sandbox/{agentId}

### Run sandbox test (key-based agent)
POST /operator/trigger-sandbox-key/{agentAddress}

### Key-based agent challenge
POST /operator/key/{agentAddress}/challenge

### Verify key-based agent
POST /operator/key/verify

### Key-based agent profile
GET /operator/key/{agentAddress}

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

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

### Liveness check (Solana only)
GET /operator/agent/{agentId}/liveness?chain=solana

### 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)

// Sandbox evaluation for key-based agent
const keyResult = await valiron.triggerKeyAgentSandbox("0x1234...abcd");
console.log(keyResult.tier);           // "A"
```

Auto-sandbox: Middleware automatically triggers sandbox evaluation for new agents (on-chain with totalFeedback=0, or key-based with no score). Returns 403 with { error: "Agent pending evaluation", retryAfterMs: 30000 }.

## API Scaffolding

Valiron's core product is middleware deployed within the API seller's backend. API Scaffolding is a separate product for organizations that require a hosted, agent-facing wrapper URL for an existing HTTPS API. It can serve as an evaluation path before adopting a first-party backend integration protected by Valiron middleware. Operators create wrappers in the dashboard under Make API Agent-Ready or via POST /operator/endpoints. Agents call:

GET/POST/etc /wrap/{operatorId}/{path}

Wrapper config fields: path, method, targetUrl (upstream API base URL), pricePerCall, paymentProtocol ("x402" or "mpp"), paymentNetwork ("eip155:8453", "eip155:84532", "tempo:4217", or "tempo:42431"), payoutAddress, trustEnabled, rateLimit, upstreamAuthType, upstreamAuthHeader, upstreamAuthSecret.

Free wrappers (pricePerCall=0) forward directly to targetUrl. x402 paid wrappers return 402 with x402 payment challenge and require retry with X-PAYMENT. MPP paid wrappers return 402 with WWW-Authenticate: Payment and require retry with Authorization: Payment. Trust-enabled wrappers require x-agent-id or x-agent-address/session headers and deny untrusted agents before forwarding.

## Operator SDK (ValironOperator)

For API sellers who want to monetize endpoints. Requires a `val_op_` API key from the dashboard.

```typescript
import { ValironOperator } from '@valiron/sdk';

const operator = new ValironOperator({ apiKey: 'val_op_xxxx' });

// Express: one line to monetize an endpoint
app.use('/api/inference', operator.paywall({
  pricePerCall: 0.05,
  minTrustScore: 45,
}));

// Fastify: register as plugin
app.register(operator.fastifyPaywall({
  pricePerCall: 0.10,
  prefix: '/api',
}));

// req.valiron is populated with gate result + pricing
app.post('/api/inference', (req, res) => {
  console.log(req.valiron.tier);         // 'AAA'
  console.log(req.valiron.pricePerCall); // 0.05
  res.json({ result: 'output' });
});
```

PaywallConfig options: pricePerCall (number, required), minTrustScore (number, default 45), ttlMs (number, default 86400000), onDeny (callback), onAllow (callback).

## Trust Model

Valiron evaluates agents using four independent trust signals:

1. **On-Chain Reputation (ERC-8004)** — Feedback from other agents/operators (0-100 per review).
2. **Behavioral Sandbox** — Simulated API interactions testing rate-limit compliance, auth behavior, payment handling, injection safety, PII handling, session isolation, and task completion. Exact weights are proprietary.
3. **World ID** — Proof-of-personhood via Worldcoin. Verification levels: orb (biometric, highest boost), device (passkey), phone (SMS).
4. **Icebreaker** — Human attestation via Ethereum Attestation Service (EAS) on Base. A human attests this is their "designated agent."

## 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
- 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

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

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

### Solana (QuantuLabs 8004-solana)

- Identity Registry: 8oo4dC4JvBLwy5tGgiH3WwK4B9PWxL9Z4XjA2jzkQMbQ
- Reputation Registry (ATOM): AToMw53aiPQ8j7iHVb4fGt6nzUNxUhcPc3tbPBZuzVVb

## Supported Chains

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

## Plans & Limits

Free: 3 gated endpoints, 5 sandbox tests/day. Pro: unlimited endpoints, unlimited sandbox, webhooks, proxy gateway, analytics, evaluation history, custom tier thresholds. Pro requires operator API key (val_op_ prefix).

## Proxy Gateway (Pro)

Forward requests through Valiron's edge proxy with automatic trust gating, logging, and SSRF protection (blocks private IPs, metadata endpoints). Use `valiron.proxy({ agentId, targetUrl, method?, headers?, body? })`.

## Key-Based Agents

Web2 agents without on-chain identity use EIP-191 challenge-response via `x-agent-address` header. SDK auto-detects. Returns KeyAgentProfile with agentAddress, verified, score, tier, riskLevel, route, icebreaker, reasons, timestamp.

New key agents are automatically sandbox-evaluated on first gated request. Middleware allows key agents when verified and score >= minScore. Use `triggerKeyAgentSandbox(address)` or `POST /operator/trigger-sandbox-key/{address}` to trigger manually.

## World ID Methods

- verifyWorldId(agentId, proof) — Submit World ID proof
- getWorldIdStatus(agentId) — Check verification status
- getWorldIdProfile(agentId) — Full World ID profile

## Telemetry

Opt-in anonymous usage metrics. Disable with `telemetry: { enabled: false }`. Supports custom sampleRate (0–1) and custom handler function.

## Middleware Error Responses

All middleware returns: 401 (no agent ID), 403 (denied by trust gate), 503 (service unavailable). Fail-closed: never allows unverified agents through.

## Solana Notes

- Use chain: "solana" in SDK or ?chain=solana query parameter
- Agent IDs are base-58 Metaplex Core asset pubkeys or sequential integers (1, 2, 42)
- Wallet addresses are base-58 Solana public keys (not 0x-prefixed)
- Identity and reputation provided by QuantuLabs (separate from EVM 8004 contracts)
- Extra reputation fields: trustTier, qualityScore, confidence, riskScore, uniqueCallers
- Liveness endpoint: GET /operator/agent/{agentId}/liveness?chain=solana
- Feedback write-back: Valiron scores written on-chain via giveFeedback() (requires SOLANA_FEEDBACK_KEYPAIR env var)

## Documentation

- [Full documentation (llms-full.txt)](https://www.valiron.co/llms-full.txt) — Complete AI-optimized documentation in a single file
- [auth.md](https://www.valiron.co/auth.md) — Agent identity skill (create keypair, authenticate, manage sessions)
- docs/agents/README.md — Index
- docs/agents/QUICKSTART.md — Get started
- docs/agents/AGENT-READY-APIS.md — Hosted x402/MPP wrappers for existing APIs
- docs/agents/DASHBOARD.md — Operator Dashboard (manage endpoints, keys, analytics, playground)
- 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

## Operator Dashboard

Dashboard URL: https://www.valiron.co/dashboard (JWT-authenticated)

### Dashboard Features
- Overview: revenue, calls, agents, latency stats + quick start guide
- Agents: view every agent that called your API, drill into per-agent detail
- Analytics: revenue charts (7/30/90 days), top endpoints, today's stats
- Call Logs: paginated log with time/agent/chain/endpoint/status/cost/latency filters
- API Keys: generate, copy, and revoke operator API keys (val_op_ prefix)
- Make API Agent-Ready: create hosted wrappers with upstream base URL, price, x402/MPP protocol, optional trust, rate limit, upstream auth
- Playground: test how agents at different trust levels are evaluated (dry-run or live)
- Settings: update name, view plan and fee rate
- Admin (admin-only): platform stats, all operators

### Dashboard API Endpoints (JWT-authenticated)

POST /operator/register
Body: { "email": "...", "password": "...", "name": "..." }

POST /operator/login
Body: { "email": "...", "password": "..." }

GET /operator/me
PATCH /operator/me
Body: { "name": "..." }

GET /operator/keys
POST /operator/keys/rotate
Body: { "label": "..." }
DELETE /operator/keys/{keyId}

GET /operator/endpoints
POST /operator/endpoints
Body: { "path": "/weather", "method": "GET", "pricePerCall": 0.001, "description": "...", "rateLimit": 60, "targetUrl": "https://api.example.com", "paymentProtocol": "x402", "paymentNetwork": "eip155:8453", "payoutAddress": "0x...", "trustEnabled": false }
DELETE /operator/endpoints/{endpointId}

Public wrapper call:
ALL /wrap/{operatorId}/{path}

GET /operator/analytics/stats
GET /operator/analytics/revenue?days=30
GET /operator/analytics/top-endpoints?limit=10
GET /operator/analytics/agents?sortBy=lastSeen&limit=50&offset=0
GET /operator/analytics/agents/{agentId}
GET /operator/analytics/logs?limit=50&offset=0&days=7

POST /operator/playground
Body: { "method": "GET", "path": "/api/test", "agentId": "25459", "chain": "ethereum", "dryRun": false, "headers": {}, "body": null }

### Admin Endpoints (require role: "admin")
GET /operator/admin/stats
GET /operator/admin/operators
GET /operator/admin/operators/{id}
GET /operator/admin/operators/{id}/logs