API reference overview

peaqOS exposes two HTTP/JSON APIs:

MCR API: reads, plus one signed write. , machine profiles, operator fleet data, metadata, and Machine Cards, all backed by contracts on peaq, plus the monetization opt-in toggle. Documented below.
Machine Markets API: powers Scale. Machine identity proofs, machine records, , the skill registry, the service catalogue, and machine-aware market search. See the Machine Markets API overview.

This page covers the MCR API. Writes against peaqOS state (, event submission, ) happen via the peaqOS SDK and . The one exception is the monetization toggle, which is a signature-verified write on this API.

Quick start

Pick the setup that matches your workflow: an AI-driven flow via the peaqOS skill, or direct HTTP calls.

Agent skill
cURL
ROS 2

pip install peaq-os-cli
npx skills add peaqnetwork/peaq-os-skills

Auto-detects Claude Code, Cursor, or Windsurf. Then invoke /peaqos in Claude Code and ask for an MCR score, machine profile, or operator fleet — the skill picks the right CLI command and the CLI hits this API for you. To target a specific runtime, add --agent claude-code | cursor | windsurf — see the peaqOS AI page.

curl https://mcr.peaq.xyz/mcr/did:peaq:0xabc123...

Endpoint index below. No API key required: MCR data is public.

ros2 service call /peaqos_node/mcr/query \
  peaq_ros2_interfaces/srv/PeaqosQueryMcr \
  "{did: 'did:peaq:<MACHINE_EVM_ADDRESS>'}"

peaq_ros2_peaqos exposes the MCR API as ROS 2 services. Full reference on SDK: ROS 2; MCR-specific services are listed under Services → MCR queries.

Base URL

Set the environment variable PEAQOS_MCR_API_URL to the root of the MCR API server:

export PEAQOS_MCR_API_URL=https://mcr.peaq.xyz

For local development against a self-hosted server, use http://127.0.0.1:8000. All endpoint paths in this reference are relative to that base URL.

Authentication

There are no API keys or tokens anywhere on this API. Every read is public: MCR scores, machine profiles, and metadata are public on-chain data. The single write, PUT /machine/{key}/monetization, authorizes the caller by verifying an signature carried in the request body. Still no key or token: the signature is the credential.

Rate limits

The API enforces a limit of 90 requests per minute per IP address. Requests that exceed the limit receive a 429 Too Many Requests response. For production deployments with multiple workers, the rate limiter backend can be swapped to Redis.

Server configuration

When self-hosting the MCR API, these environment variables tune caching, storage, the monetization write path, and test-mode behavior. Typical deployments need the contract addresses, RPC, and a persistent directory for the monetization state; the rest have workable defaults.

Variable	Default	Purpose
`IDENTITY_REGISTRY_ADDRESS`	n/a	Primary contract address. When empty, the server boots in test mode: `/ready` returns 503 with `rpc_connected: false` and all `contracts.*` (including `admin_flags`) reported as `false`.
`ADMIN_FLAGS_ADDRESS`	n/a	Optional `AdminFlags` contract. Influences MCR responses via `negative_flag` and admin trust overrides. When the service is initialised but this address is unset, `contracts.admin_flags` on `/ready` is `true`: the probe skips the optional check and the service stays ready.
`MCR_CACHE_TTL`	`3600`	MCR response cache TTL in seconds. Set to `0` to disable caching entirely.
`EVENT_STORE_DB_PATH`	`/tmp/peaqos_events.db`	SQLite path for the delta-sync event cache. Must resolve under `/tmp`, `/data`, or `/var/lib/peaqos`.
`MONETIZATION_DB_PATH`	`/var/lib/peaqos/monetization.db`	SQLite path for monetization opt-in state. Unlike the rebuildable event cache, this is the single source of truth, so it must live on a persistent volume (allowed prefixes: `/data`, `/var/lib/peaqos`, and `/var/tmp` for local dev). The parent directory must already exist and be writable; the server does not create it and fails startup with guidance when it is missing.
`CHAIN_ID`	`0`	EVM chain ID bound into the monetization signed message. `0` means adopt the live chain ID from the RPC at startup; a non-zero value that disagrees with the node fails startup loudly.
`MONETIZATION_SIG_MAX_AGE`	`300`	Seconds a monetization signature stays valid in the past direction.
`MONETIZATION_SIG_MAX_SKEW`	`30`	Seconds of future clock skew tolerated on a monetization signature.
`SKIP_PROVISIONED_GATE`	`false`	Dev/demo toggle that short-circuits the “must be bonded” gate on scoring. Never enable in production.

