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

# Delivery modes

> What a Cred Protocol score or report may be used for, and how each response says so

Every score and report Cred Protocol returns is delivered in one of two modes. The mode tells you what the response is, what it may be used for, and which fields it carries.

> [card] Commercial / analytics
>
> The default on every rail. Risk analytics, portfolio and counterparty analysis, reputation, fraud and sanctions screening. **Not a consumer report.**

> [card] Consumer report
>
> For credit decisions about individuals. Available only to certified consumer-credit customers, and carries the processes a consumer report requires.

## Commercial / analytics delivery

Commercial delivery is what you get by default, whichever way you call the API:

| Rail | Delivery mode |
| - | - |
| API key (`Authorization: Bearer`) | Commercial, unless the key is certified for consumer credit |
| x402 (`X-PAYMENT`) | Commercial |
| MPP (`Authorization: Payment`) | Commercial |
| MCP server (all tools) | Commercial |
| MetaMask Snap | Commercial |
| Sandbox | `sandbox` (mock data) |

A commercial response is **not a consumer report** and is **not to be used to determine an individual's eligibility for credit, insurance, employment or housing**. Use it for what it is: an analytical view of an address's on-chain history. Typical uses are risk analytics, portfolio and treasury analysis, counterparty and protocol due diligence, agent reputation, fraud and sybil detection, and sanctions screening.

Anonymous rails (x402, MPP, MCP, the Snap) always receive commercial delivery: they carry no certification, so the consumer-mode fields are never included.

## Consumer-report delivery

Lending to an individual on the strength of their score, or otherwise using it to decide whether an individual gets credit, is consumer-report delivery. It is available only on API keys whose owner has been vetted by Cred Protocol and has accepted the consumer-use certification on that key.

Consumer-report responses add what a consumer-credit customer needs:

* **Ranked key factors** — up to four factors, ranked by how much each lowered this address's score, with reason codes, the score range and the date, for adverse-action notices
* **Inquiry record** — every request about the address is recorded and can be disclosed to the address's owner
* **Obsolescence window** — negative items older than seven years are excluded from the score
* **Dispute process** — the owner of an address can dispute how their activity has been interpreted, with a defined reinvestigation period

### Becoming certified

1. **Contact us.** Email [team@credprotocol.com](mailto:team@credprotocol.com) with your company details and how you intend to use scores in credit decisions. We review your legal entity, lending licence or exemption, product and borrower relationship, permissible purpose, data handling and adverse-action process, and ask for a named compliance contact.
2. **We approve your account.** Once the review is complete, we enable consumer-credit certification on your console account.
3. **Accept the certification on a key.** In the console, create an API key (or edit one) with the **Consumer credit** purpose and accept the consumer-use certification. You certify, among other things, that you will request consumer reports only for a permissible purpose, will not resell them, will send adverse-action notices citing the key factors, and will not use them for employment, insurance or housing decisions. Keys with any other purpose are unaffected.

Until all three steps are done, a key with the consumer-credit purpose is still served in commercial mode.

### Stating the purpose of each request

Every consumer-mode request must say why it is being made, in the `X-Cred-Purpose` header:

| `X-Cred-Purpose` | Use |
| - | - |
| `credit_transaction` | Deciding whether to extend credit the consumer applied for |
| `account_review` | Reviewing an existing credit account of the consumer |
| `collection` | Collecting on an account of the consumer |
| `legitimate_business_need` | Another legitimate business need in a transaction the consumer initiated |

If you request reports on behalf of a lender, name it in `X-Cred-End-User` (up to 200 characters). Both values are recorded with the inquiry and shown to the owner of the address when they review who has accessed their file.

```bash theme={null}
curl https://api.credprotocol.com/api/v2/score/address/0x... \
  -H "Authorization: Bearer $CRED_API_KEY" \
  -H "X-Cred-Purpose: credit_transaction" \
  -H "X-Cred-End-User: Acme Lending LLC"
```

A consumer-mode request without a valid purpose is rejected before any Cred Units are charged:

