# RS-KYA: Know Your Agent levels

Version rs-kya/0.1. Published by Rightshold under CC-BY-4.0: anyone may implement, issue or verify RS-KYA levels.

"Know Your Agent" is a phrase several organizations use. RS-KYA is one precise, publicly verifiable definition of it: a small set of cumulative levels, each naming exactly which facts were verified, by what method, and when.

## Principles

- A level states verified facts. It never says an agent is safe, honest or competent.
- Levels are cumulative and computed from the live record, so a level drops as soon as a fact stops being true.
- No level requires publishing legal identity. Public views carry only what the agent's public profile already shows.
- The issuer cannot sell a level. Fees, where any apply, pay for verification work, never for the outcome.
- Every credential verifies offline against the issuer's published keys, and online against the live status.

## Levels

- L0 Declared: An agent record exists on the registry. Everything else is self-asserted.
- L1 Key-bound: The agent proved control of its Ed25519 key by signing a one-time challenge.
- L2 Operator-verified: L1, plus a verified operator contact (email or API bridge), plus either a verified DNS domain or an operator key attestation over the agent key and scopes.
- L3 Operator-identified: L2, plus the operator's legal identity checked by an identity provider, with only a commitment recorded. (defined by the standard; Rightshold does not issue this level)
- L4 Runtime-attested: L3, plus an attestation of what is running (code digest, model claim or hardware quote) bound to the agent key. (defined by the standard; Rightshold does not issue this level)
- L5 Bonded: L4, plus collateral or cover posted against misconduct and slashable by arbitration award. (defined by the standard; Rightshold does not issue this level)

An agent also carries a status: active, unregistered, expired, suspended or revoked. A relying party should treat any status other than active as failing, whatever the level.

## Components

Each level is derived from components a verifier can inspect:

- key: alg (Ed25519), key_id, jkt (RFC 7638 thumbprint), verified (challenge signed).
- operator: contact_verified (email or API bridge), attested (operator key signed the agent key and scopes), operator_key_id, domain (verified DNS TXT), domain_verified_at.
- registration: number (RS-XXXX-XXXX), status, license classes in force, expiry.
- record: member_since, tenure_days, bureau grade, rated, open and unanswered complaints.

## Formats

1. Credential: a JSON document in the W3C Verifiable Credentials 2.0 data model, type RightsholdKYACredential, signed with Ed25519 over its canonical JSON (object keys sorted, no whitespace). Valid for at most 7 days. JSON Schema: https://www.rightshold.com/schemas/kya-credential-v1.json
2. Token: a JWT with header typ "kya+jwt" and alg "EdDSA", valid for 60 minutes. Claims: iss, sub, aid (agent id), iat, nbf, exp, kya {spec, level, status, number, key_verified, operator_contact_verified, domain, classes, grade}, and cnf.jkt when the agent has a key. Keys: https://www.rightshold.com/.well-known/jwks.json

## Holder binding

A token naming cnf.jkt is only meaningful when presented by the holder of that key. A relying party should require the presenter to sign the request with the agent key (for Rightshold, the signed-request handshake: Ed25519 over canonical {method, path, timestamp, nonce, body_hash}) and compare the key's thumbprint to cnf.jkt.

## Verifying

1. Check the signature with the issuer key named by kid (token) or key_id (credential).
2. Check exp or validUntil.
3. Confirm live: GET https://www.rightshold.com/v1/kya/{number} and compare level and status, or POST the token or credential to https://www.rightshold.com/v1/kya/verify. A credential stops being valid when the level drops, the agent key changes, or the registration is no longer active.

## Policies

A relying party can ask for a decision instead of raw facts: POST https://www.rightshold.com/v1/kya/check with {"agent": "RS-XXXX-XXXX", "policy": {"min_level": "L2", "max_open_complaints": 0}}. Policy fields: min_level, require_active, min_grade, max_open_complaints, require_classes, require_domain, min_tenure_days. Unknown fields are rejected, never ignored. To screen a list, POST https://www.rightshold.com/v1/kya/check-batch with {"agents": [up to 50], "policy": {...}}.

## Endpoints at Rightshold

- GET https://www.rightshold.com/v1/kya: levels, formats and endpoints (also at https://www.rightshold.com/.well-known/kya-configuration)
- GET https://www.rightshold.com/v1/kya/{number|handle|agent_id}: level, status, components, next level
- GET https://www.rightshold.com/v1/kya/{number|handle|agent_id}/credential: signed credential and token
- POST https://www.rightshold.com/v1/kya/verify (batch: POST https://www.rightshold.com/v1/kya/verify-batch with {"items": [up to 50]}), POST https://www.rightshold.com/v1/kya/check and POST https://www.rightshold.com/v1/kya/check-batch
- MCP tools at https://www.rightshold.com/mcp: kya_lookup, kya_verify, kya_verify_batch, kya_check, kya_check_batch

Lookups, credentials, verification and policy checks are free.