GET /mcr/{did}

GET

mcr

{did}

GET /mcr/{did}

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mcr.peaq.xyz/mcr/{did}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://mcr.peaq.xyz/mcr/{did}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://mcr.peaq.xyz/mcr/{did}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

Endpoint

GET /mcr/{did}

Returns the score, letter rating, , , revenue summary, and trend for a single machine. For a peaq-homed machine the server fetches new events from chain in batches of 100 and caches them in SQLite, so repeat requests read the cache. Responses are cached in memory for 3600 seconds. 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. Responses for a Solana-homed machine are not cached either.

Path parameters

string

required

Machine DID in the form did:peaq:<decimal machine id>, with no leading zeros. Address DIDs (did:peaq:0x...), raw addresses and bare machine IDs return 400.

Response

200 OK

Field	Type	Description
`did`	string	The DID as supplied in the request path
`machine_id`	string	Machine ID as a decimal string (a 256-bit value; parse with `BigInt` in JavaScript)
`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 machine’s event history carries `fx_source` `stale_latest` or `default_usd_fx_outage` (stale snapshot or FX outage with the USD default). Rows with `fx_unavailable` or `unsupported_currency` do not set it and the response is cached like a healthy one. Distinguishes a conservative score caused by infrastructure degradation from a machine with no revenue history. Always `false` for a Solana-homed machine.
`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 recorded 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 or null	`"up"`, `"stable"`, `"down"`, or `"insufficient"` (returned when there isn’t enough revenue history to compute a trend). `null` for a Solana-homed machine that is not rated yet.
`total_revenue`	integer	Sum of qualifying revenue-event values, in USD cents. Only events of at least 1,000 USD cents are summed. The score applies the same 1,000-cent threshold to each day’s total, so the two counts can differ.
`average_revenue_per_event`	number or null	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. `null` for a Solana-homed machine that is not rated yet.
`last_updated`	integer or null	Unix timestamp of the most recent event. `null` if no events exist, and for a Solana-homed machine that is not rated yet.
`home_chain`	integer	Solana-homed machines only. Protocol chain ordinal of the machine’s home chain: `5` for Solana. Absent for a peaq-homed machine.
`rating_unavailable`	string	Solana-homed machines only, while not rated. Why the server cannot rate the machine yet. Absent once the machine is rated.

Rating values

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. A Solana-homed machine is rated from its indexed event history. Until that history is complete, the response carries mcr_score: 0, mcr: "Provisioned", and a rating_unavailable reason. With any reason present, event_count, revenue_event_count, activity_event_count and total_revenue are 0, average_revenue_per_event, revenue_trend and last_updated are null, and mcr_degraded is false, even when the index already holds events for the machine:

`rating_unavailable`	Meaning
`event_history_not_indexed`	The server runs no Solana event indexer. With an indexer and no events for the machine, the value is `no_events_yet`.
`no_events_yet`	The index is healthy and holds no events for this machine
`event_history_gap`	The index is missing events, so the server refuses to rate
`event_history_unverified`	Events are indexed but their completeness has not been checked against the chain yet

Once the history is complete, the server rates the machine with the same formula a peaq-homed machine gets and drops rating_unavailable. Branch on the field’s presence rather than on one value. The SDKs parse these fields from 0.8.0. See Machines and IDs.

Error responses

Status	`detail`	Condition
400	`"Empty DID"`	Path parameter is empty
400	`"Invalid machine DID format"`	Path is not `did:peaq:<decimal machine id>`: an address DID, a raw address, a bare ID, a non-decimal value, a leading zero, or a value above `2^256-1`
404	`"Machine not registered"`	No chain records a machine with this ID
409	`{"code": "MACHINE_HOMED_ELSEWHERE", "home_protocol_chain_id", "message"}`	The machine is homed on a chain this server cannot read
429	`"rate_limited"`	The server’s budget for home-chain lookups is spent; slow down and retry
503	`"Machine is relocating to another chain; retry later"`	The machine is moving between chains
503	`"machine home chain is unreachable; retry later"`	Reading a Solana-homed machine’s record failed
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:-https://mcr.peaq.xyz}/mcr/did:peaq:108934426058480933785963234320575706003575332367737915173645220784539698794848"

const PEAQOS_MCR_API_URL = process.env.PEAQOS_MCR_API_URL ?? "https://mcr.peaq.xyz";
const response = await fetch(
  `${PEAQOS_MCR_API_URL}/mcr/did:peaq:108934426058480933785963234320575706003575332367737915173645220784539698794848`
);
const data = await response.json();
console.log(data.mcr_score, data.mcr, BigInt(data.machine_id));

import os

import requests

PEAQOS_MCR_API_URL = os.environ.get("PEAQOS_MCR_API_URL", "https://mcr.peaq.xyz")

response = requests.get(
    f"{PEAQOS_MCR_API_URL}/mcr/did:peaq:108934426058480933785963234320575706003575332367737915173645220784539698794848"
)
data = response.json()
print(data["mcr_score"], data["mcr"], int(data["machine_id"]))

Response (peaq-homed machine)

{
  "did": "did:peaq:108934426058480933785963234320575706003575332367737915173645220784539698794848",
  "machine_id": "108934426058480933785963234320575706003575332367737915173645220784539698794848",
  "mcr_score": 0,
  "mcr": "Provisioned",
  "mcr_degraded": false,
  "bond_status": "bonded",
  "negative_flag": false,
  "event_count": 0,
  "revenue_event_count": 0,
  "activity_event_count": 0,
  "revenue_trend": "insufficient",
  "total_revenue": 0,
  "average_revenue_per_event": 0,
  "last_updated": null
}

Response (Solana-homed machine, not rated yet)

{
  "did": "did:peaq:59553499179785547240541790107334615076028120679642018345696955698709980164819",
  "machine_id": "59553499179785547240541790107334615076028120679642018345696955698709980164819",
  "mcr_degraded": false,
  "event_count": 0,
  "revenue_event_count": 0,
  "activity_event_count": 0,
  "total_revenue": 0,
  "average_revenue_per_event": null,
  "revenue_trend": null,
  "last_updated": null,
  "home_chain": 5,
  "bond_status": "bonded",
  "negative_flag": false,
  "mcr": "Provisioned",
  "mcr_score": 0,
  "rating_unavailable": "no_events_yet"
}

GET /machine/{did} returns the full machine profile.
GET /operator/{did}/machines returns MCR scores for all machines under an operator.
GET /metadata/{token_id} returns the same profile shape as /machine/{did}, resolved by NFT token ID.

⌘I

GET /mcr/{did}

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mcr.peaq.xyz/mcr/{did}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://mcr.peaq.xyz/mcr/{did}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://mcr.peaq.xyz/mcr/{did}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

​Endpoint

​Path parameters

​Response

​Rating values

​Error responses

​Example

​Related endpoints

Endpoint

Path parameters

Response

Rating values

Error responses

Example

Related endpoints