```json theme={null}
HTTP/1.1 400 Bad Request

{
  "detail": {
    "error": "purpose_required",
    "message": "Consumer-report requests must state a permissible purpose in the X-Cred-Purpose header.",
    "allowed": ["credit_transaction", "account_review", "collection", "legitimate_business_need"]
  }
}
```

The headers are ignored on commercial requests.

### When a certification lapses

If your certification is withdrawn, or we publish a new version of the certification that you have not yet accepted, your consumer-credit keys keep working but are served in **commercial** mode: responses carry `delivery.mode: "commercial"` and no key factors. Accept the current certification on the key in the console to restore consumer-report delivery.

## How a response says which mode it is in

Score and report responses carry a `delivery` block, and the same mode is set in the `X-Cred-Delivery-Mode` response header.

```json theme={null}
{
  "score": 812,
  "range": "good",
  "delivery": {
    "mode": "commercial",
    "notice": "Commercial and analytics delivery. Not a consumer report; not to be used to determine an individual's eligibility for credit, insurance, employment or housing."
  }
}
```

| `delivery.mode` | Meaning |
| - | - |
| `commercial` | Commercial / analytics delivery (default) |
| `consumer` | Consumer-report delivery, certified consumer-credit customers only |
| `sandbox` | Mock data from the [sandbox](https://docs.credprotocol.com/guides/sandbox-testing.md) |

```http theme={null}
HTTP/1.1 200 OK
X-Cred-Delivery-Mode: commercial
```

Check the mode in your integration rather than assuming it: a key's mode can change, and the same endpoint serves both.

## Subject type: is the address an individual's wallet?

Single-address scores and full and single-chain reports carry `subject_type` (on the report, under `report.account`), which says what kind of subject the address is:

| `subject_type` | Meaning |
| - | - |
| `eoa` | A wallet controlled by one key, including one with an EIP-7702 delegation |
| `smart_wallet` | An ERC-4337 smart account or a Safe with a single owner: likely one person |
| `multisig` | A Safe with several owners |
| `token` | An ERC-20, ERC-721 or ERC-1155 token contract |
| `contract` | Any other contract (a protocol, a vault, an agent) |
| `unknown` | The address's code could not be read |

A multisig, a token or another contract is not an individual, so it cannot be the subject of a consumer report. In consumer-report delivery such a response omits the key factors, and its `delivery` block carries a `subject_warning`:

```json theme={null}
"delivery": {
  "mode": "consumer",
  "notice": "Consumer-report delivery under the Cred Protocol consumer-use certification.",
  "subject_warning": "This address is not an individual's wallet (multisig / token / contract). It cannot be the subject of a consumer report; this response is commercial analytics."
}
```

`eoa`, `smart_wallet` and `unknown` are delivered normally. In commercial delivery `subject_type` is informational and no warning is added.

## What this means for the use-case guides

The [use-case guides](https://docs.credprotocol.com/use-cases/qualifying-access.md) show how to turn a score into product rules — collateral tiers, pool access, personalised experiences. Applied to protocols, treasuries, agents and other non-individual subjects, those patterns are commercial delivery. Applied to decide whether an individual gets credit, they need consumer-report delivery and a certified key.

## Disputes

The owner of an address can dispute their own file. Sign in with the address's wallet on [score.credprotocol.com](https://score.credprotocol.com) or in the Cred MetaMask Snap (or call `POST /wallet/disputes` with the wallet token from `POST /wallet/verify`) and describe what is wrong: an event that is inaccurate, a wallet that is not yours, the wrong kind of subject, or anything else, with the transaction hash if you have one and an email address for the outcome.

* Every dispute is reinvestigated within **30 days**; the confirmation email gives the due date.
* While a dispute is open, the address's score and report carry `under_dispute: true`, so anyone reading them knows the file is being reviewed.
* If an event turns out to be wrong, it is removed from scoring and the score is recomputed at once. The report shows how many events were removed in `credit_events.excluded_by_dispute`.
* The outcome (corrected, reviewed without change, or rejected) is emailed with an explanation. `GET /wallet/disputes` lists your disputes and their status.

Only the wallet itself can file a dispute about its address; API keys and payment rails cannot. At most three disputes can be open per address.


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