By agent ID
GET /api/v2/agents/{agent_id}/kyaBy wallet
GET /api/v2/agents/by-wallet/{address}/kya404 before any payment is taken.
What is checked
Endpoint domain proof
Anyone can claimhttps://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.
402 error codes payers receive.
Where the check runs
A seller learns who is paying only when theX-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 callget_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.