# Trust Model

Valiron uses a hybrid trust model to evaluate AI agents hitting your API. This document explains what behaviors are evaluated and what each trust tier means for your routing decisions.

## Identity proof is not reputation

Provider-backed identity separates who controls an agent identity
from how that agent should be treated. `anonymous`, `claimed`, and `verified`
describe identity evidence only. `verified` remains pseudonymous and does not
mean that Valiron identified a human or that the agent has good behavioral
history.

After identity verification, Valiron looks up reputation using the stable
provider-canonical subject. For ANS this is `agentHost`, not the versioned ANS
name or registration UUID. The verification endpoint can then return a policy
action of `allow`, `limit`, `challenge`, or `block`. An identity with no observed
reputation returns an unknown risk level rather than being inferred as risky.

ANS trust-index and lifecycle evidence remain external provider evidence; they
are not relabeled as Valiron-observed reputation. SDK 1.3 exposes dedicated
provider identity gates using `x-valiron-identity-*` proof headers. The ANS
resolver and provider credentials remain inside Valiron's hosted service. See
[Provider-Backed Agent Identity](./PROVIDER-IDENTITY.md).

## Trust Tiers

Valiron assigns a Moody's-style credit tier from a normalized `0-100` trust score:

| Tier | Meaning | Route Decision |
|------|---------|----------------|
| AAA | Prime, highest quality | `prod` |
| AA | High grade | `prod` |
| A | Upper medium grade | `prod` |
| BAA | Medium grade | `prod` or `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` |

## Selectable Trust Signals

API sellers can use Valiron plug-and-play, or choose the trust signals used for a specific endpoint.

Supported signals:

| Signal | Description | Plan |
|--------|-------------|------|
| `8004` | ERC-8004 / Solana on-chain reputation | Free |
| `sandbox` | Valiron behavioral sandbox score | Free |
| `world` | World ID human-agent link | Pro |
| `self` | Self eligible-human proof and optional Self Agent ID link | Pro |
| `icebreaker` | Icebreaker human/background attestation | Pro |
| `wallet` | Explainable wallet-history activity and risk signal | Pro |

Selected trust signals contribute to a combined trust assessment. Exact weighting and scoring internals are not part of the public API contract.

If no signals are specified, Valiron uses the plug-and-play default: sandbox plus any other available trust signals.

## Wallet Intelligence

The optional `wallet` signal evaluates the history of the wallet Valiron resolves for an incoming agent. EVM history is read through Alchemy on Ethereum, Base, Arbitrum, Optimism, and Polygon. Solana history is read through Helius.

The assessment returns a `0-100` trust score where higher is better, `risk = 100 - score`, a `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` risk level, a confidence value, explainable reasons, and the normalized history features used by the scorer. Current features include transaction count, active days, wallet age, unique counterparties on EVM, failed transaction rate on Solana, and recent activity spikes when enough timestamps are available.

Confidence dampens sparse assessments toward a neutral score. If a provider key is missing, the network is unsupported, or the provider times out, wallet intelligence is marked unavailable and excluded from the composite score rather than being treated as malicious. A populated hard-risk flag forces `sandbox_only`, but the current history providers do not independently supply sanctions or malicious-address attribution.

Wallet history is bounded, not exhaustive: EVM uses up to 100 recent incoming and 100 recent outgoing transfers plus oldest-transfer lookups; Solana uses up to 1,000 recent signatures. The signal should not be described as AML, sanctions compliance, mixer detection, or complete fund tracing without an additional blockchain-intelligence provider.

Request wallet intelligence directly:

```typescript
const assessment = await valiron.getWalletRisk("0x52ce...", { chain: "base" });
console.log(assessment.score, assessment.riskLevel, assessment.confidence);
```

Or include it in an endpoint policy:

```typescript
app.use("/api/high-trust", createValironGate({
  sdk: valiron,
  trustSignals: ["8004", "sandbox", "wallet"],
  minScore: 80,
}));
```

## Behavioral Factors

Valiron evaluates agents across multiple behavioral dimensions. The behavioral evaluation is holistic — no single sandbox behavior determines the outcome. The specific factors evaluated and their weights are proprietary and not disclosed.

## What Makes an Agent Trustworthy

Agents that demonstrate responsible API usage patterns will earn the highest trust tiers. The specific behaviors that contribute to trust scoring are proprietary. In general, agents that are well-behaved, respect API boundaries, and handle errors gracefully will score highly.

## Predictive Risk

Valiron also computes an explainable forecast for agents with enough observed history. Predictive risk does not replace the trust gate; it helps operators decide what should happen before the next sensitive action.

The forecast combines:

- Recent sandbox evaluation scores, route decisions, and score trend
- Recurring behavioral failures such as rate-limit disrespect, loops, high error rate, and burstiness
- Behavioral fingerprints such as request cadence, backoff pattern, protocol mix, and error-response pattern
- Recent operator call logs including production error rate and latency

The output includes `predictedNextScore`, `passProbability`, `riskDirection`, `confidence`, `recommendedPolicy`, `recommendedTests`, and human-readable reasons. A low-confidence forecast means Valiron has sparse evidence; it should be treated as a prompt to run another sandbox evaluation rather than a final judgment.

Review forecasts on the agent detail page in the Valiron dashboard. Use the SDK trust gate for runtime enforcement.

## Checking an Agent's Trust Status

```typescript
import { ValironSDK } from "@valiron/sdk";

const valiron = new ValironSDK({ apiKey: process.env.VALIRON_API_KEY });
const result = await valiron.triggerSandboxTest("AGENT_ID");

console.log(`Tier: ${result.tier}`);
console.log(`Risk: ${result.riskLevel}`);
console.log(`Meets threshold: ${result.meetsThreshold}`);
```

Or via HTTP:

```bash
curl -X POST https://valiron-edge-proxy.onrender.com/operator/trigger-sandbox/AGENT_ID -H "Authorization: Bearer $VALIRON_API_KEY"
```

Use selected signals in middleware:

```typescript
app.use("/api/paid", createValironGate({
  sdk: valiron,
  trustSignals: ["8004", "sandbox"],
  minScore: 70,
}));
```

---

## Solana Trust Evaluation

Solana agents go through the same behavioral evaluation pipeline as EVM agents, with additional data from the QuantuLabs ATOM engine.

### Feedback Write-Back Loop

Unlike EVM (where feedback must be submitted manually), Solana agents benefit from **automatic feedback write-back**: after every sandbox test or gate evaluation, Valiron writes the computed score to the on-chain ATOM registry via `giveFeedback()`.

This means Solana agents build on-chain reputation automatically through normal Valiron usage:

```
Agent evaluated by Valiron sandbox
       ↓
Score computed (e.g. 92 / AA)
       ↓
Valiron calls giveFeedback() on-chain
       ↓
ATOM reputation updated
       ↓
Next evaluation includes new on-chain data
```

Feedback write-back is managed by Valiron. Write-back is fire-and-forget — if the transaction fails, the evaluation result is still returned.