# Valiron

## Access and data boundaries

Profile endpoints require operator authentication and return identity and trust summaries. They do not return raw behavioral metrics, stored-evidence links, RPC URLs, internal errors, or verification-provider records. Self and World ID responses return an allowlisted verification summary; nullifiers, credential subjects, and provider storage references are private.

Sandbox runs require an operator API key. Enriched profiles, the trust-gated proxy, and webhook registration require a Pro operator API key. Webhook deliveries are scoped to the operator that initiated the evaluation and the selected chain. Legacy global evaluation history and platform statistics are restricted to Valiron administrators; view your own account analytics in the dashboard.

The gate also requires agent challenge-response headers (`x-agent-address` plus a valid `x-agent-session`, or a signed fresh challenge). Operator credentials do not replace agent identity. See [authentication](https://www.valiron.co/auth.md).


## Valiron Developer Resources

- [Valiron developer portal](https://www.valiron.co/developers): REST API, SDK, authentication, webhooks, and MCP setup.
- [Valiron OpenAPI specification](https://www.valiron.co/openapi.json): Machine-readable public API contract.
- [Valiron public API discovery](https://www.valiron.co/api): API URLs and integration resources, no authentication required.
- [Valiron API health](https://www.valiron.co/api/health): Live availability and supported chains, no authentication required.
- [Valiron authentication](https://www.valiron.co/auth.md): Operator keys and agent identity proofs.
- [Valiron API and webhook reference](https://www.valiron.co/docs/agents/API-REFERENCE.md): REST endpoints and evaluation-complete webhooks.
- [Valiron MCP server](https://www.valiron.co/mcp): Streamable HTTP (POST), no API key; public health and integration docs.
- [Valiron MCP setup](https://www.valiron.co/docs/agents/MCP.md): Client configuration, tool scope, and transport details.


> 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, optional wallet-history intelligence, predictive risk forecasts, 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.

Provider-backed identity uses SDK 1.3 signing helpers and x-valiron-identity-* proof headers. Agents call createAgentIdentityProof() and agentIdentityProofHeaders(); API owners use createValironIdentityGate(), valironIdentityFastifyPlugin, createValironIdentityNextMiddleware, or valironIdentityGateCheck. The headers are untrusted proof inputs until the gate hashes exact request bytes, calls verifyAgentIdentity(), prevents replay, and enforces allow|limit|challenge|block. Valiron hosts ANS credentials and CA trust; customers do not configure them. See https://www.valiron.co/docs/agents/PROVIDER-IDENTITY.md.

## End-to-End Middleware Integration

For a production integration, choose an identity path, select trustSignals from 8004, sandbox, world, self, icebreaker, and wallet, then use the gate result (allow, score, tier, riskLevel, route) to apply your endpoint policy. See https://www.valiron.co/docs/agents/E2E-MIDDLEWARE-INTEGRATION.md. SDK middleware supports both x-agent-id and x-agent-address; trust-enabled hosted API Scaffolding wrappers currently require x-agent-id.

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

### Wallet-history risk (Pro)
GET /operator/wallet-risk/{wallet}?chain={chain}
Requires: Authorization: Bearer val_op_...
Returns: { available, wallet, network, provider, score, rawScore, risk, confidence, riskLevel, reasons, hardFlags, features, observedAt, expiresAt, error? }

### Resolve wallet to agent ID
GET /operator/resolve-wallet/{wallet}?chain={chain}
Returns: { wallet, agentId, source, chainId?, agentName?, timestamp }
Resolution returns a registered agent ID when available, or 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}
GET /operator/key/{agentAddress}/icebreaker — private owner context for a verified key agent; requires a Pro operator key or that agent's authenticated session. Returns profile handles, not connections or mutuals. Does not alter the Web2 behavioral score.

### Provider-backed identity proof
POST /operator/identity/verify
Body: { provider, agentId, signature, timestamp, nonce, requestDigest, keyId?, policy? }
Returns: { agentId, provider, organization, identityStatus, humanIdentified, stableIdentityId, credentialId?, credentialVersion?, externalTrust?, verifiedAt, failureReason?, reputationScore, riskLevel, policyDecision }

### 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, createValironIdentityGate } from "@valiron/sdk";
const valiron = new ValironSDK({ apiKey: process.env.VALIRON_API_KEY, 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");

// Pro wallet-history assessment
const walletRisk = await valiron.getWalletRisk("0x...", { chain: "base" });

// 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"

// Provider identity: low-level verification
const identity = await valiron.verifyAgentIdentity(proof, { claimed: "block" });

// Provider identity: route enforcement
app.post("/api/quote", createValironIdentityGate({ sdk: valiron }), handler);
```

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 through the website. 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 and deny untrusted agents before forwarding. Use SDK middleware in your own backend when you need to support x-agent-address. Wrapper controls and analytics apply only to traffic sent to `/wrap/{operatorId}/{path}`: publish that URL to agents and protect any public origin with HMAC upstream auth, rejecting direct unsigned requests. Do not treat `x-valiron-*` metadata headers as credentials.

## 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 six 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. **Self** — Self Enterprise eligible-human proof via signed session webhooks, with optional Self Agent ID binding.
5. **Icebreaker** — Human attestation via Ethereum Attestation Service (EAS) on Base. A human attests this is their "designated agent."
6. **Wallet Intelligence** (Pro) — Bounded Alchemy history on Ethereum/Base/Arbitrum/Optimism/Polygon or Helius signature history on Solana. Returns a trust score, inverse risk, confidence, reasons, hard flags, and normalized activity features.

Wallet intelligence is confidence-damped toward neutral when history is sparse. Provider failures are excluded from composite scoring. Current adapters do not provide sanctions, mixer, scam, or criminal attribution and do not trace complete transaction history.

Predictive risk is available in the dashboard for observed agents. It forecasts the next score, pass probability, trend, confidence, recommended policy, suggested tests, and reasons from recent sandbox evaluations, behavioral fingerprints, and operator call logs. It does not replace the trust gate; low-confidence forecasts mean more evaluation data is needed.

## 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 and custom tier thresholds. All profile reads and trust operations require an operator API key (val_op_ prefix); paid features require Pro.

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

## Self Methods

- createSelfSession(agentId, request?) — Create a Self Enterprise verification session and redirect the user to `verificationUrl`
- getSelfStatus(agentId) — Check whether the agent has a verified Self eligible-human link
- getSelfProfile(agentId) — Full Self eligible-human and optional Agent ID profile
- verifySelf(agentId, proof) — Not supported for hosted customer integrations; use createSelfSession() and getSelfStatus()

## Telemetry

Opt-out anonymous client usage reports. Disable with `telemetry: { enabled: false }`. Supports custom sampleRate (0–1) and custom handler function. Environment defaults to recognized NODE_ENV values, otherwise unknown. Signal selections do not measure successful verifications.

## Middleware Error Responses

All middleware returns actionable JSON. Use the stable `code` for program logic and read `message`, `action`, and `docsUrl` for recovery. Codes: `MISSING_AGENT_IDENTITY` (401), `TRUST_GATE_DENIED` (403), `AGENT_EVALUATION_PENDING` (403; honor `retryAfterMs`), and `TRUST_GATE_UNAVAILABLE` (503, fail-closed). SDK `ValironError` instances preserve the same server code plus `details.action`, `details.requestId`, `details.docsUrl`, and `details.retryAfterMs`.

## 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() when enabled by Valiron

## 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/PROVIDER-IDENTITY.md — Provider-independent identity proof, replay protection, policy actions, and ANS adapter status
- 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 (sign in on the website)

### Dashboard Features
- Overview: revenue, calls, agents, latency stats + quick start guide
- Agents: view every agent that called your API, drill into per-agent detail with predictive risk
- 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