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

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 /metadata/{token_id}
Returns NFT metadata for a MachineNFT token. The server looks up the machine ID from the token ID via the MachineNFT contract, then resolves the machine owner address and builds the same response as GET /machine/. This endpoint is designed to serve as an ERC-721 tokenURI target.

​
Path parameters

​
token_id
integer
default:"1"
required
NFT token ID (not the machine ID)

​
Response

200 OK The response shape is identical to GET /machine/. All base fields and data visibility-dependent fields apply. See that page for the full field reference.
FieldTypeDescription
schema_versionstringAlways "1.0"
namestring"Machine #<token_id>" when the token round-trips, or "Machine (no NFT)" if the on-chain NFT lookup returns 0
peaqos.machine_idintegerOn-chain machine ID resolved from the token
peaqos.didstringMachine DID derived from the owner address (did:peaq:<owner_address>)
peaqos.operatorstring or nullOperator DID from the DID document
peaqos.mcrstringLetter rating: AAA, AA, A, BBB, BB, B, NR, or Provisioned
peaqos.mcr_scoreintegerMCR score 0-100
peaqos.bond_statusstring"bonded" or "unbonded"
peaqos.negative_flagbooleantrue 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_countintegerTotal on-chain event count
peaqos.data_visibilitystring"private", "onchain", or "public"
peaqos.documentation_urlstring or nullPublic documentation URL from the DID document
Additional fields (data_api, event_data, partner_data, partner_data_error) depend on data_visibility. See GET /machine/ for details.

​
Error responses

StatusdetailCondition
404"Token not found"Token ID does not map to any machine in the MachineNFT contract
404"Machine not registered"The token’s machine ID is not present in the IdentityRegistry contract
422(FastAPI validation error)token_id is less than 1 or not an integer
503"Service not initialised"Server started without contract addresses
503"Chain unavailable"Any chain or DID call failed

​
Example

curl "${PEAQOS_MCR_API_URL}/metadata/7"
Response 
{
  "schema_version": "1.0",
  "name": "Machine #7",
  "peaqos": {
    "machine_id": 42,
    "did": "did:peaq:0xabc1230000000000000000000000000000000001",
    "operator": "did:peaq:0xoperator0000000000000000000000000000001",
    "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": 1500,
        "timestamp": 1711900000,
        "trust_level": 1,
        "metadata": {},
        "origin_currency": "USD",
        "origin_subunit": 100,
        "usd_value": 1500,
        "usd_subunit": 100,
        "amount_status": "ok"
      }
    ]
  }
}
  • GET /machine/ returns the same response shape, resolved by DID instead of token ID.
  • GET /mcr/ returns a focused MCR response with revenue trend and summary.
  • GET /machines/ returns the peaqOS Machine Card resolved by numeric machine ID.