# Quickstart

> Estimated integration time: under 2 minutes.

## Prerequisites

1. **Create an account** with email/password, Google, or GitHub on the [Operator Dashboard](./DASHBOARD.md) at [valiron.co/dashboard](https://www.valiron.co/dashboard)
2. **Verify your email for password signup**, then **complete the guided setup** — every sign-up method enters the same resumable onboarding flow
3. **Copy your API key** when it is shown; returning incomplete accounts can generate a dedicated setup key
4. Add the SDK middleware below to the backend routes agents call. Choose registered, key-based, or ANS/provider-backed identity in the wizard.

> **Tip:** Before writing any code, try the [API Playground](./DASHBOARD.md#api-playground) to see how Valiron evaluates agents at different trust levels against your endpoints.

## Step 1 — Install the SDK

```bash
npm install @valiron/sdk
```

> **Requirements:** Node.js >= 18.0.0. Zero external dependencies.

## Step 2 — Initialize the client

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

const valiron = new ValironSDK({
  apiKey: process.env.VALIRON_API_KEY,
  endpoint: "https://valiron-edge-proxy.onrender.com",
  chain: "ethereum", // or: monad, arbitrum, base, polygon, solana, etc.
  timeout: 5000,
});
```

Get an operator API key from https://www.valiron.co/dashboard and configure it server-side for profile reads, trust gates, and sandbox runs. Pro is required for paid signals, enriched profiles, proxy calls, and webhooks.

> **Solana agents:** Use `chain: "solana"` and pass the agent's Metaplex Core asset
> pubkey (base-58) as the agent ID instead of a numeric token ID.
> Solana identity and reputation is provided by
> [QuantuLabs 8004-solana](https://8004.qnt.sh/).

## Step 3 — Check an agent's trust level

First identify which kind of agent is calling your API:

| Agent type | Header | SDK/API path |
|------------|--------|--------------|
| ERC-8004 / Solana agent | `x-agent-id` | `getAgentProfile()` / `/operator/agent/:agentId` |
| Local, Web2, or non-ERC-8004 agent | `x-agent-address` | `getKeyAgentProfile()` / `/operator/key/:agentAddress` |
| Provider-backed identity (ANS and future adapters) | `x-valiron-identity-*` proof headers | `createValironIdentityGate()` / `verifyAgentIdentity()` |

Do not pass a local agent name such as `my-agent` to `/operator/agent/:agentId`. That endpoint expects an on-chain ERC-8004 token ID or Solana agent identifier. Non-ERC-8004 agents should use the key-based identity flow from [auth.md](https://www.valiron.co/auth.md).

For a provider-backed identity, use `createAgentIdentityProof()` in the agent
runtime and `createValironIdentityGate()` in the API. The receiving gate hashes
the exact request body, verifies the signature through Valiron, prevents replay,
and enforces `allow`, `limit`, `challenge`, or `block`. See
[Provider-Backed Agent Identity](./PROVIDER-IDENTITY.md).

For an on-chain agent, check their trust route:

```typescript
const route = await valiron.checkAgent("INCOMING_AGENT_ID");
// Returns: "prod" | "prod_throttled" | "sandbox" | "sandbox_only"
```

For a key-based agent, look up the verified agent address:

```typescript
const profile = await valiron.getKeyAgentProfile("0xAgentAddress");
console.log(profile.route); // "prod" | "prod_throttled" | "sandbox" | "sandbox_only"
```

## Step 4 — Get the full trust profile

For an on-chain agent:

```typescript
const profile = await valiron.getAgentProfile("INCOMING_AGENT_ID");

console.log(profile.routing.finalRoute);       // "prod"
console.log(profile.routing.meetsThreshold);   // true
console.log(profile.onchainReputation.averageScore); // 92.5
```

For a local, Web2, or non-ERC-8004 agent:

```typescript
const profile = await valiron.getKeyAgentProfile("0xAgentAddress");

console.log(profile.verified);  // true
console.log(profile.score);     // 82
console.log(profile.route);     // "prod_throttled"
```

## Step 5 — Gate your endpoint (recommended)

The fastest way to protect your API — add Valiron as Express middleware:

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

app.use("/api/paid", createValironGate({ sdk: valiron }));
```

This checks `x-agent-id` first for on-chain agents, then falls back to `x-agent-address` for key-based agents. It returns 403 for untrusted agents, is safe with Express 4 (async errors are handled), and includes a 30-second client-side cache for x402 compatibility.

Pro operators can include wallet history in an endpoint policy:

```typescript
const valiron = new ValironSDK({ apiKey: process.env.VALIRON_API_KEY });

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

The `wallet` signal supports Ethereum, Base, Arbitrum, Optimism, Polygon, and Solana. If wallet history is unavailable, Valiron excludes it from the composite score instead of penalizing the agent.

Or use `getAgentProfile()` directly for on-chain custom logic:

```typescript
const profile = await valiron.getAgentProfile("INCOMING_AGENT_ID");
const { finalRoute, decision } = profile.routing;
if (finalRoute === "prod" || finalRoute === "prod_throttled") {
  // Serve the request — agent is trusted
} else {
  // Block — agent is untrusted (tier: profile.localReputation?.tier)
}
```

> **Note**: The `gate()` method calls a protected endpoint that requires agent challenge-response auth. Use the middleware (`createValironGate`) or `getAgentProfile()` for server-side trust checks.

For key-based agents, use `getKeyAgentProfile()` directly:

```typescript
const profile = await valiron.getKeyAgentProfile("0xAgentAddress");
if (profile.verified && (profile.score ?? 0) >= 65) {
  // Serve the request
} else {
  // Block or ask the agent to complete https://www.valiron.co/auth.md
}
```

## What happens next?

Based on the route decision, your API should:

- `prod` — Allow full access. The agent is trusted.
- `prod_throttled` — Allow with rate limiting. The agent shows moderate trust.
- `sandbox` — Serve limited/test data. The agent is still being evaluated.
- `sandbox_only` — Block or serve only sandbox responses. The agent has failed behavioral evaluation.

## Step 6 — Trigger a sandbox evaluation (optional)

Proactively evaluate an agent before they hit your endpoints:

```typescript
// On-chain agents
const result = await valiron.triggerSandboxTest("AGENT_ID");

console.log(result.tier);            // "AAA"
console.log(result.riskLevel);       // "GREEN"
console.log(result.meetsThreshold);  // true

// Key-based (Web2) agents
const keyResult = await valiron.triggerKeyAgentSandbox("0x1234...abcd");
console.log(keyResult.tier);         // "A"
```

> **Auto-sandbox:** You usually don't need to call these manually. When a new agent (on-chain with `totalFeedback === 0`, or key-based with no score yet) hits a gated endpoint, the middleware automatically triggers sandbox evaluation in the background. The agent receives a `403` with `{ error: "Agent pending evaluation", retryAfterMs: 30000 }` — they should retry after 30 seconds.

## Step 7 — Register a webhook (optional)

Get notified whenever Valiron evaluates an agent calling your API:

```bash
curl -X POST https://valiron-edge-proxy.onrender.com/operator/webhooks/register \
  -H "Authorization: Bearer $VALIRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "evaluation_complete", "url": "https://your-endpoint.com/hooks/valiron"}'
```

## Step 8 — Monitor in the Dashboard

Once your integration is live, use the [Operator Dashboard](./DASHBOARD.md) to:

- **Agents** — See every agent that has called your API, sorted by activity, spend, or errors
- **Analytics** — Track revenue, call volume, and top endpoints over time
- **Call Logs** — Paginated log of every request with status codes, latency, and cost
- **Playground** — Test how agents at different trust levels are evaluated against your endpoints

## Using the HTTP API directly (no SDK)

```bash
# Check an agent's trust profile
curl -H "Authorization: Bearer $VALIRON_API_KEY" https://valiron-edge-proxy.onrender.com/operator/agent/AGENT_ID

# Check a key-based agent profile
curl -H "Authorization: Bearer $VALIRON_API_KEY" https://valiron-edge-proxy.onrender.com/operator/key/0x1234...abcd

# Get a key-based identity challenge
curl -X POST https://valiron-edge-proxy.onrender.com/operator/key/0x1234...abcd/challenge

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

# Trigger sandbox for key-based agent
curl -X POST https://valiron-edge-proxy.onrender.com/operator/trigger-sandbox-key/0x1234...abcd -H "Authorization: Bearer $VALIRON_API_KEY"

# Gate decision (allow/deny)
curl -H "Authorization: Bearer $VALIRON_API_KEY" -X POST https://valiron-edge-proxy.onrender.com/operator/gate/AGENT_ID

# Behavioral snapshot hash
curl -H "Authorization: Bearer $VALIRON_API_KEY" https://valiron-edge-proxy.onrender.com/operator/agent/AGENT_ID/snapshot

# Register webhook
curl -X POST https://valiron-edge-proxy.onrender.com/operator/webhooks/register \
  -H "Authorization: Bearer $VALIRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "evaluation_complete", "url": "https://your-endpoint.com/hooks"}'
```

## Separate product — API Scaffolding

Valiron middleware is the primary backend integration. API Scaffolding is a separate product for exposing an existing HTTPS API through a Valiron-hosted, agent-facing URL.

1. Open [valiron.co/dashboard](https://www.valiron.co/dashboard).
2. Go to **Make API Agent-Ready**.
3. Enter your public path, upstream API base URL, price, payment protocol, and optional trust settings.
4. Distribute the generated wrapper URL to agent clients:

```text
https://valiron-edge-proxy.onrender.com/wrap/{operatorId}/{path}
```

API Scaffolding can collect payment, apply optional trust checks, enforce rate limits, forward upstream, and log usage. For deployments requiring full backend control, protect the API directly with Valiron middleware using `createValironGate()` or `ValironOperator.paywall()`.

---

## Cleanup (long-running servers)

Call `dispose()` when shutting down to flush pending telemetry:

```typescript
process.on("SIGTERM", async () => {
  await valiron.dispose();
  process.exit(0);
});
```

---

## What's next?

- **[End-to-End Middleware Integration](./E2E-MIDDLEWARE-INTEGRATION.md)** — Choose identity, trust signals, and a downstream policy for a production integration
- **[Proxy Gateway](./SDK-REFERENCE.md#proxy-gateway-pro)** — Forward requests through Valiron's edge proxy (Pro)
- **[API Scaffolding](./AGENT-READY-APIS.md)** — Create hosted x402/MPP wrappers for existing APIs
- **[Key-Based Agents](./SDK-REFERENCE.md#key-based-agents)** — Support Web2 agents without on-chain identity
- **[World ID](./SDK-REFERENCE.md#world-id-methods)** — Verify agent-human linkage
- **[Self](./SDK-REFERENCE.md#self-methods)** — Create Self Enterprise sessions and verify eligible-human linkage
- **[Wallet Intelligence](./TRUST-MODEL.md#wallet-intelligence)** — Add explainable wallet-history risk to Pro endpoint policies
- **[Fastify / Next.js / Hono middleware](./SDK-REFERENCE.md#middleware)** — Framework-specific middleware
- **[Plans & Limits](./SDK-REFERENCE.md#plans--limits)** — Free vs Pro feature comparison

---

## Quickstart: Solana Agents

Solana agents use a different registry ([QuantuLabs 8004-solana](https://8004.qnt.sh/)) but the same Valiron API. Here's how to evaluate Solana-based agents calling your API.

### Step 1 — Initialize with Solana chain

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

const valiron = new ValironSDK({
  apiKey: process.env.VALIRON_API_KEY,
  endpoint: "https://valiron-edge-proxy.onrender.com",
  chain: "solana",
});
```

### Step 2 — Query an agent by asset pubkey or sequential ID

Solana agents have two ID formats — use whichever the agent provides:

```typescript
// By Metaplex Core asset pubkey (base-58)
const profile = await valiron.getAgentProfile("DFkntsJ9aTCHkK88m6WZVQEvLdLNi4X1LVUgRMqetFPM");

// By sequential ID (integer assigned by QuantuLabs indexer)
const profile = await valiron.getAgentProfile("1226");

console.log(profile.identity.name);                   // "NoahScout_Bot.noah"
console.log(profile.onchainReputation.solana?.trustTier); // "trusted"
```

### Step 3 — Check liveness (Solana only)

Solana agents support a liveness probe that pings their declared service endpoints:

```bash
curl -H "Authorization: Bearer $VALIRON_API_KEY" "https://valiron-edge-proxy.onrender.com/operator/agent/1226/liveness?chain=solana"
```

### Step 4 — Gate decision (same as EVM)

```typescript
const gate = await valiron.gate("1226");
if (gate.allow) {
  // Serve the request — agent is trusted
}
```

### Solana HTTP API examples

```bash
# Get agent profile (sequential ID)
curl -H "Authorization: Bearer $VALIRON_API_KEY" "https://valiron-edge-proxy.onrender.com/operator/agent/1226?chain=solana"

# Get agent profile (asset pubkey)
curl -H "Authorization: Bearer $VALIRON_API_KEY" "https://valiron-edge-proxy.onrender.com/operator/agent/DFkntsJ9aTCHkK88m6...?chain=solana"

# Resolve wallet to agent
curl -H "Authorization: Bearer $VALIRON_API_KEY" "https://valiron-edge-proxy.onrender.com/operator/resolve-wallet/VSAnVX4MQjEXreHc92iHxWuXPQZ1tjwiKccpFLCgLM9?chain=solana"

# Trigger sandbox
curl -H "Authorization: Bearer $VALIRON_API_KEY" -X POST "https://valiron-edge-proxy.onrender.com/operator/trigger-sandbox/1226?chain=solana"

# Trust gate
curl -H "Authorization: Bearer $VALIRON_API_KEY" -X POST "https://valiron-edge-proxy.onrender.com/operator/gate/1226?chain=solana"

# Liveness check
curl -H "Authorization: Bearer $VALIRON_API_KEY" "https://valiron-edge-proxy.onrender.com/operator/agent/1226/liveness?chain=solana"
```