API reference overview

Base URL, authentication, rate limits, error envelope, and endpoint index for the peaqOS MCR API, the Verify API and the Machine Markets API.

peaqOS exposes three HTTP/JSON APIs:

• MCR API: reads, plus one signed write. Machine Credit Ratings, machine profiles, operator fleet data, NFT metadata, and Machine Cards, all backed by on-chain contracts on peaq and, for a Solana-homed machine, its Solana registry program, plus the monetization opt-in toggle. Documented below.
• Verify API: one public read, GET /v1/verify/machines/{machineId}, that returns a machine’s KYB and chip verification status for Verify, and two chip intake routes, POST /v1/verify/chip/challenge and POST /v1/verify/chip/evidence, that take peaq’s onboarding token. Served under /v1/verify/ on the same host as the MCR API, with its own rate limits and error codes.
• Machine Markets API: powers Scale. Machine identity proofs, machine records, Machine Agent pairings, 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 (registration, event submission, bridging) happen via the peaqOS SDK and smart contracts. The one exception is the monetization toggle, which is a signature-verified write on this API.

Machines and IDs

The MCR API is served at https://mcr.peaq.xyz. It serves every machine activated under Economics 2.0, on peaq and on Solana, and addresses machines by their decimal machine ID: GET /mcr/did:peaq:<decimal id>, GET /machines/<decimal id>, GET /machine/<decimal id>/monetization. Operators keep their address DID: GET /operator/did:peaq:0x<address>/machines. Address-form machine DIDs are rejected: see DID format for the answer each route gives.

The SDK query helpers (queryMcr, queryMachine, queryOperatorMachines and their Python equivalents) read it on a tokenomics20 client, and check the compatibility signal at GET /.well-known/peaq-monetization before signing a monetization change. peaqos qualify mcr and peaqos show read it when TOKENOMICS_DEPLOYMENT_ID is set (see peaqOS CLI). Requires SDK 0.8.0 and CLI 0.0.12. Ratings are also on the Machine Explorer.

A machine homed on Solana (Onboard a machine on Solana) uses the same did:peaq:<decimal id> and the same routes. Its Machine Card names the registry as solana:<chain reference>:<program id> (a peaq-homed machine shows eip155:3338:<MachineRegistry address>), and its responses carry home_chain (protocol chain ordinal, 5 for Solana) and rating_unavailable, plus owner (base58), controller, machine_type and relocating on the profile. revenue_trend and average_revenue_per_event are null while rating_unavailable is present, and the routes answer 503 while the machine relocates or its home chain is unreachable. SDK side: SDK JS, SDK Python.

The operator listing is served from an ownership index: MachineRegistry events for peaq-homed machines, kept current by a background worker, and a periodic snapshot for Solana-homed machines. A 200 can be up to 100 blocks behind the chain head the worker last read and says how far in index. Past that, or when either part is out of date, the route answers 503 with a detail naming the cause (for example operator index syncing: block X of Y) and a Retry-After header.

Every machine ID in a response is a JSON string, including the Machine Card’s registrations[].machineId, because a 2.0 machine ID is a 256-bit hash that a JavaScript number rounds. Parse it with BigInt in JavaScript or int in Python. A rounded ID reads a different machine: a monetization write fails with 404 MACHINE_NOT_FOUND, or with 403 UNAUTHORIZED_SIGNER if only the signed message carries the rounded ID.

The SDK query helpers already return bigint / int. Paths accept the decimal string.

Quick start

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

Agent skill

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 calls this API. To target a specific runtime, add --agent claude-code | cursor | windsurf. See the peaqOS AI page.

cURL

curl https://mcr.peaq.xyz/mcr/did:peaq:<decimal machine id>

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

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

The SDK’s tokenomics20 client and the CLI with TOKENOMICS_DEPLOYMENT_ID set take the host from the deployment record and do not read this variable.

All endpoint paths in this reference are relative to that base URL.

Authentication

There are no API keys or tokens on the MCR API. Every read is public: MCR scores, machine profiles, and metadata are public on-chain data. The Verify read is public too; only the two chip intake routes under /v1/verify/chip/ require a Bearer token, which peaq issues to its onboarding service and not to operators.

The single write, PUT /machine/{key}/monetization, authorizes the caller by verifying a signature carried in the request body: EIP-191 for a peaq-homed machine, Ed25519 from the owner for a Solana-homed one. Still no key or token: the signature is the credential.

Rate limits

