# Valiron — Documentation

> **Protect your API endpoints from bad or malicious AI agents.** This documentation covers how to integrate Valiron into your API to gate, score, and sandbox agents before they reach your infrastructure.

## What is Valiron?

Valiron is trust infrastructure for API sellers. It evaluates AI agents using on-chain identity (ERC-8004 or Solana), key-based identity for non-ERC-8004 agents, behavioral sandbox testing, and a Moody's-style credit rating system — so you can allow trusted agents and block risky ones automatically.

**If you sell APIs**, Valiron's core product is middleware deployed within the API backend through the SDK. It provides direct control over trust checks, routing, sandboxing, payment gating, and analytics before requests reach application handlers.

Valiron also provides **API Scaffolding** as a separate product for organizations that require a hosted, agent-facing wrapper URL for an existing HTTPS API. It can add x402/MPP payment challenges, optional trust checks, rate limits, upstream forwarding, and logging without requiring backend code changes. Scaffolding can serve as an evaluation path before adopting a first-party backend integration protected by Valiron middleware.

## Documentation Index

| File | Purpose |
|------|---------|
| [QUICKSTART.md](./QUICKSTART.md) | Get started in under 2 minutes — install the SDK, gate your first endpoint |
| [AGENT-READY-APIS.md](./AGENT-READY-APIS.md) | API Scaffolding — hosted x402/MPP wrappers for existing APIs |
| [DASHBOARD.md](./DASHBOARD.md) | Operator Dashboard — manage endpoints, keys, analytics, and playground |
| [API-REFERENCE.md](./API-REFERENCE.md) | Complete HTTP API reference with request/response schemas |
| [SDK-REFERENCE.md](./SDK-REFERENCE.md) | TypeScript SDK methods, signatures, and usage examples |
| [TRUST-MODEL.md](./TRUST-MODEL.md) | How agents are scored, what behaviors are penalized, tier assignments |
| [IDENTITY.md](./IDENTITY.md) | Agent identity — ERC-8004/Solana agents and key-based Web2 agents |
| [SANDBOX.md](./SANDBOX.md) | How the sandbox evaluates agents and determines production readiness |
| [CHAINS.md](./CHAINS.md) | Supported blockchain networks and contract addresses |
| [ERRORS.md](./ERRORS.md) | Error codes, troubleshooting, and retry guidance |

## Key Concepts (Summary)

- **Agent ID**: An agent's ERC-8004 token ID (EVM) or Metaplex Core asset pubkey (Solana) — their on-chain identity. Use this with `x-agent-id` and `/operator/agent/:agentId`.
- **Key-Based Agent Address**: A persistent Ethereum-style address for a local, Web2, or non-ERC-8004 agent. Use this with `x-agent-address` and `/operator/key/:agentAddress`.
- **Sequential ID** (Solana only): A convenience integer (1, 2, 42…) assigned by the QuantuLabs indexer. Maps to an asset pubkey.
- **Trust Tier**: AAA (highest trust) → C (lowest trust). Assigned based on behavioral evaluation.
- **Risk Level**: GREEN, YELLOW, or RED.
- **Route Decision**: `prod`, `prod_throttled`, `sandbox`, or `sandbox_only` — determines what access level your API should give.
- **API Scaffolding**: A separate hosted Valiron wrapper product at `/wrap/{operatorId}/{path}` that can collect x402/MPP payments, optionally gate by trust, and forward to an upstream API.
- **Payment Protocol**: `x402` for Base/USDC HTTP payments or `mpp` for Machine Payment Protocol payments through Tempo.
- **Sandbox**: An isolated test environment where Valiron evaluates agent behavior before granting production access.
- **Liveness** (Solana only): Endpoint health probe via `isItAlive()`. See [API-REFERENCE.md](./API-REFERENCE.md#solana-support).

## Which Identity Path Should I Use?

| Agent type | Use this identifier | Request header | Lookup path |
|------------|---------------------|----------------|-------------|
| ERC-8004 / on-chain EVM agent | ERC-8004 token ID | `x-agent-id` | `/operator/agent/:agentId` |
| Solana 8004 agent | Metaplex Core asset pubkey or indexed ID | `x-agent-id` | `/operator/agent/:agentId?chain=solana` |
| Local, Web2, or non-ERC-8004 agent | Persistent Ethereum-style agent address | `x-agent-address` | `/operator/key/:agentAddress` |

Do not send a local agent name such as `my-agent` to `/operator/agent/:agentId`. That endpoint is for registry-backed on-chain agents. Local and Web2 agents should generate or reuse a persistent keypair, prove ownership through Valiron's challenge-response flow, and then use their `x-agent-address` for trust checks.

## Supported Registries

| Network | Provider | Identity | Reputation |
|---------|----------|----------|------------|
| EVM (41 chains) | [8004 team](https://erc8004.org) | `0x8004A169...` | `0x8004BAa1...` |
| Solana | [QuantuLabs](https://8004.qnt.sh/) | `8oo4dC4J...` | `AToMw53a...` (ATOM) |

## Base URL

```
https://valiron-edge-proxy.onrender.com
```