> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Know Your Agent

> Decide whether to serve, pay or lend to an onchain AI agent with one call: identity, operator, sanctions screening and a pass/review/block verdict

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](https://eips.ethereum.org/EIPS/eip-8004) agent ID, or just the wallet that is paying you, and Cred returns one profile with coded flags and a verdict.

> [card] By agent ID
>
> `GET /api/v2/agents/{agent_id}/kya`

> [card] 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](https://docs.credprotocol.com/api-reference/sanctions/screen.md) and [exposure](https://docs.credprotocol.com/api-reference/sanctions/exposure.md), 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:

```json theme={null}
{
  "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

```bash theme={null}
curl https://api.credprotocol.com/api/v2/agents/by-wallet/0x2222222222222222222222222222222222222222/kya \
  -H "Authorization: Bearer $CRED_API_KEY"
```

```json theme={null}
{
  "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]
}
```

> [!NOTE]
>
> 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](https://docs.credprotocol.com/compliance/delivery-modes.md).

## 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](https://docs.credprotocol.com/sdks/typescript.md#screen-x402-payers-know-your-agent).
* **Python** (`x402`, async or sync server): `register_cred_kya(server, api_key=...)`. See [the Python SDK](https://docs.credprotocol.com/sdks/python.md#screen-x402-payers-know-your-agent).

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

## From MCP

Agents using the [Cred MCP server](https://docs.credprotocol.com/mcp-services/agent-skill.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.