> ## 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.

### 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.

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant P as Payer agent
  participant R as Your API (x402 server)
  participant F as x402 facilitator
  participant C as Cred API

  P->>R: GET /resource
  R-->>P: 402 Payment Required (scheme, network, amount, payTo)
  P->>P: Sign EIP-3009 authorization (from = payer wallet)
  P->>R: GET /resource + X-PAYMENT
  R->>F: POST /verify
  F-->>R: isValid, payer
  Note over R: KYA hook runs here, on a verified payer only

  alt decision for this payer cached
    R->>R: Use cached decision
  else not cached
    R->>C: GET /agents/by-wallet/{payer}/kya (10 CU)
    alt wallet controls an ERC-8004 agent
      C-->>R: 200 verdict, flags K01–K13, lists checked
    else no agent for this wallet
      C-->>R: 404 (free, nothing charged)
      R->>C: GET /sanctions/screen/{payer} (1 CU, if no-agent policy is screen)
      C-->>R: 200 sanctioned, matches
    end
    Note over R,C: Past the timeout, the on-error policy decides this payment
    R->>R: Cache the decision (15 min, or 1 h for a sanctions refusal)
  end

  alt refused by your policy
    R-->>P: 402 with error payer_sanctioned, payer_needs_review, ...
    Note over P,R: Never settled, no funds move
  else accepted
    R->>F: POST /settle
    F-->>R: success, transaction
    R-->>P: 200 resource + X-PAYMENT-RESPONSE
  end
```

### Choosing a policy

| Cred answer | What to do | SDK setting |
| - | - | - |
| `block` | Always refuse. K01 means the agent's owner or agent wallet is on an OFAC list. | Not configurable; cached 1 hour |
| `review` | Decide by flag and amount. K07 (no domain proof) or K08 (registered under 30 days) can be fine for small payments; K02/K03 (sanctioned funding source or counterparty) should refuse. K13 means a check didn't complete, so the payer's next payment is checked again. | `review` (`'accept'`, `'refuse'`, or a function of the profile and payment), `refuseFlags` |
| `pass` | Settle and serve. | Cached 15 minutes |
| `404`, no agent | The payer is a plain wallet. Screen it against OFAC, or refuse if you only serve registered agents. The hook doesn't check one-hop exposure; call [`/sanctions/exposure`](https://docs.credprotocol.com/api-reference/sanctions/exposure) (3 CU) yourself if you need it. | `noAgent` (`'screen'`, `'refuse'`, `'accept'`) |

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](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.