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.
peaqID is a W3C DID that identifies a machine across every chain it transacts on.
Every peaqID follows the format:
The address is the machine’s EOA (externally owned account) on peaq chain. The DID resolves to a flat key-value attribute store on the peaq DID precompile (0x0000000000000000000000000000000000000800). Any consumer can start from the DID and traverse to the machine’s identity, financial history, and credit rating.
Per-machine vs per-proxy
peaqOS assigns one DID per machine and one DID per proxy operator. The two serve different roles:
| DID type | Registered by | Attributes | Purpose |
|---|
| Machine DID | registerMachine (self-managed) or registerFor (proxy delegation) | machineId, nftTokenId, operator, documentation_url, data_api, data_visibility | Identifies a single machine, links to its Machine NFT and event history |
| Proxy DID | registerMachine. The proxy itself is a registered machine. | machineId, machines | Identifies an operator, lists the machine IDs of all machines it manages |
operator attribute. A proxy operator’s machines attribute is a JSON array of machine IDs (e.g., [123, 456, 789]).
DID writes always go to the caller’s DID. The DID precompile keys attributes by msg.sender. A proxy that calls registerFor mints the machine’s identity NFT and pays the bond, but it cannot write attributes to the machine’s DID; the machine must sign its own writeMachineDIDAttributes call. Skipping this leaves the machine unreachable through the MCR API.
DID attribute table
After registration, the operator or machine must explicitly call writeMachineDIDAttributes (or writeProxyDIDAttributes) to write these attributes to the DID. Registration itself only mints the identity and creates the on-chain machine ID; the DID attribute writes are a separate transaction.
| Attribute | Type | Description |
|---|
machineId | uint256 | On-chain machine ID assigned by IdentityRegistry. Primary key for all queries. |
nftTokenId | uint256 | Token ID of the machine’s Machine NFT. This is a separate ERC-721 token space and is not equal to machineId. |
operator | did:peaq:0x... | Proxy operator’s DID. Absent if the machine self-manages. |
documentation_url | URL string | Link to machine documentation maintained by the project. |
data_api | URL string | Raw data API endpoint. The MCR API reads this when data_visibility is public. |
data_visibility | public / private / onchain | Controls how the MCR API exposes raw event data. Unset or empty defaults to private. |
machines | JSON array string | Proxy operator DID only. List of managed machine IDs. The DID precompile stores the full JSON; the MCR API truncates to the first 100 valid IDs when reading the machines attribute. |
Byte limits
Both SDKs enforce these constraints before any DID write reaches the chain:
| Constant | Value | Applies to |
|---|
DID_MAX_NAME_BYTES | 64 | Attribute name |
DID_MAX_VALUE_BYTES | 2560 | Attribute value |
Migration. peaq chain has approximately 3.5 million existing peaqID holders. Existing holders retain their peaqIDs. A migration path to the current DID format is on the roadmap; the new format is what onboards from peaqOS today. Resolving a peaqID
import "dotenv/config";
import { PeaqosClient } from "@peaqos/peaq-os-sdk";
const client = PeaqosClient.fromEnv();
// Fetch machine profile by DID
const response = await fetch(
`${client.apiUrl}/machine/did:peaq:0xMachineAddress`
);
const machine = await response.json();
console.log(machine.peaqos.did); // "did:peaq:0x..."
console.log(machine.peaqos.machine_id); // 123
console.log(machine.peaqos.mcr); // "BBB"
Data visibility modes
The data_visibility attribute controls how the MCR API handles raw event data for this machine:
| Mode | MCR API behavior | Raw data location |
|---|
public | Fetches from data_api, includes in response | Project’s API |
private | Returns the data_api URL only; consumer fetches directly | Project’s API |
onchain | Parses JSON metadata from EventRegistry events into event_data[], capped at the first 100 events per response | Onchain (higher gas cost) |
private is the default when data_visibility is unset or empty.
Cross-links
- Activate function registers machines and writes DID attributes
- GET /machine/ returns the full machine profile, including DID-sourced metadata
- Machine NFT is linked to the peaqID via the
nftTokenId attribute
