Skip to content

KYA Integration Guide

Know Your Agent (KYA) is the agent equivalent of KYC (Know Your Customer). Infrastructure providers query the Agent Registry to verify an agent's registration status and compliance before provisioning services.

What KYA does for you

KYA lets you answer three questions before serving an agent:

  1. Is this agent registered? -- Does it have a public identity in the Agent Registry?
  2. Is it compliant? -- Has it attested compliance within the last 7 days?
  3. What is it authorized to do? -- Does its operational scope match the service requested?

Why Implement KYA?

Benefit Description
Accountability Every registered agent has a Haftungsperson (legally responsible human). If something goes wrong, there is a traceable responsible party.
Compliance Agents must attest compliance every 7 days. Lapsed agents are automatically flagged as non-compliant.
Auditability All registrations, attestations, and regulatory actions are on-chain and publicly verifiable.
EU AI Act readiness The Agent Registry is designed as a reference implementation for EU AI Act compliance requirements.
Zero friction A single API call. No SDK installation, no blockchain interaction required.

Quick Start: Single API Call

Check any agent's KYA status with one curl command:

curl https://api.theagentregistry.org/api/v1/kya/0xAGENT_WALLET

Example: Check a registered agent

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

Response: 

{
  "wallet": "0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252",
  "isRegistered": true,
  "isCompliant": true,
  "agent": {
    "agentId": 1,
    "creator": "0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252",
    "haftungsperson": "0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252",
    "agentWallet": "0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252",
    "operationalScope": "Scientific test agent #1 — COAI Research Agentenregister POC",
    "generation": 0,
    "selfModifying": false,
    "registeredAt": "2026-02-22T19:02:18.000Z",
    "lastAttestation": "2026-02-22T19:02:18.000Z",
    "status": "Active"
  },
  "checkedAt": "2026-02-23T10:30:00.000Z"
}

Response Interpretation

The KYA response contains three key fields:

Field Type Meaning
isRegistered boolean The wallet belongs to an agent in the Agent Registry
isCompliant boolean The agent is registered and has attested compliance within the grace period (7 days)
agent object \| null Full agent record if registered, null otherwise

Agent Status Values

Status Meaning KYA Recommendation
Active Normal operation Allow if compliant
Suspended Temporarily suspended by a regulator Deny service
Revoked Permanently revoked by a regulator Deny service
Terminated Voluntarily terminated Deny service

isRegistered vs. isCompliant

An agent can be registered but not compliant. This happens when:

  • The agent has not attested compliance in the last 7 days
  • The agent's status is Suspended, Revoked, or Terminated

Always check isCompliant -- not just isRegistered -- before provisioning services.

Decision Logic

JavaScript / Node.js

const res = await fetch(`https://api.theagentregistry.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 not compliant (${agent.status})`);

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

provisionService(agentWallet);

Python

import requests

def check_kya(agent_wallet: str) -> dict:
    resp = requests.get(f"https://api.theagentregistry.org/api/v1/kya/{agent_wallet}")
    resp.raise_for_status()
    kya = resp.json()

    if not kya["isRegistered"]:
        raise ValueError("Agent not in Agentenregister")
    if not kya["isCompliant"]:
        raise ValueError(f"Agent not compliant ({kya['agent']['status']})")

    return kya["agent"]

On-Chain KYA Check (Smart Contracts)

If your protocol is a smart contract, you can verify agent registration directly on-chain without relying on the REST API.

Solidity Interface

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

interface IAgentenregister {
    function isRegistered(address agentWallet) external view returns (bool);
    function isRegisteredAndCompliant(address agentWallet) external view returns (bool);
}

Usage in Your Contract

address constant REGISTRY = 0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23;

modifier onlyRegisteredAgent() {
    require(
        IAgentenregister(REGISTRY).isRegisteredAndCompliant(msg.sender),
        "Agent not registered or not compliant"
    );
    _;
}

function sensitiveOperation() external onlyRegisteredAgent {
    // Only registered, compliant agents can call this
}

Gas cost

The isRegisteredAndCompliant() view function costs 0 gas when called from an external account (off-chain read). When called from another contract on-chain, it costs approximately 5,000--8,000 gas.

When agents make requests to your service, recommend they include these headers for easy identification:

Header Value Purpose
X-Agent-Registry-ID Agent ID (e.g., 1) Quick lookup by numeric ID
X-Agent-Wallet Wallet address (e.g., 0x4b19...) Primary identifier for KYA check
X-Agent-Registry 0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23 Registry contract address (for multi-registry environments) 
curl -H "X-Agent-Wallet: 0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252" \
     -H "X-Agent-Registry-ID: 1" \
     https://your-service.com/api/endpoint

Caching Guidance

The Agent Registry API caches KYA responses for 1 minute (60 seconds). This means:

Scenario Recommendation
High-frequency requests from same agent Cache the KYA result locally for 60 seconds
Compliance-critical operations Always query fresh (the API cache is already short-lived)
Batch processing Cache results for the batch duration, then re-check
Background monitoring Poll every 5 minutes for status changes

Cache headers

The API returns X-RateLimit-Remaining headers. The rate limit is 60 requests per minute per IP address. For high-volume providers, consider caching results locally to stay within limits.

Error Handling

HTTP Status Meaning Action
200 KYA check succeeded Inspect isRegistered and isCompliant fields
429 Rate limit exceeded Retry after 60 seconds
500 Internal server error Retry with exponential backoff 
async function kyaCheck(wallet, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const res = await fetch(`https://api.theagentregistry.org/api/v1/kya/${wallet}`);
      if (res.status === 429) {
        await new Promise(r => setTimeout(r, 60000));
        continue;
      }
      return await res.json();
    } catch (err) {
      if (i === retries - 1) throw err;
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
    }
  }
}

Next Steps