> ## 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 /machine/{did}
> Return the full machine profile for a DID, with response fields that vary by data visibility setting.
## Endpoint
```http theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
GET /machine/{did}
```
Returns the full machine profile for a DID. The response includes identity, MCR score, bond status, and data visibility-dependent fields. This endpoint shares its response builder with [GET /metadata/{token_id}](/peaqos/api-reference/get-metadata); both return the same shape.
## Path parameters
Machine DID (`did:peaq:0x...`) or raw EVM address (`0x...`)
## Response
**200 OK -- base fields (always present)**
| Field | Type | Description |
| :------------------------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema_version` | string | Always `"1.0"` |
| `name` | string | `"Machine #"` if an NFT token exists, otherwise `"Machine (no NFT)"` |
| `peaqos.machine_id` | integer | On-chain machine ID |
| `peaqos.did` | string | Machine DID |
| `peaqos.operator` | string or null | Operator DID from the DID document. `null` if not set. |
| `peaqos.mcr` | string | Letter rating: `AAA`, `AA`, `A`, `BBB`, `BB`, `B`, `NR`, or `Provisioned` |
| `peaqos.mcr_score` | integer | MCR score 0-100 |
| `peaqos.bond_status` | string | `"bonded"` or `"unbonded"` |
| `peaqos.negative_flag` | boolean | `true` when the AdminFlags contract has a negative-flag timestamp set for this machine. Stays `true` for as long as the timestamp is recorded on-chain, regardless of whether the 180-day MCR scoring penalty is still in effect. |
| `peaqos.event_count` | integer | Total on-chain event count |
| `peaqos.data_visibility` | string | `"private"`, `"onchain"`, or `"public"`. Defaults to `"private"` if the DID document has no `data_visibility` attribute or contains an unrecognised value. |
| `peaqos.documentation_url` | string or null | Public documentation URL from the DID document |
### Additional fields by data visibility
The `data_visibility` value on the machine's DID document determines which additional fields appear in the `peaqos` object.
#### `data_visibility == "private"`
| Field | Type | Description |
| :---------------- | :----- | :-------------------------------------------------------------------------------------------------------- |
| `peaqos.data_api` | string | The machine's data API URL from the DID document. Only present when a `data_api` attribute is configured. |
#### `data_visibility == "onchain"`
| Field | Type | Description |
| :------------------ | :---- | :--------------------------------------------------------------------------------------------------------- |
| `peaqos.event_data` | array | Up to the first 100 events for this machine (oldest first by on-chain index), parsed from on-chain storage |
Each element in `event_data`:
| Field | Type | Description |
| :---------------- | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_type` | integer | `0` = revenue, `1` = activity |
| `origin_value` | integer | Non-negative ISO 4217 minor-unit integer (e.g. cents for USD/HKD, whole units for JPY/KRW). Revenue: raw partner-submitted amount in `origin_currency`. Activity: arbitrary non-negative integer. |
| `timestamp` | integer | Unix timestamp |
| `trust_level` | integer | `0` = self-reported, `1` = on-chain verifiable, `2` = hardware-signed |
| `metadata` | object | Parsed JSON metadata from the event. Falls back to `{"raw": "..."}` if the stored metadata is not valid JSON. |
| `origin_currency` | string | **Revenue only.** ISO 4217 currency code in upper-case. The API normalises against the 25-fiat supported list: USD, HKD, JPY, CNY, KRW, SGD, TWD, THB, PHP, MYR, IDR, VND, INR, EUR, GBP, CHF, SEK, NOK, DKK, PLN, CAD, AUD, NZD, MXN, BRL. Codes outside this set are echoed back as-is with `amount_status: "unsupported_currency"`. When the partner omits the currency on-chain, the server defaults to `"USD"`. Activity events omit this field. |
| `origin_subunit` | integer or null | **Revenue only.** Divisor that converts `origin_value` to a display amount: `100` for two-decimal currencies (USD, HKD, EUR, etc.) and `1` for the zero-decimal codes JPY, KRW, and VND. `null` when `origin_currency` is outside the supported whitelist (`amount_status: "unsupported_currency"`). |
| `usd_value` | integer or null | **Revenue only.** FX-normalized value in **USD cents**. Display = `usd_value / 100`. `null` when `amount_status != "ok"` (FX failed); consumers must branch on `amount_status` before displaying. |
| `usd_subunit` | integer | **Revenue only.** Always `100`. USD's minor unit divisor; the field exists to make the cents convention explicit on the wire. |
| `amount_status` | string | **Revenue only.** `"ok"` (FX succeeded; `usd_value` is meaningful), `"unsupported_currency"` (currency not in MCR FX whitelist), or `"fx_unavailable"` (FX feed degraded or stale). Non-`"ok"` rows score conservatively and surface `mcr_degraded: true` on [`/mcr/{did}`](/peaqos/api-reference/get-mcr). |
#### `data_visibility == "public"`
The server fetches live data from the machine's `data_api` URL with a 5-second timeout. The URL is validated before the request is made: private IP ranges, loopback addresses, link-local addresses, reserved ranges, multicast addresses, and known cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`) are blocked. Redirects are not followed. Responses must be valid JSON objects no larger than 1 MB.
On success:
| Field | Type | Description |
| :-------------------- | :----- | :------------------------------------------------------- |
| `peaqos.partner_data` | object | The JSON object returned by the machine's `data_api` URL |
On failure:
| Field | Type | Description |
| :-------------------------- | :----- | :----------------------------- |
| `peaqos.partner_data_error` | string | One of the fixed strings below |
Possible `partner_data_error` values:
| Value | Cause |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"data_api not configured"` | DID has no `data_api` attribute |
| `"blocked: unsafe URL"` | URL scheme is not http/https, hostname is missing, host is in the blocked list, or DNS resolves to a private/loopback/link-local/reserved/multicast IP |
| `"blocked: malformed URL"` | URL could not be parsed |
| `"fetch failed"` | Network error, timeout, redirect, or non-2xx HTTP response |
| `"response too large"` | Response exceeded 1 MB |
| `"invalid JSON response"` | Body was not valid JSON, or the parsed value was not a JSON object |
## 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"` | Any chain call failed |
## Example
```bash bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
curl "${PEAQOS_MCR_API_URL}/machine/did:peaq:0xabc1230000000000000000000000000000000001"
```
```javascript JavaScript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
const response = await fetch(
`${PEAQOS_MCR_API_URL}/machine/did:peaq:0xabc1230000000000000000000000000000000001`
);
const data = await response.json();
console.log(data.peaqos.mcr, data.peaqos.data_visibility);
```
```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
import requests
response = requests.get(
f"{PEAQOS_MCR_API_URL}/machine/did:peaq:0xabc1230000000000000000000000000000000001"
)
data = response.json()
print(data["peaqos"]["mcr"], data["peaqos"]["data_visibility"])
```
**Response (private visibility)**
```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
"schema_version": "1.0",
"name": "Machine #7",
"peaqos": {
"machine_id": 1,
"did": "did:peaq:0xabc1230000000000000000000000000000000001",
"operator": "did:peaq:0xoperator0000000000000000000000000000001",
"mcr": "BB",
"mcr_score": 45,
"bond_status": "bonded",
"negative_flag": false,
"event_count": 12,
"data_visibility": "private",
"documentation_url": null,
"data_api": "https://machine.example.com/api/data"
}
}
```
**Response (onchain visibility)**
```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
"schema_version": "1.0",
"name": "Machine #7",
"peaqos": {
"machine_id": 1,
"did": "did:peaq:0xabc1230000000000000000000000000000000001",
"operator": null,
"mcr": "B",
"mcr_score": 30,
"bond_status": "bonded",
"negative_flag": false,
"event_count": 5,
"data_visibility": "onchain",
"documentation_url": null,
"event_data": [
{
"event_type": 0,
"origin_value": 20000,
"timestamp": 1711900000,
"trust_level": 2,
"metadata": { "job_id": "abc" },
"origin_currency": "HKD",
"origin_subunit": 100,
"usd_value": 2564,
"usd_subunit": 100,
"amount_status": "ok"
}
]
}
}
```
**Response (public visibility, fetch failure)**
```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
"schema_version": "1.0",
"name": "Machine (no NFT)",
"peaqos": {
"machine_id": 3,
"did": "did:peaq:0xdef4560000000000000000000000000000000003",
"operator": null,
"mcr": "NR",
"mcr_score": 0,
"bond_status": "unbonded",
"negative_flag": false,
"event_count": 0,
"data_visibility": "public",
"documentation_url": null,
"partner_data_error": "blocked: unsafe URL"
}
}
```
## Related endpoints
* [GET /mcr/{did}](/peaqos/api-reference/get-mcr) returns a focused MCR score response with revenue trend and summary.
* [GET /metadata/{token_id}](/peaqos/api-reference/get-metadata) returns the same response shape, resolved by NFT token ID instead of DID.
* [GET /machines/{machine_id}](/peaqos/api-reference/get-machine-card) returns the peaqOS Machine Card resolved by numeric machine ID.