# Quickstart

> Estimated integration time: under 2 minutes.

## Prerequisites

1. **Create an account** on the [Operator Dashboard](./DASHBOARD.md) at [valiron.co/dashboard](https://valiron.co/dashboard)
2. **Copy your API key** from the Keys page
3. **Register your endpoints** on the Endpoints page — set path, method, price per call, and rate limits

> **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({
  endpoint: "https://valiron-edge-proxy.onrender.com",
  chain: "ethereum", // or: monad, arbitrum, base, polygon, solana, etc.
  timeout: 5000,
});
```

No API key is required for read operations.

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

When an agent calls your API, check their trust route:

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

## Step 4 — Get the full trust profile

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

## 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 reads `x-agent-id` from the request header, checks trust via the public agent profile endpoint, and returns 403 for untrusted agents. It's safe with Express 4 (async errors are handled) and includes a 30-second client-side cache for x402 compatibility.

Or use `getAgentProfile()` directly for 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.

## 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 "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 https://valiron-edge-proxy.onrender.com/operator/agent/AGENT_ID

# Trigger sandbox evaluation
curl -X POST https://valiron-edge-proxy.onrender.com/operator/trigger-sandbox/AGENT_ID

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

# Gate decision (allow/deny)
curl -X POST https://valiron-edge-proxy.onrender.com/operator/gate/AGENT_ID

# Behavioral snapshot hash
curl 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 "Content-Type: application/json" \
  -d '{"event": "evaluation_complete", "url": "https://your-endpoint.com/hooks"}'
```

---

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

- **[Proxy Gateway](./SDK-REFERENCE.md#proxy-gateway-pro)** — Forward requests through Valiron's edge proxy (Pro)
- **[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
- **[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({
  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 "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 "https://valiron-edge-proxy.onrender.com/operator/agent/1226?chain=solana"

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

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

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

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

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