# 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, optional wallet-history intelligence, 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 |
| [E2E-MIDDLEWARE-INTEGRATION.md](./E2E-MIDDLEWARE-INTEGRATION.md) | End-to-end middleware integration — identity, trust signals, downstream policy, and testing |
| [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 |
| [PROVIDER-IDENTITY.md](./PROVIDER-IDENTITY.md) | Provider-backed identity — SDK signing helpers and gates, normalized proofs, replay protection, policies, and ANS |
| [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`.
- **Provider-Backed Identity**: An ANS or future provider identity verified through `ValironSDK.verifyAgentIdentity()`. SDK 1.3 includes signing helpers and dedicated Express, Fastify, Next.js, and generic identity gates. Valiron hosts the ANS credentials and CA configuration.
- **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.
- **Wallet Intelligence**: A Pro trust signal that converts bounded Alchemy or Helius wallet history into an explainable score, risk level, confidence, and reasons.
- **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` |
| ANS, DNS, DID, API-key, or future provider identity | Provider-canonical agent ID | `x-valiron-identity-*` proof headers | SDK identity gate or `/operator/identity/verify` |

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.

Provider identity gates calculate the digest from the API's exact raw request
bytes and never trust a caller-supplied digest header. ANS credentials and the
trusted CA bundle live in Valiron's hosted service, not customer applications. See
[Provider-Backed Agent Identity](./PROVIDER-IDENTITY.md).

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

## Developer interfaces

- [Valiron OpenAPI](https://www.valiron.co/openapi.json)
- [Valiron MCP server setup](./MCP.md)
- [Valiron developer portal](https://www.valiron.co/developers)