Skip to main content
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

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: To verify your own agent, serve the following JSON at that path on each of your endpoint domains:

Verdict and flags

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

Example

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.

Where the check runs

A seller learns who is paying only when the X-PAYMENT header arrives. The hook runs in the window between the facilitator’s verify and settle: after verify, so only a payer who really signed the payment is looked up (a forged from address can’t spend your Cred Units), and before settle, so a refused payer’s funds never move.

Choosing a policy

The Python SDK uses the same settings in snake case (refuse_flags, no_agent). The diagram shows the default authorization flow. The upfront and escrow flows have no verify step, so the hook runs just before their early settle instead. Store the verdict, the flag codes and compliance.lists_checked from onDecision (on_decision in Python) next to the payment record: they show which lists you screened against when you accepted the payment.

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.