Skip to main content
GET
/
mcr
/
{did}
GET /mcr/{did}
curl --request GET \
  --url https://mcr.peaq.xyz/mcr/{did}

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.

​
Endpoint

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

​
did
string
required
Machine DID (did:peaq:0x...) or raw EVM address (0x...).

​
Response

200 OK
FieldTypeDescription
didstringThe DID as supplied in the request path
machine_idintegerOn-chain machine ID resolved from the DID
mcr_scoreintegerMCR score 0-100. 0 when the rating is Provisioned (not enough history to score) or NR (unbonded).
mcrstringLetter rating: AAA, AA, A, BBB, BB, B, NR, or Provisioned
mcr_degradedbooleantrue 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_statusstring"bonded" or "unbonded"
negative_flagbooleantrue 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_countintegerTotal events stored on-chain for this machine
revenue_event_countintegerNumber of revenue events (event_type 0) over the machine’s full event history.
activity_event_countintegerNumber of activity events (event_type 1) over the machine’s full event history.
revenue_trendstring"up", "stable", "down", or "insufficient" (returned when there isn’t enough revenue history to compute a trend).
total_revenueintegerSum 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_eventnumberMean 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_updatedinteger or nullUnix 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

StatusdetailCondition
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

curl "${PEAQOS_MCR_API_URL}/mcr/did:peaq:0xabc1230000000000000000000000000000000001"
Response 
{
  "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
}
  • GET /machine/ returns the full machine profile including data visibility-dependent fields.
  • GET /operator//machines returns MCR scores for all machines under an operator.
  • GET /metadata/ returns the same profile shape as /machine/{did}, resolved by NFT token ID.