The MCR API allows 90 requests per minute per connecting address for each request path: /machines/1 and /machines/2 are counted separately. Over the limit you get 429 with a Retry-After header. The Verify read has its own budget of 60 requests per minute per IP address across all machine IDs; its 429 carries the coded envelope (RATE_LIMITED) and no Retry-After header.

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"	The server started without its contract addresses
"Chain unavailable"	RPC call to the node or a contract failed
"Empty DID"	DID path parameter is empty
"Invalid machine DID format"	/mcr and /machine only: the machine DID is not did:peaq:<decimal id> (an address DID, a raw address, or a bare number)
"Invalid Ethereum address format"	Operator DID or address does not match ^0x[a-fA-F0-9]{40}$
"Machine not registered"	No machine with this ID in MachineRegistry (/mcr, /machine)
"Machine not found"	No machine with this ID (machines endpoint)
"Token not found"	Token ID does not map to any machine (metadata endpoint)
"operator index syncing: block X of Y"	Operator listing only: the ownership index is more than 100 blocks behind the chain, or its worker has not read the chain head recently
"machines registered on another chain are not indexed yet; retry later"	Operator listing only: the Solana snapshot has not been taken or is out of date
"Machine is relocating to another chain; retry later"	The machine is moving between chains
"machine home chain is unreachable; retry later"	Reading a Solana-homed machine’s record failed
"rate_limited"	429: the server’s budget for home-chain lookups is spent; slow down and retry
"Internal server error"	Unhandled exception (logged server-side)

Coded envelope

The two monetization endpoints (GET, PUT) and every route under /v1/verify/ nest a stable machine-readable code instead of a bare string:

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

The read routes (/mcr, /machine, /machines, /metadata) use the same coded shape for 409 MACHINE_HOMED_ELSEWHERE, with home_protocol_chain_id next to code and message.

Branch on code, never on message. Two cases return neither shape:

• A request body that is not valid JSON gets a 422 whose detail is a list of validation objects with no code at all.
• A caller over the rate limit gets a 429 with the body {"error": "Rate limit exceeded: 90 per 1 minute"}.

Status codes

Code	Meaning
200 OK	Request succeeded; JSON body returned
400 Bad Request	On /mcr and /machine, the machine DID is not did:peaq:<decimal id>; on the operator listing, 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, or an Ed25519 signature does not verify for signer_pubkey (INVALID_SIGNATURE)
403 Forbidden	Monetization PUT only: the signer is not the machine’s owner or controller (peaq-homed), or not its owner (Solana-homed) (UNAUTHORIZED_SIGNER)
404 Not Found	The requested DID, machine ID, or token ID does not exist on-chain
409 Conflict	MACHINE_HOMED_ELSEWHERE on any machine route, including both monetization endpoints: the machine is homed on a chain this server cannot read, and the body carries home_protocol_chain_id. 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	Over the rate limit: the response carries Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. On a machine route, "rate_limited" means the server’s budget for home-chain lookups is spent.
500 Internal Server Error	Unhandled server exception
503 Service Unavailable	Service not initialised or chain/RPC call failed

DID format

GET /mcr/{did} and GET /machine/{did} take one form: did:peaq:<decimal machine id>, for example did:peaq:108934426058480933785963234320575706003575332367737915173645220784539698794848. An address DID, a raw address, or a bare decimal number returns 400 Invalid machine DID format.

GET /machines/{machine_id} and GET /metadata/{token_id} take the bare decimal ID as an integer. Anything else, including a DID, returns 422.

Operator DIDs on GET /operator/{did}/machines take did:peaq:0x<address> or the raw address 0x<address>.

The monetization endpoints take a machine DID or the bare decimal machine ID as key. An address DID returns 400 INVALID_REQUEST with the message only Tokenomics 2.0 decimal machine DIDs are supported, and a raw address also returns 400 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: identity, rating, bond status, service endpoints, and home-chain fields for a Solana-homed machine.

GET /operator/{did}/machines

Paginated list of the machines an operator address owns or controls, with per-machine MCR scores.

GET /metadata/{token_id}

Metadata for a machine token (token ID equals machine ID). 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.

GET /v1/verify/machines/{machineId}

Verify record of a machine: home chain, DID controller, operator, and independent KYB and chip statuses.

POST /v1/verify/chip/challenge

Five-minute challenge for one machine’s chip. Requires peaq’s onboarding token.

POST /v1/verify/chip/evidence

Submit the signed chip evidence for a challenge and get a receipt. Requires peaq’s onboarding token.

Machine Markets API

A separate surface on a separate host. Pairing, delegation policy, skill registry, service catalogue, and market search.

Machine Markets API overview

Base path, access model, error codes, common types, and the Machine Markets endpoints.