---
name: valiron-agent-profile-lookup
version: 1.0.0
description: Look up an agent's Valiron trust profile, including World ID, Self, and Icebreaker enriched human trust signals when available.
homepage: https://www.valiron.co
---

# Valiron Agent Profile Lookup Skill

Use this skill when the user wants to inspect who an agent is, what trust signals it has, and whether it has human-linked context from World ID, Self, or Icebreaker.

## Goal

Fetch and interpret Valiron profiles for an agent:

- On-chain identity and wallet.
- On-chain reputation.
- Local behavioral reputation.
- Routing decision.
- World ID proof-of-personhood status.
- Self eligible-human and Agent ID status.
- Icebreaker human/background attestation.

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

Baseline public profile reads can work without an API key, but enriched/account-scoped usage should be configured with the operator key from the start.

## 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: Identify the Agent

Use `x-agent-id` only for agents registered in ERC-8004 or Solana 8004:

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

Use `x-agent-address` for Web2 agents or Web3 agents that are not registered in ERC-8004 or Solana 8004:

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

If the app only has a wallet address, first try `resolveWallet()`. If no 8004 agent ID is resolved, treat the caller as key-based and use `x-agent-address`. If the agent does not have a persistent keypair identity, use `https://www.valiron.co/auth.md`.

## Step 5: Basic Profile Lookup

```ts
const profile = await valiron.getAgentProfile("25459", {
  trustSignals: ["8004", "sandbox", "world", "self", "icebreaker"],
});

console.log(profile.identity.name);
console.log(profile.identity.wallet);
console.log(profile.routing.finalRoute);
console.log(profile.localReputation?.tier);
console.log(profile.localReputation?.riskLevel);
```

For Web2 agents or unregistered Web3 agents, look up the verified key-based profile:

```ts
const keyProfile = await valiron.getKeyAgentProfile("0xAgentAddress");

console.log(keyProfile.verified);
console.log(keyProfile.score);
console.log(keyProfile.tier);
console.log(keyProfile.route);
console.log(keyProfile.icebreaker);
```

## Step 6: World ID Profile

```ts
const worldProfile = await valiron.getWorldIdProfile("25459");

console.log(worldProfile.worldId.verified);
console.log(worldProfile.humanTrust.hasHumanLink);
console.log(worldProfile.humanTrust.verificationLevel);
console.log(worldProfile.icebreaker.verifiedHandles);
console.log(worldProfile.reasons);
```

Use this when the decision depends on proof-of-personhood or a combined World ID plus Icebreaker view.

## Step 7: Self Profile

```ts
const selfProfile = await valiron.getSelfProfile("25459");

console.log(selfProfile.self.verified);
console.log(selfProfile.humanTrust.hasEligibleHuman);
console.log(selfProfile.humanTrust.hasAgentBinding);
console.log(selfProfile.self.selfAgentId);
console.log(selfProfile.reasons);
```

Use this when the decision depends on Self eligible-human predicates, OFAC/country eligibility, age predicates, or Self Agent ID binding.

## Step 8: Wallet Lookup

If the app has a wallet address instead of an agent ID:

```ts
const resolution = await valiron.resolveWallet("0x52ce...", { chain: "base" });

if (resolution.agentId) {
  const profile = await valiron.getAgentProfile(resolution.agentId, {
    chain: "base",
    trustSignals: ["8004", "sandbox", "world", "self", "icebreaker"],
  });
}
```

If `resolution.agentId` is `null`, do not send the wallet as `x-agent-id`. Use the key-based identity path and send it as `x-agent-address` after challenge verification.

## Step 9: Server Route Example

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

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

export async function GET(request: Request) {
  const url = new URL(request.url);
  const agentId = url.searchParams.get("agentId");

  if (!agentId) {
    return Response.json({ error: "agentId is required" }, { status: 400 });
  }

  const [profile, world, self] = await Promise.all([
    valiron.getAgentProfile(agentId, {
      trustSignals: ["8004", "sandbox", "world", "self", "icebreaker"],
    }),
    valiron.getWorldIdProfile(agentId).catch(() => null),
    valiron.getSelfProfile(agentId).catch(() => null),
  ]);

  return Response.json({
    agentId,
    identity: profile.identity,
    routing: profile.routing,
    tier: profile.localReputation?.tier ?? null,
    riskLevel: profile.localReputation?.riskLevel ?? null,
    worldId: world?.worldId ?? null,
    self: self?.self ?? null,
    icebreaker: world?.icebreaker ?? null,
  });
}
```

## Decision Examples

Allow a high-trust agent:

```ts
const allow =
  profile.routing.finalRoute === "prod" &&
  profile.localReputation?.riskLevel === "GREEN";
```

Require human-linked context:

```ts
const hasHumanSignal =
  worldProfile.humanTrust.hasHumanLink ||
  selfProfile.humanTrust.hasEligibleHuman ||
  Boolean(worldProfile.icebreaker.attested);
```

Require Self Agent ID binding:

```ts
const hasSelfAgentBinding =
  selfProfile.self.verified &&
  selfProfile.self.selfAgentLinked === true;
```

## Plan Boundaries

`8004` and `sandbox` are the baseline signals. `world`, `self`, and `icebreaker` are enriched signals and may require Pro or Enterprise access when used as selected scoring signals.

## Test Checklist

1. Fetch an agent with baseline `getAgentProfile()`.
2. Fetch World ID status/profile for the same agent.
3. Fetch Self status/profile for the same agent.
4. Verify missing enriched signals are handled as `null` or `verified: false`.
5. Verify UI and logs distinguish "not verified" from "lookup failed".

## Acceptance Criteria

- The lookup returns agent identity, route, tier, and risk level.
- World ID, Self, and Icebreaker signals are included when available.
- Missing enriched signals do not crash the route.
- The app does not claim a human link unless the relevant signal is verified or attested.