> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# GET /mcr/{did}
> Compute and return the Machine Credit Rating for a single machine DID.
## Endpoint
```http theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
GET /mcr/{did}
```
Returns the Machine Credit Rating (MCR) score, letter rating, bond status, event counts, revenue summary, and trend for a single machine. The server paginates the full event history in batches of 100 to compute the score. Results are cached in memory with a TTL configurable via the `MCR_CACHE_TTL` env var (defaults to 3600 seconds; set `MCR_CACHE_TTL=0` to disable caching). Responses are not cached when `mcr_degraded` is `true`: the server retries upstream FX sources on the next request rather than pinning a conservative score.
## Path parameters
Machine DID (`did:peaq:0x...`) or raw EVM address (`0x...`).
## Response
**200 OK**
| Field | Type | Description |
| :-------------------------- | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `did` | string | The DID as supplied in the request path |
| `machine_id` | integer | On-chain machine ID resolved from the DID |
| `mcr_score` | integer | MCR score 0-100. `0` when the rating is `Provisioned` (not enough history to score) or `NR` (unbonded). |
| `mcr` | string | Letter rating: `AAA`, `AA`, `A`, `BBB`, `BB`, `B`, `NR`, or `Provisioned` |
| `mcr_degraded` | boolean | `true` if any event in the score window came from a degraded FX path (stale snapshot or upstream FX outage). Distinguishes a conservative score caused by infra degradation from a machine with no revenue history. Degraded responses bypass the cache so the next request retries fresh FX. |
| `bond_status` | string | `"bonded"` or `"unbonded"` |
| `negative_flag` | boolean | `true` when the AdminFlags contract has a negative-flag timestamp set for this machine (and the value is in the plausible range 2020-01-01 ≤ ts ≤ now+1 day). The MCR scoring penalty only applies while the flag is within its active window, but this field stays `true` for as long as the timestamp is recorded on-chain. |
| `event_count` | integer | Total events stored on-chain for this machine |
| `revenue_event_count` | integer | Number of revenue events (event\_type 0) over the machine's full event history. |
| `activity_event_count` | integer | Number of activity events (event\_type 1) over the machine's full event history. |
| `revenue_trend` | string | `"up"`, `"stable"`, `"down"`, or `"insufficient"` (returned when there isn't enough revenue history to compute a trend). |
| `total_revenue` | integer | Sum of qualifying revenue-event values, in **USD cents**. Only events meeting the per-event qualifying threshold are summed; daily aggregation for the MCR score uses a separate qualifying threshold. |
| `average_revenue_per_event` | number | Mean value per qualifying revenue event, in **USD cents**, rounded to 2 decimals. Divides only by events that meet the per-event qualifying threshold, so the divisor can be smaller than `revenue_event_count`. `0` if no qualifying events. |
| `last_updated` | integer or null | Unix timestamp of the most recent event. `null` if no events exist. |
### Rating values
Possible values of `mcr`: `AAA`, `AA`, `A`, `BBB`, `BB`, `B`, `NR`, or `Provisioned`.
Unbonded machines return a rating of `NR` with `mcr_score: 0`. Bonded machines that have not yet accumulated enough history return a rating of `Provisioned` with `mcr_score: 0`.
## Error responses
| Status | `detail` | Condition |
| :----- | :---------------------------------- | :----------------------------------------------------------- |
| 400 | `"Empty DID"` | Path parameter resolves to an empty string |
| 400 | `"Invalid Ethereum address format"` | DID or address does not match the expected hex format |
| 404 | `"Machine DID not found"` | DID address has no `machineId` attribute in the DID registry |
| 404 | `"Machine not registered"` | Machine ID is not present in the IdentityRegistry contract |
| 503 | `"Service not initialised"` | Server started without contract addresses |
| 503 | `"Chain unavailable"` | RPC call failed during any chain read |
## Example
```bash bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
curl "${PEAQOS_MCR_API_URL}/mcr/did:peaq:0xabc1230000000000000000000000000000000001"
```
```javascript JavaScript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
const response = await fetch(
`${PEAQOS_MCR_API_URL}/mcr/did:peaq:0xabc1230000000000000000000000000000000001`
);
const data = await response.json();
console.log(data.mcr_score, data.mcr);
```
```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
import requests
response = requests.get(
f"{PEAQOS_MCR_API_URL}/mcr/did:peaq:0xabc1230000000000000000000000000000000001"
)
data = response.json()
print(data["mcr_score"], data["mcr"])
```
**Response**
```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
"did": "did:peaq:0xabc1230000000000000000000000000000000001",
"machine_id": 1,
"mcr_score": 45,
"mcr": "BB",
"mcr_degraded": false,
"bond_status": "bonded",
"negative_flag": false,
"event_count": 12,
"revenue_event_count": 7,
"activity_event_count": 5,
"revenue_trend": "stable",
"total_revenue": 35000,
"average_revenue_per_event": 5000.0,
"last_updated": 1711900000
}
```
## Related endpoints
* [GET /machine/{did}](/peaqos/api-reference/get-machine) returns the full machine profile including data visibility-dependent fields.
* [GET /operator/{did}/machines](/peaqos/api-reference/get-operator-machines) returns MCR scores for all machines under an operator.
* [GET /metadata/{token_id}](/peaqos/api-reference/get-metadata) returns the same profile shape as `/machine/{did}`, resolved by NFT token ID.