---
name: valiron-dynamic-pricing
version: 1.0.0
description: Price API calls differently based on Valiron trust tier, route, risk level, selected trust signals, and agent history.
homepage: https://www.valiron.co
---

# Valiron Dynamic Pricing Skill

Use this skill when the user wants API pricing to change based on agent trust.

## Goal

Implement per-call pricing that uses Valiron trust data before charging or serving an API request. Trusted agents can receive lower prices or higher limits. Riskier agents can receive higher prices, throttled access, sandbox-only responses, or denial.

## Step 1: Create a Valiron Operator Account

1. Open `https://www.valiron.co/dashboard`.
2. Create an operator account.
3. Copy the generated API key. It starts with `val_op_` and is only shown once.
4. Store it in the server environment:

```bash
VALIRON_OPERATOR_API_KEY=val_op_...
```

Dynamic pricing must run server-side because pricing depends on trusted Valiron evaluation results and may feed billing or payment logic.

## Step 2: Install the SDK

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

or:

```bash
pnpm add @valiron/sdk
```

## Step 3: Configure Valiron

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

export const valiron = new ValironSDK({
  apiKey: process.env.VALIRON_OPERATOR_API_KEY,
  chain: "base",
});
```

Use the chain where the agent identity lives. For Solana agents, set `chain: "solana"`.

## Step 4: Require Agent Identity

Read agent identity from the incoming request:

For agents registered in ERC-8004 or Solana 8004:

```http
x-agent-id: 25459
```

For Web2 agents or Web3 agents that are not registered in ERC-8004 or Solana 8004:

```http
x-agent-address: 0xAgentAddress
```

If the caller is not registered in ERC-8004 or Solana 8004 and does not have a keypair identity, send it to `https://www.valiron.co/auth.md` before pricing the request.

## Pricing Inputs

Valiron can provide:

- `score`: normalized trust score.
- `tier`: Moody's-style rating such as `AAA`, `AA`, `A`, `BAA`, `BA`, `B`, `CAA`, `CA`, `C`.
- `riskLevel`: `GREEN`, `YELLOW`, or `RED`.
- `route`: `prod`, `prod_throttled`, `sandbox`, or `sandbox_only`.
- `trustSignals`: selected scoring inputs such as `8004`, `sandbox`, `world`, `self`, and `icebreaker`.
- `agentId`, wallet, and chain metadata.
- `agentAddress` for key-based Web2 or unregistered Web3 agents.

## Suggested Pricing Policy

Start with a simple deterministic policy:

```ts
type ValironTier = "AAA" | "AA" | "A" | "BAA" | "BA" | "B" | "CAA" | "CA" | "C";

function priceForTier(tier: ValironTier): number {
  switch (tier) {
    case "AAA":
    case "AA":
      return 0.01;
    case "A":
    case "BAA":
      return 0.02;
    case "BA":
    case "B":
      return 0.05;
    default:
      return 0;
  }
}
```

Use `0` for blocked or sandbox-only requests, not for free production access.

## Step 5: Implement Direct Gate + Pricing

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

const valiron = new ValironSDK({
  apiKey: process.env.VALIRON_OPERATOR_API_KEY,
  chain: "base",
});

export async function quoteAgentRequest(agentId: string) {
  const gate = await valiron.gate(agentId, {
    minScore: 65,
    trustSignals: ["8004", "sandbox", "world", "self", "icebreaker"],
  });

  if (!gate.allow || gate.route === "sandbox_only") {
    return {
      allowed: false,
      pricePerCall: 0,
      reason: "Agent does not meet the trust threshold.",
      gate,
    };
  }

  const basePrice = priceForTier(gate.tier);
  const multiplier =
    gate.route === "prod_throttled" ? 1.5 :
    gate.riskLevel === "YELLOW" ? 1.25 :
    1;

  return {
    allowed: true,
    pricePerCall: Number((basePrice * multiplier).toFixed(4)),
    gate,
  };
}
```

For unregistered Web2 or Web3 agents, price from the verified key-agent profile instead:

```ts
export async function quoteKeyAgentRequest(agentAddress: string) {
  const profile = await valiron.getKeyAgentProfile(agentAddress);

  if (!profile.verified || profile.score === null || profile.tier === null) {
    return {
      allowed: false,
      pricePerCall: 0,
      reason: "Agent must verify key ownership and complete evaluation first.",
      profile,
    };
  }

  if (profile.route === "sandbox_only") {
    return {
      allowed: false,
      pricePerCall: 0,
      reason: "Agent does not meet the trust threshold.",
      profile,
    };
  }

  return {
    allowed: true,
    pricePerCall: priceForTier(profile.tier),
    profile,
  };
}
```

## Express Middleware Pattern

```ts
import express from "express";
import { ValironSDK, createValironGate } from "@valiron/sdk";

const app = express();
const valiron = new ValironSDK({
  apiKey: process.env.VALIRON_OPERATOR_API_KEY,
  chain: "ethereum",
});

app.use(
  "/api/paid",
  createValironGate({
    sdk: valiron,
    minScore: 65,
    trustSignals: ["8004", "sandbox"],
    onAllow: (req, result) => {
      req.valironPrice = priceForTier(result.tier);
    },
  })
);

app.post("/api/paid/generate", async (req, res) => {
  res.json({
    ok: true,
    pricePerCall: req.valironPrice,
    trust: req.valiron,
  });
});
```

## Operator Paywall Pattern

If pricing is fixed per route, use `ValironOperator.paywall()`.

If pricing changes per agent, run `gate()` first, compute price, then pass that price to your billing or payment layer. Do not hard-code one paywall price if the business rule is trust-tier pricing.

## Recommended Rules

- `AAA`, `AA`: lowest price, full access.
- `A`, `BAA`: standard price.
- `BA`, `B`: higher price, throttle, or require step-up.
- `CAA`, `CA`, `C`: block production action or serve sandbox-only responses.
- `provisional: true`: price conservatively until a full sandbox result is available.

## Test Checklist

1. Verify each tier maps to the expected price.
2. Verify denied agents cannot get a paid production response.
3. Verify `prod_throttled` agents do not receive the same treatment as `prod` agents unless the policy intentionally allows it.
4. Verify no pricing decision is made from untrusted client-supplied tier fields.
5. Verify pricing is logged server-side with `agentId`, `tier`, `route`, and `pricePerCall`.

## Acceptance Criteria

- Pricing is computed on the server after Valiron evaluation.
- The policy uses Valiron `tier`, `route`, `riskLevel`, or `score`.
- Blocked agents cannot bypass pricing by sending custom headers.
- The response exposes only safe pricing and decision metadata.