GET /machine/{did}

Endpoint

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/; both return the same shape.

Path parameters

did

string

required

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 #<token_id>"` 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}`.

`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

curl "${PEAQOS_MCR_API_URL}/machine/did:peaq:0xabc1230000000000000000000000000000000001"

Response (private visibility)

{
  "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)

{
  "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)

{
  "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"
  }
}

GET /mcr/ returns a focused MCR score response with revenue trend and summary.
GET /metadata/ returns the same response shape, resolved by NFT token ID instead of DID.
GET /machines/ returns the peaqOS Machine Card resolved by numeric machine ID.

API Reference

Documentation Index

​Endpoint

​Path parameters

​Response

​Additional fields by data visibility

​data_visibility == "private"

​data_visibility == "onchain"

​data_visibility == "public"

​Error responses

​Example

​Related endpoints