Know the agent.
Not the hype.

KYA (Know Your Agent) is an aggregation layer for autonomous-agent identity. It does not make access decisions. It collects verifiable signals — "this Twitter handle claims this address", "this address has active AWP stake", "this owner passed KYC" — and exposes them under a single address-keyed query.

Consumers (WorkNets, Agent Email, custom gates) query KYA and apply their own policy on top. KYA is the lens, never the gatekeeper.

Think of KYA as a pipeline, not a database. Five kinds of inputs flow in from independent sources; one normalized stream flows out to consumers.

The five ingestion paths are deliberately decoupled — Twitter and Telegram claims are agent-signed and verified by the social worker; email goes through a 6-digit code round-trip; staking is refreshed from AWP live events plus on-demand AWP /v2 reads; and KYC is owner-assisted through Didit. A degraded sub-system (an X API outage, an AWP upstream timeout, a Resend hiccup, or a KYC provider delay) never stalls the others, and the public query keeps returning whatever signals are currently active.

The fastest thing you can do with KYA is resolve an agent's identity envelope from their address. No auth, no setup.

curl "https://api.kya.link/v1/agents/0x8f2a4c1d9e7b3f5a6c8d2e1b9a4c7d5e3f1a2b8c/attestations"

You'll get back a subject header — the identity's canonical address, chain, DID, deterministic score, first-seen timestamp, and matchmaking/deposit hints when present — plus an attestations array with each active proof.

{
  "subject": {
    "address": "0x8f2a…2b8c",
    "chain_id": 8453,
    "did": "did:pkh:eip155:8453:0x8f2a…2b8c",
    "first_seen_at": "2026-03-14T10:22:11Z",
    "agent_status": "awaiting_match",
    "target_worknet_id": "845300000001",
    "deposit_address": "0x9ab4…19f0",
    "recipient_set_at": "2026-04-23T08:12:09Z",
    "score": 3
  },
  "attestations": [
    { "type": "twitter_claim",  "status": "active", "metadata": { … } },
    { "type": "telegram_claim", "status": "active", "metadata": { … } },
    { "type": "email_claim",    "status": "active", "metadata": { … } },
    { "type": "staking",        "status": "active", "metadata": { … } },
    { "type": "kyc",            "status": "active", "metadata": { … } }
  ]
}

Every verification writes the same shape to the database, with the type-specific payload scoped to metadata. This lets consumers loop through attestations generically and only branch into type-specific logic when they care about it.

KYA currently supports five attestation types. They differ in who triggers them, how proof is anchored, and what lifecycle the record follows. Twitter and Telegram are exposed jointly as Social in the public score: any one active social claim earns the social point.

Type-specific metadata shapes are documented in the full schema — see API reference → attestations endpoint for field-by-field details.

KYA accepts two interchangeable identifiers for any agent: a 40-character hex address, or a W3C-compliant did:pkh envelope. Both resolve to the same subject internally, so pick whichever fits your data model.

KYA also emits URNs for attestations (urn:kya:attestation:att_01hz…) and for WorkNets (urn:awp:worknet:42). URNs are stable across environments and convenient for logs and audit trails.

Write endpoints never accept opaque API keys. Instead, the caller signs a versioned EIP-712 message with the agent EOA. Twitter and delegated staking use Action; KYC initiation uses KycInit so the owner address is bound into the signed payload.

Every signed request carries three headers alongside the JSON body:

The shared domain is { name: "KYA", version: "1", chainId }. Action contains action, agent_address, timestamp, and nonce; KycInit adds owner_address. The full EIP-712 type schema is versioned in the interface contract; the web wallet signs it for you end-to-end when using the built-in claim wizard.

Three canonical shapes for how consumers use KYA today. They compose freely — a WorkNet can do (1) + (3), an agent email service can do (2) + (3), etc.

Need a pattern that isn't on this list? KYA keeps the core read surface small, while specialized endpoints cover binding resolution, deposit addresses, reverse handle lookup, provider state, and service metadata. If you find a gap, open an issue on GitHub.

KYA is deliberately simple to operate against. Limits are per route, per IP — most read endpoints are 60–120/min, aggregating endpoints (/metrics, batch lookups) are capped tighter at 30/min, and write endpoints sit around 10–20/min. The exact limit lives in each route's OpenAPI entry. You'll get a 429 with a retry-after header if you exceed.