Error envelope

Most error responses use the same JSON shape:

{
  "detail": "<human-readable message>"
}

The detail string describes the cause. Common values:

`detail` value	Meaning
`"Service not initialised"`	Server started without contract addresses (test mode)
`"Chain unavailable"`	RPC call to the node or a contract failed
`"Empty DID"`	DID path parameter is empty
`"Invalid Ethereum address format"`	DID or address does not match `^0x[a-fA-F0-9]{40}$`
`"Machine DID not found"`	DID address has no `machineId` attribute in the DID registry
`"Machine not registered"`	Machine ID is not present in the IdentityRegistry contract
`"Machine not found"`	Machine ID does not exist (machines endpoint)
`"Machine wallet not found"`	Machine wallet is the zero address
`"Token not found"`	NFT token ID does not map to any machine in MachineNFT
`"Internal server error"`	Unhandled exception (logged server-side)

Coded envelope on the monetization endpoints

The two monetization endpoints (GET, PUT) nest a stable machine-readable code instead of a bare string:

{
  "detail": {
    "code": "MACHINE_NOT_FOUND",
    "message": "machine not found"
  }
}

Branch on code, never on message. One case returns neither shape: a body that is not valid JSON gets a 422 whose detail is a list of validation objects with no code at all.

Status codes

Code	Meaning
`200 OK`	Request succeeded; JSON body returned
`400 Bad Request`	DID is empty or the address does not match `^0x[a-fA-F0-9]{40}$`; on the monetization endpoints, a malformed body or key (`INVALID_REQUEST`) or a timestamp outside the freshness window (`TIMESTAMP_OUT_OF_WINDOW`)
`401 Unauthorized`	Monetization PUT only: the signature bytes cannot be recovered to any address (`INVALID_SIGNATURE`)
`403 Forbidden`	Monetization PUT only: the recovered signer is not the machine’s owner, machine wallet, or on-chain operator (`UNAUTHORIZED_SIGNER`)
`404 Not Found`	The requested DID, machine ID, or token ID does not exist on-chain
`409 Conflict`	Monetization PUT only: machine not bonded or deactivated (opt-in gates), or a newer signature was already applied (`STALE_SIGNATURE`)
`422 Unprocessable Entity`	Path, query, or request-body validation failed (FastAPI auto-generated)
`429 Too Many Requests`	Rate limit exceeded. Responses include slowapi headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`)
`500 Internal Server Error`	Unhandled server exception
`503 Service Unavailable`	Service not initialised or chain/RPC call failed

DID format

Endpoints that accept a DID path parameter support two formats:

Full DID: did:peaq:0xabc123...
Raw address: 0xabc123...

The server strips the did:peaq: prefix internally before querying the chain. The monetization endpoints are the exception. Their key parameter takes a full DID or a decimal machine id, and rejects a raw address with INVALID_REQUEST.

MCR API endpoints

GET /mcr/{did}

Machine Credit Rating score, rating, bond status, event counts, and revenue trend for a single machine.

GET /machine/{did}

Full machine profile with data visibility-dependent fields (private, onchain, or public).

GET /operator/{did}/machines

Paginated list of machines registered under an operator, with per-machine MCR scores.

GET /metadata/{token_id}

NFT metadata for a MachineNFT token. Same response shape as /machine/.

GET /machines/{machine_id}

peaqOS Machine Card for a machine, including services, registrations, and operator info.

GET /health and /ready

Liveness and readiness probes for health checks and monitoring.

GET /machine/{key}/monetization

Current monetization opt-in state for a machine: status, signer, and last update.

PUT /machine/{key}/monetization

Signed opt-in or opt-out toggle. The only signature-verified write on this API.

Machine Markets API

Separate surface, separate host (orchestrator deployment). Pairing, delegation policy, skill registry, service catalogue, and market search.

Machine Markets API overview

Base path, access model, error codes, common types, and the full Machine Markets endpoint surface.

​Quick start

​Base URL

​Authentication

​Rate limits

​Server configuration

​Error envelope

​Coded envelope on the monetization endpoints

​Status codes

​DID format

​MCR API endpoints