Query Machine Credit Rating

Fetch a machine’s MCR from the peaqOS MCR API. Covers curl, JavaScript, and Python.

The MCR API returns a machine’s credit rating along with event counts, revenue trend, and bond status. It’s a public read API. No authentication required.

Endpoint

GET https://mcr.peaq.xyz/mcr/{did}

https://mcr.peaq.xyz is the public peaq-hosted MCR. It serves machines activated under Economics 2.0, homed on peaq or on Solana. {did} is the machine’s DID in the form did:peaq:<decimal machine id>. An address DID (did:peaq:0x...), a raw EVM address, or a bare machine ID returns 400 Invalid machine DID format. There is no public MCR API for Tokenomics 1.0 machines.

The SDK query helpers read the same server on a tokenomics20 client (SDK 0.8.0). See API reference. For a machine homed on Solana the response adds home_chain (5 for Solana) and, until the machine can be rated, a rating_unavailable reason.

Fetch the MCR

curl

curl -s "https://mcr.peaq.xyz/mcr/did:peaq:<decimal machine id>"

Response shape

{
  "did": "did:peaq:<decimal machine id>",
  "machine_id": "<decimal machine id>",
  "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
}

machine_id is a JSON string, because a 2.0 machine ID exceeds what a JavaScript number holds exactly. total_revenue and average_revenue_per_event are USD cents. Divide by 100 for display ($350 and$50 in this example). revenue_trend and average_revenue_per_event can be null, for example for a Solana-homed machine that is not rated yet, and the SDK query helpers type both as nullable; null / None means not computable.

A newly registered machine that hasn’t accumulated enough history returns mcr: "Provisioned" with mcr_score: 0. Unbonded machines return mcr: "NR" with mcr_score: 0. See GET /mcr/{did} for the full field reference.

Query an operator’s fleet

Use the operator endpoint to list all machines registered under a proxy operator, paginated with MCR scores per machine. The operator DID stays did:peaq:0x<address>, because it names an account, not a machine. Each entry carries its machine as did:peaq:<decimal machine id> with machine_id as a string.

curl

curl -s "https://mcr.peaq.xyz/operator/did:peaq:0xProxyAddress/machines?offset=0&limit=20"

See GET /operator/{did}/machines for the full response shape and pagination details.

Caching

The server applies a 1-hour TTL on MCR responses by default, configurable via the MCR_CACHE_TTL env var (0 to disable). Repeat requests within the window return cached values, except for responses with mcr_degraded: true and responses for a Solana-homed machine, which are never cached. The last_updated field is the timestamp of the machine’s most recent event (when it happened, not when it was submitted or indexed).

Error handling

The MCR API returns standard HTTP status codes: 400 for malformed inputs, 404 when the DID is unregistered, 409 when the machine is homed on a chain this server cannot read, 429 (rate_limited) when the server’s lookup budget for other chains is spent, and 503 when a chain is unavailable or the machine is relocating. Bodies are JSON with a detail field: a string, or for 409 an object with code, home_protocol_chain_id and message.

If you call through the SDK (queryMcr(client, did) in JS / query_mcr(client, did) in Python), HTTP failures surface as RuntimeError (JS) or ApiError (Python). The code attribute carries NOT_FOUND, SERVICE_UNAVAILABLE, SERVER_ERROR, TIMEOUT, etc. On a tokenomics20 client a machine homed on another chain normally still answers, with home_chain set and a rating_unavailable reason until its events are indexed. HTTP 409 with the code MACHINE_HOMED_ELSEWHERE (McrApiError in JS) comes back only when the server cannot read the machine’s home chain. See SDK errors reference for the full code map.

Next steps

• GET /mcr/{did}: full API reference for this endpoint
• GET /machine/{did}: full machine profile
• Machine Credit Rating concept: rating scale and lifecycle