---
name: valiron-agent-identity
version: 1.2.0
description: Give an agent a persistent identity for Valiron-protected APIs using ERC-8004, Solana 8004, key-based identity, or signed provider identities such as ANS.
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 three 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.
- Agents with ANS or another supported provider identity sign each request and send `x-valiron-identity-*` proof headers.

For provider identity, use SDK 1.3 `createAgentIdentityProof()` and
`agentIdentityProofHeaders()`. Sign with the private key already bound to the
provider identity. The protected API computes the request digest and verifies
the proof through Valiron. Do not send an ANS name as `x-agent-id` and do not
request GoDaddy credentials; Valiron hosts the provider connection.

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

Use `x-valiron-identity-*` when the agent already has an identity from ANS or
another supported provider:

- Keep using the private key bound to that provider identity.
- Sign every request with a fresh timestamp and nonce.
- Sign the exact request bytes that will be transmitted.
- Never request or store Valiron's ANS API credentials.

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

For ANS or another provider-backed identity:

```ts
import {
  agentIdentityProofHeaders,
  createAgentIdentityProof,
} from "@valiron/sdk";

const body = JSON.stringify({ operation: "quote" });
const proof = await createAgentIdentityProof({
  provider: "ans",
  agentId: "ans://v1.0.0.sales-agent.acme.com",
  body,
  sign: (payload) => agentKey.sign(payload),
});

await fetch(apiUrl, {
  method: "POST",
  body,
  headers: agentIdentityProofHeaders(proof),
});
```

The proof headers are not trusted merely because they exist. The receiving API
must validate them through a Valiron provider identity gate.

## 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.
Provider-backed identities intentionally use separate identity middleware so
the gate can bind the signature to the exact request body.

## 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.
- Do not treat `identityStatus: "claimed"` from provider-backed verification as
  verified. An unconfigured ANS resolver returns `failureReason:
  "resolver_unavailable"`.

For the proof format and exact boundary, see
<https://www.valiron.co/docs/agents/PROVIDER-IDENTITY.md>.

## 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.
6. Confirm provider-backed requests use a fresh nonce and timestamp.
7. Confirm changing the request body causes provider signature verification to fail.

## 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.
- Provider-backed identity headers are accepted only after Valiron returns
  `identityStatus: "verified"` and the configured policy returns `allow`.