# Quickstart

> Estimated integration time: under 2 minutes.

## Prerequisites

1. **Create an account** on the [Operator Dashboard](./DASHBOARD.md) at [valiron.co/dashboard](https://www.valiron.co/dashboard)
2. **Copy your API key** from the Keys page
3. Add the SDK middleware below to the backend routes agents call.

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

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

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

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

# Check a key-based agent profile
curl 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

# 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"}'
```

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

- **[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
- **[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"
```