---
name: valiron-agent-identity
version: 1.0.0
description: Give an agent a persistent identity for Valiron-protected APIs, supporting registered ERC-8004/Solana 8004 agent IDs and key-based identities for Web2 or unregistered Web3 agents.
homepage: https://www.valiron.co
---

# Valiron Agent Identity Skill

Use this skill when the user needs an agent to identify itself to a Valiron-protected API.

## Goal

Ensure every agent request has a stable identifier that Valiron can evaluate.

Valiron supports two identity paths:

- Agents registered in ERC-8004 or Solana 8004 use `x-agent-id`.
- Every agent not registered in ERC-8004 or Solana 8004 uses a generated persistent keypair and sends `x-agent-address`. This includes Web2 agents and Web3 agents that have wallets but no 8004 registration.

## 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_...
```

The key is used by protected middleware, operator analytics, and account-scoped features. Keep it server-side.

## Step 2: Install Dependencies

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

or:

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

`viem` is used to create and sign with Ethereum-style keypairs for key-based agents.

## Step 3: Configure Valiron

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

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

## Step 4: Choose Identity Path

Use `x-agent-id` when the agent is registered in an 8004 registry:

- ERC-8004 EVM agent.
- Solana 8004 agent.

Use `x-agent-address` when the agent is not registered in ERC-8004 or Solana 8004:

- Generate a persistent Ethereum-style keypair.
- Prove ownership with challenge-response.
- Reuse the same address on every request.
- This path applies to Web2 agents and unregistered Web3 agents.

## Step 5: Fastest Path For Key-Based Agents

Use Valiron's hosted agent identity instructions:

```text
https://www.valiron.co/auth.md
```

Tell the coding agent to follow that file exactly. It creates or reuses `agent-identity.json`, signs challenges, and stores a session token.

## Step 6: Key-Based Agent Verification With SDK

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

const valiron = new ValironSDK({
  apiKey: process.env.VALIRON_OPERATOR_API_KEY,
});
const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const agentAddress = account.address;

const { challenge } = await valiron.getKeyAgentChallenge(agentAddress);
const signature = await account.signMessage({ message: challenge });

const profile = await valiron.verifyKeyAgent({
  challenge,
  signature,
  agentAddress,
});

console.log(profile.verified);
console.log(profile.route);
console.log(profile.tier);
```

## Step 7: Send Requests With Identity Headers

For registered ERC-8004 or Solana 8004 agents:

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

For Web2 agents or unregistered Web3 agents:

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

If the protected API returns `challenge_required`, sign the challenge and retry with:

```http
x-agent-address: 0xAgentAddress
x-agent-challenge: challenge text
x-agent-signature: 0xSignature
```

If the API returns `x-agent-session`, store it and send:

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

## Middleware Compatibility

Valiron middleware auto-detects identity:

1. It first checks `x-agent-id`.
2. It then falls back to `x-agent-address`.
3. Legacy `x-agent-key-hash` may also be accepted by older integrations.

No separate middleware is required for key-based agents.

## Common Mistakes

- Do not send a local name like `my-agent` to `/operator/agent/:agentId`.
- Do not send a wallet address as `x-agent-id`; if the agent is not registered in 8004, use `x-agent-address`.
- Do not regenerate a new keypair on every request.
- Do not store the private key in frontend/browser code.
- Do not derive Ethereum addresses manually with SHA3; use `viem` or a trusted wallet library.
- Do not treat an unverified key address as a trusted identity.

## Test Checklist

1. Confirm the agent has one stable identifier across restarts.
2. Confirm registered ERC-8004 or Solana 8004 agents send `x-agent-id`.
3. Confirm Web2 and unregistered Web3 agents send `x-agent-address`.
4. Confirm key-based agents can complete challenge-response.
5. Confirm a session token is reused until expiry.

## Acceptance Criteria

- Every protected request carries a Valiron-readable identity header.
- Key-based identities are backed by a persistent private key.
- Challenge signatures are generated server-side or by the agent runtime, not by a browser user.
- The integration can fetch a Valiron profile for the chosen identity.