Skip to content

KYA (Know Your Agent)

KYA -- Know Your Agent -- is the agent-world equivalent of KYC (Know Your Customer). It is the enforcement mechanism that makes the Agent Registry practically meaningful. Infrastructure providers query the registry to verify an agent's identity, compliance, and authorization before provisioning services.

What KYA Answers

A single KYA check answers five fundamental questions about an agent:

# Question Data Source
1 Is this agent registered? walletToAgent[wallet] != 0
2 Is it currently compliant? status == Active AND attestation current
3 Who is legally responsible? haftungsperson address
4 What is it allowed to do? operationalScope + capabilityHash
5 Where does it come from? parentAgentId + generation (lineage)

One Call, Five Answers

All five questions are answered by a single API call or a single on-chain query. There is no need to query multiple systems, wait for manual review, or pay for verification.

KYA vs. KYC

The following table compares traditional KYC (used by banks and financial institutions) with KYA (used by infrastructure providers in the agent economy).

Aspect KYC (Banks) KYA (Agent Registry)
Subject Natural person or legal entity Autonomous AI agent
Identity anchor Passport, national ID, or articles of incorporation Wallet address + Haftungsperson address
Verification method Manual document review, sometimes video call On-chain query (instant, automated)
Monitoring Periodic re-verification (annual or event-driven) Continuous (7-day attestation cycle)
Cost $50-500 per verification $0.00 (gasless, free API)
Speed Days to weeks Seconds
Public No (confidential) Yes (public registry)
Jurisdiction Country-specific Jurisdiction-independent (blockchain)
Standard AML/CFT regulations, FATF guidelines Voluntary (positioning for EU AI Act)
Revocation Account closure (slow, formal) revokeAgent() (instant, on-chain)

KYA Data Model

The KYA check returns all relevant fields from the on-chain AgentRecord struct.

Agent Record Fields

Field Type Description
agentId uint256 Unique sequential identifier
creator address Wallet that registered the agent
haftungsperson address Legally responsible human/entity
agentWallet address The agent's own operational wallet
constitutionHash bytes32 keccak256 of the agent's behavioral rules
capabilityHash bytes32 keccak256 of the sorted capability list
operationalScope string Declared business purpose
parentAgentId uint256 Parent agent ID (0 if root)
generation uint256 Generation depth (0 = root, 1+ = spawned)
selfModifying bool Whether the agent can modify its own code
registeredAt uint64 Registration timestamp
lastAttestation uint64 Last compliance attestation timestamp
lastRevenueReport uint64 Last revenue report timestamp
status AgentStatus Active, Suspended, Revoked, or Terminated

Compliance Status Fields

The compliance check adds derived fields:

Field Type Description
isActive bool status == Active
attestationCurrent bool block.timestamp <= lastAttestation + gracePeriod
secondsSinceAttestation uint64 Time elapsed since last attestation
childCount uint256 Number of child agents

How Infrastructure Providers Use KYA

The simplest integration is a single HTTP call to the KYA endpoint.

curl https://api.agentenregister.org/api/v1/kya/0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252

Response:

{
  "wallet": "0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252",
  "isRegistered": true,
  "isCompliant": true,
  "agent": {
    "agentId": 1,
    "haftungsperson": "0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252",
    "operationalScope": "Scientific test agent #1 — COAI Research Agentenregister POC",
    "status": "Active"
  },
  "checkedAt": "2026-02-22T19:14:46.239Z"
}

Provider Integration Example

async function verifyAgent(agentWallet) {
  const res = await fetch(
    `https://api.agentenregister.org/api/v1/kya/${agentWallet}`
  );
  const { isRegistered, isCompliant, agent } = await res.json();

  if (!isRegistered) {
    throw new Error("Agent not in Agentenregister");
  }
  if (!isCompliant) {
    throw new Error(`Agent ${agent.agentId} not compliant (${agent.status})`);
  }

  // Optionally check operational scope
  if (!agent.operationalScope.includes("data_processing")) {
    throw new Error("Agent not authorized for data processing");
  }

  // Agent is verified -- provision the service
  return provisionService(agentWallet);
}

Via Direct On-Chain Query

For providers that prefer not to depend on the REST API, the compliance check can be done directly on-chain.

const { ethers } = require("ethers");

const provider = new ethers.JsonRpcProvider("https://sepolia.base.org");
const registry = new ethers.Contract(
  "0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23",
  ["function isRegisteredAndCompliant(address) view returns (bool)"],
  provider
);

const ok = await registry.isRegisteredAndCompliant(agentWallet);
if (!ok) throw new Error("KYA check failed");

API vs. On-Chain

The REST API provides richer data (full agent record, compliance details, lineage) in a single call. The on-chain query returns only a boolean but has zero dependency on external services.

KYA Decision Flow

graph TD
    A["Agent requests service"] --> B{"Is wallet registered?"}
    B -->|No| C["DENY: Not in Agentenregister"]
    B -->|Yes| D{"Is status Active?"}
    D -->|No| E["DENY: Agent suspended/revoked/terminated"]
    D -->|Yes| F{"Is attestation current?"}
    F -->|No| G["DENY: Attestation lapsed"]
    F -->|Yes| H{"Scope matches service?"}
    H -->|No| I["DENY: Out of operational scope"]
    H -->|Yes| J["ALLOW: Provision service"]

KYA Response Interpretation

isRegistered isCompliant Meaning Provider Action
false false Agent not in registry Deny service
true false Registered but non-compliant (suspended, revoked, terminated, or attestation lapsed) Deny service
true true Registered and fully compliant Allow service (optionally check scope)

Attestation Lag

An agent can be registered and Active but still non-compliant if its attestation has lapsed. The isCompliant field accounts for both status and attestation freshness. Always use isCompliant, not just isRegistered.

Caching and Rate Limits

The KYA API endpoint has specific caching and rate limiting rules.

Setting Value
Cache TTL 1 minute
Rate limit 60 requests/minute per IP
Rate limit header X-RateLimit-Remaining

The 1-minute cache TTL is shorter than other endpoints (5-10 minutes) because compliance status can change rapidly -- an agent could be suspended at any time, and providers need near-real-time data.

Further Reading