# Operator Dashboard

> Manage your Valiron integration from a single web interface — register endpoints, monitor agent activity, test trust evaluations, and view analytics.

**Dashboard URL:** [https://www.valiron.co/dashboard](https://www.valiron.co/dashboard)

---

## Getting Access

To create an account:

1. Go to [valiron.co/dashboard](https://www.valiron.co/dashboard) and click **Create account**
2. Enter your name, email, and password
3. On success, you'll see a **one-time API key** — copy it immediately (it won't be shown again)

After registration, sign in with your email and password. Your session is stored as a JWT in the browser.

---

## Overview

**Route:** `/dashboard`

Your landing page after signing in. Shows a summary of your integration at a glance:

- **Top stats** — Total Revenue, Total Calls, Unique Agents, Avg Latency
- **Secondary stats** — Active API Keys, Registered Endpoints, Calls Today, Plan + fee rate
- **Recent Activity** — Last 5 call logs with method, path, agent, cost, and timestamp
- **Quick Start** — 3-step guide: get API key → make an API agent-ready → test with agents

---

## Agents

**Route:** `/dashboard/agents`

View every AI agent that has called your API, sorted by last seen, call volume, spend, or error count.

Each agent card shows:
- Agent ID (ERC-8004 token ID)
- Chain badges (multi-chain support)
- Last seen, total calls, total spent, avg latency, error count

**Click an agent** to drill into:
- Summary stats and first/last seen dates
- Endpoint breakdown table — which of your endpoints they called, how many times, spend, avg latency, errors
- Recent call log for that agent

---

## Analytics

**Route:** `/dashboard/analytics`

Revenue and usage analytics with time-range filtering.

- **Stats grid** — Total Revenue, Total Calls, Unique Agents, Avg Latency
- **Today's stats** — Calls Today, Revenue Today, Error Rate (highlighted if > 5%)
- **Daily Revenue chart** — Bar chart with tooltips (7 / 30 / 90 day range selector)
- **Top Endpoints** — Ranked by call volume with revenue, avg latency, and unique agent count

---

## Call Logs

**Route:** `/dashboard/logs`

Paginated log of every API call made through your Valiron-gated endpoints.

Each row shows:
- Timestamp
- Agent label + ID
- Chain badge
- Endpoint (method + path)
- Status code (color-coded: green for 2xx, yellow for 4xx, red for 5xx)
- Cost charged
- Latency
- Session ID

**Filters:**
- Time range: All time, Last 24h, 7 days, 30 days, 90 days
- Pagination: 50 entries per page

---

## API Keys

**Route:** `/dashboard/keys`

Manage your operator API keys. These keys authenticate your backend when calling Valiron's trust evaluation API via the SDK.

**Actions:**
- **Generate new key** — Creates a new `val_op_` prefixed key. Shown once — copy it immediately.
- **Revoke key** — Permanently disables a key. Revoked keys are shown separately.

Each key shows its prefix, label, last used date, and creation date.

---

## Make API Agent-Ready

**Route:** `/dashboard/endpoints`

Create hosted Valiron wrappers for existing HTTP APIs. A wrapper provides a public agent-facing URL, handles optional x402/MPP payment challenges, optionally checks Valiron trust, applies rate limits, forwards to the upstream API, and records call logs.

This product is appropriate when an API must be callable by autonomous agents without requiring immediate SDK integration in the provider backend.

### Hosted wrapper flow

1. Open **Make API Agent-Ready**.
2. Click **Make API Agent-Ready**.
3. Enter your upstream API details and payment settings.
4. Save the wrapper.
5. Distribute the generated wrapper URL to agent clients:

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

When an agent calls the wrapper:

1. Valiron matches `{operatorId}`, path, and method to your wrapper config.
2. If `pricePerCall` is greater than `0`, Valiron returns a `402 Payment Required` challenge unless valid payment is attached.
3. If trust checks are enabled, Valiron evaluates the agent identity headers.
4. Valiron appends the wrapper path to `targetUrl`, forwards the request, and adds Valiron metadata headers.
5. Valiron returns the upstream response and records analytics.

### Wrapper fields

| Field | Required | Description |
|-------|----------|-------------|
| Public path | Yes | Agent-facing path (for example `/weather`). This becomes `/wrap/{operatorId}/weather`. |
| Method | Yes | HTTP method: GET, POST, PUT, PATCH, DELETE |
| Upstream API base URL | Yes | Existing API base URL, for example `https://api.example.com`. Must be HTTPS in production. Private/internal addresses are blocked. |
| Price per call (USD) | Yes | `0` for free wrappers, or a positive USD amount for paid wrappers. |
| Payment protocol | Yes | `x402` or `mpp`. `x402` is used by default and for free wrappers. |
| Payment network | No | Network for paid wrappers. Common values: `eip155:8453` for Base x402 and `tempo:4217` for MPP. |
| Payout wallet | No | Required for paid x402 wrappers unless a platform default receiving address is configured. |
| Require Valiron trust | No | When enabled, callers must provide agent identity headers and pass the trust threshold. |
| Rate limit (req/min) | No | Max requests per minute per agent (null = unlimited) |
| Upstream auth | No | Optional static header secret Valiron should attach to your upstream request. |
| Description | No | What this endpoint does |

**Removing a wrapper** performs a soft-delete. The wrapper stops matching new calls but historical logs remain available.

### Free wrapper example

```text
Public path: /status
Method: GET
Upstream API base URL: https://api.example.com
Price: 0
```

Agents call:

```bash
curl https://valiron-edge-proxy.onrender.com/wrap/{operatorId}/status
```

### Paid x402 wrapper example

```text
Public path: /weather
Method: GET
Upstream API base URL: https://api.example.com
Price: 0.001
Payment protocol: x402
Payment network: eip155:8453
Payout wallet: 0x...
```

Agents call the wrapper once, receive a `402` with an x402 payment challenge, then retry with a valid `X-PAYMENT` header.

### Paid MPP wrapper example

```text
Public path: /research
Method: GET
Upstream API base URL: https://api.example.com
Price: 0.001
Payment protocol: mpp
Payment network: tempo:4217
```

Agents call the wrapper once, receive `WWW-Authenticate: Payment`, then retry with `Authorization: Payment ...`. For command-line testing, use `mppx`:

```bash
pnpm exec mppx https://valiron-edge-proxy.onrender.com/wrap/{operatorId}/research
```

For the complete setup guide, see [AGENT-READY-APIS.md](./AGENT-READY-APIS.md).

---

## API Playground

**Route:** `/dashboard/playground`

Test how Valiron evaluates different AI agents against your endpoints — without writing any code or sending real traffic.

### How it works

1. **Pick a chain** — All supported chains are available (Ethereum, Monad, Arbitrum, Base, Avalanche, Polygon, Optimism, Solana, testnets, and more). Chains with pre-registered sample agents show agent cards; other chains require a custom agent ID.
2. **Select an agent** — Choose from pre-registered sample agents at different trust levels, or enter a custom agent ID:
   - **Good agents** (score 80–95, tier A/AA) — would be routed to production
   - **Bad agents** (score 30–45, tier CA/CAA) — would be routed to sandbox
   - **Zero agents** (score 0, tier C) — no reputation, requires behavioral testing
3. **Build the request** — Pick a method and enter a path. Headers (`Content-Type`, `X-Agent-Id`, `X-Valiron-Chain`, `X-Api-Key`) are added automatically. Expand **Advanced options** to add custom headers, query params, or a request body
4. **Send** — The playground evaluates the agent's on-chain trust profile and shows the result

### Dry-run mode

Toggle **Dry Run** on to see the trust evaluation without logging the call:
- Resolved tier (AAA–C)
- Routing decision (prod / sandbox / blocked)
- Price per call (from your registered endpoint)
- On-chain reputation score and feedback count

### Standard mode

With dry-run off, the playground performs the full trust evaluation and logs the call to your Analytics/Logs pages.

- **If your endpoint has an upstream base URL** — the playground forwards the request to your backend with Valiron headers (`X-Agent-Id`, `X-Valiron-Chain`, `X-Valiron-Tier`, `X-Valiron-Route`). You'll see the real HTTP response from your server.
- **If no upstream base URL is set** — the playground returns the trust evaluation only (tier, route, cost, on-chain score).

> **Tip:** Add an upstream base URL to your wrapper to enable end-to-end testing in the playground.

### Response panel

Every request shows:
- **Status code** — Color-coded (green 2xx, yellow 3xx/4xx, red 5xx)
- **Latency** — Round-trip time in ms
- **Route** — Where the agent would be routed (prod, sandbox, blocked)
- **Cost** — Per-call price from your endpoint registration
- **Tier** — The agent's resolved trust tier
- **Body** — Trust evaluation details

### History

The sidebar shows up to 20 recent requests from the current page session. Each entry shows method, path, agent, status, latency, and timestamp. Click an entry to repopulate the request form; history is not persisted across sessions.

---

## Settings

**Route:** `/dashboard/settings`

Manage your operator profile.

- **Name** — Editable display name
- **Email** — Read-only (set during registration)
- **Plan** — Your current plan and fee rate
- **Account info** — Operator ID and account creation date

---

## Admin Panel

**Route:** `/dashboard/admin` (admin-only)

Platform-wide administration. Only visible to operators with `role: "admin"`.

- **Platform stats** — Total operators, total API calls, total revenue
- **All operators table** — Name, email, role, plan, keys, endpoints, calls, revenue, agents, join date
- **Operator drill-down** — Click any operator to see their full detail: stats, daily revenue chart, API keys, endpoints, agents, account info

---

## Middleware Integration

Valiron's core product is SDK middleware deployed within the API backend. Use this path when trust checks, route decisions, sandbox triggers, payment gating, and usage tracking must execute before the API handler.

Install the SDK and add it to your backend:

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

**Express middleware:**

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

const operator = new ValironOperator({ apiKey: "val_op_xxxx" });
app.use("/api/weather", operator.paywall({ pricePerCall: 0.05 }));
```

**Manual gating:**

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

const valiron = new ValironSDK({ chain: "ethereum" });

app.use("/api/weather", async (req, res, next) => {
  const agentId = req.headers["x-agent-id"];
  const profile = await valiron.getAgentProfile(agentId);

  if (profile.routing.finalRoute === "prod") return next();
  if (profile.routing.finalRoute === "sandbox")
    return res.status(403).json({ error: "Agent under evaluation" });
  return res.status(403).json({ error: "Agent not trusted" });
});
```

### Test with the Playground

Before going live, use the Playground to verify:
- That your endpoint pricing and rate limits are configured correctly
- That high-reputation agents get routed to production
- That low/zero-reputation agents get sandboxed or blocked
- What the full request/response cycle looks like with real latency numbers

### Monitor

Use the dashboard to track agent activity, review call logs, and monitor revenue.

## Separate Product: API Scaffolding

API Scaffolding is a separate product that provides a hosted, agent-facing wrapper URL for an existing HTTPS API. A hosted wrapper can collect x402/MPP payment, apply optional trust checks, enforce rate limits, forward upstream, and log usage.

1. Create your account on the dashboard.
2. Copy your API key from the Keys page.
3. Create a wrapper from **Make API Agent-Ready**.
4. Test the generated `/wrap/{operatorId}/{path}` URL.
5. Monitor calls in Analytics and Logs.

For deployments requiring full backend control, protect the API directly with Valiron middleware using `createValironGate()` or `ValironOperator.paywall()`.

For full hosted wrapper docs, see [AGENT-READY-APIS.md](./AGENT-READY-APIS.md).