Know Your Agent

AI agents increasingly pay for APIs (x402, MPP), trade and borrow onchain. Know Your Agent (KYA) answers the question a merchant, an API or another agent has to ask first: should I deal with this agent? Give it an ERC-8004 agent ID, or just the wallet that is paying you, and Cred returns one profile with coded flags and a verdict.

By agent ID

GET /api/v2/agents/{agent_id}/kya

By wallet

GET /api/v2/agents/by-wallet/{address}/kya

10 Cred Units per call. It can be paid with an API key, x402 or MPP, so an agent can check another agent on its own. If the agent doesn’t exist, or the wallet controls no agent, you get a 404 before any payment is taken.

What is checked

Section	What it tells you	Where it comes from
`identity`	Name, description, advertised services, `supportedTrust`, when the agent was registered, and whether each endpoint’s domain vouches for the agent	The agent’s ERC-8004 registration file (`tokenURI`), its mint log on the Identity Registry, and each endpoint domain’s `/.well-known/agent-registration.json`
`operator`	The owner wallet (the one that registered the agent and can transfer it): Cred score, wallet age, transaction count, account type	Cred credit report and score
`agent_wallet`	The wallet the agent transacts from: its verified `agentWallet`, or the owner when none is set. Same fields as `operator`, plus liquidation history	Cred credit report and score
`compliance`	The full sanctions lookup. `screened` gives each wallet (owner, agent wallet) with every OFAC list entry it matches. The agent wallet’s `funding_source` and `sanctioned_counterparties` (up to 25, most recent contact first; all are counted) carry their list entries too, across Base and Ethereum	Sanctions screening and exposure, same shapes
`reputation`	Cred’s ERC-8004 feedback entries about the agent	Reputation Registry

Endpoint domain proof

Anyone can claim https://api.bigbank.com in their registration file. KYA counts an endpoint domain as verified only when https://{domain}/.well-known/agent-registration.json lists this agent in its registrations (agentId together with agentRegistry, eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432). Each endpoint reports a domain_status:

`domain_status`	Meaning
`verified`	The domain names this agent
`mismatch`	The domain names other agents on this registry, but not this one
`absent`	No file, or the file says nothing about this registry
`unreachable`	The domain didn’t answer (retried after 30 s)
`tls_error`	The domain’s TLS certificate doesn’t verify
`unsafe`	The domain resolves to a private address and is never fetched

To verify your own agent, serve the following JSON at that path on each of your endpoint domains:

{
  "registrations": [
    { "agentId": 22, "agentRegistry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" }
  ]
}

Verdict and flags

`verdict`	When
`block`	A `block` flag is raised: the owner or agent wallet is on a sanctions list
`review`	Any `review` flag, or a check that could not complete (listed in `unavailable`). A check that didn’t run never passes
`pass`	No flags, or only `info` flags

Code	Flag	Severity
K01	`sanctioned_controller`: owner or agent wallet is on an OFAC list	block
K02	`sanctioned_funding_source`: the agent wallet was first funded by a sanctioned address	review
K03	`sanctioned_counterparty`: the agent wallet has transacted with a sanctioned address	review
K04	`registration_unreadable`: the registration file couldn’t be read	review
K05	`registration_names_other_agent`: the file’s `registrations` name other agents on this registry, not this one	review
K06	`endpoint_domain_mismatch`: an endpoint domain names other agents	review
K07	`endpoints_unverified`: web endpoints are listed but no domain names the agent	review
K08	`new_registration`: registered less than 30 days ago	review
K09	`new_agent_wallet`: the agent wallet has no transactions, or none older than 30 days	review
K10	`operator_no_history`: the owner wallet has no activity of its own	info
K11	`liquidation_history`: the agent wallet has had lending positions liquidated	info
K12	`contract_controller`: a controller is a contract that is neither a smart wallet nor a multisig	info
K13	`check_incomplete`: part of the check couldn’t complete (see `unavailable`)	review

Flag codes are stable. New flags will be added at the end of the list.

Example

curl https://api.credprotocol.com/api/v2/agents/by-wallet/0x2222222222222222222222222222222222222222/kya \
  -H "Authorization: Bearer $CRED_API_KEY"

{
  "agent_id": 22,
  "agent_registry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
  "verdict": "review",
  "flags": [
    { "code": "K08", "flag": "new_registration", "severity": "review",
      "description": "The agent was registered less than 30 days ago." }
  ],
  "unavailable": [],
  "identity": {
    "name": "Shop Agent",
    "registered_at": "2026-10-20T14:03:11Z",
    "registration_age_days": 14,
    "supported_trust": ["reputation"],
    "endpoints": [
      { "name": "A2A", "endpoint": "https://agent.example.com/.well-known/agent-card.json",
        "domain": "agent.example.com", "domain_status": "verified" }
    ]
  },
  "operator": { "address": "0x1111…", "subject_type": "eoa", "score": 742, "wallet_age_days": 812 },
  "agent_wallet": { "address": "0x2222…", "subject_type": "smart_wallet", "score": 655,
                    "transaction_count": 318, "wallet_age_days": 41, "is_owner": false },
  "compliance": {
    "sanctioned": false,
    "lists_checked": ["ofac_sdn", "ofac_consolidated"],
    "screened": [
      { "address": "0x1111…", "role": "owner", "sanctioned": false, "matches": [] },
      { "address": "0x2222…", "role": "agent_wallet", "sanctioned": false, "matches": [] }
    ],
    "exposure_subject": "0x2222…",
    "exposure_risk": "none",
    "funding_source": { "address": "0xab4c…", "chain_id": 8453, "sanctioned": false, "matches": [] },
    "counterparties_checked": 57,
    "sanctioned_counterparty_count": 0,
    "sanctioned_counterparties": [],
    "chains_checked": [8453, 1]
  },
  "reputation": { "cred_feedback": [] },
  "delivery": { "mode": "commercial", "notice": "Commercial and analytics delivery. …" },
  "resolved_from": "0x2222222222222222222222222222222222222222",
  "agent_ids": [22]
}

KYA is always a commercial delivery. It describes an agent and its wallets, and it is not a consumer report about the person behind them. See delivery modes.

In an x402 server

Sellers on x402 v2 can screen every paying agent before settlement with one line:

TypeScript (@x402/core): registerCredKya(server, { apiKey }). See Screen x402 payers.
Python (x402, async or sync server): register_cred_kya(server, api_key=...). See the Python SDK.

Both pages list the policy options and the 402 error codes payers receive.

From MCP

Agents using the Cred MCP server call get_agent_kya (by agent ID) or get_wallet_kya (by the wallet that is paying you). They cost the same and refuse unknown agents before charging.

Get Started

Use Cases

Guides

On-Chain Reputation

Compliance

By agent ID

By wallet

What is checked

Endpoint domain proof

Verdict and flags

Example

In an x402 server

From MCP

By agent ID

By wallet

​What is checked

​Endpoint domain proof

​Verdict and flags

​Example

​In an x402 server

​From MCP

What is checked

Endpoint domain proof

Verdict and flags

Example

In an x402 server

From MCP