GET /v1/verify/machines/{machineId}

GET

verify

machines

{machineId}

curl --request GET \
  --url https://mcr.peaq.xyz/v1/verify/machines/{machineId}

const options = {method: 'GET'};

fetch('https://mcr.peaq.xyz/v1/verify/machines/{machineId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mcr.peaq.xyz/v1/verify/machines/{machineId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://mcr.peaq.xyz/v1/verify/machines/{machineId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://mcr.peaq.xyz/v1/verify/machines/{machineId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

Endpoint

GET /v1/verify/machines/{machineId}

Returns the Verify record of one machine: its home chain, its DID controller and in their native address kinds, and one status per topic (KYB on the operator address, chip on the machine ID). Public, no key. Beta: the route is stable for v1 beta, the response may still change; the SDK and CLI wrappers are marked experimental.

The route serves peaq-homed machines. A machine homed on Solana returns 503 VERIFY_READ_UNAVAILABLE.

Send Accept: application/json with no query string and no body; the route needs no credentials. The route never redirects and never caches (Cache-Control: no-store).

Path parameters

string

default:"123"

required

Decimal machine ID as a string, 1 to 2^256-1, no sign, whitespace or leading zeros. A DID (did:peaq:...), an address or any other spelling returns 400 INVALID_MACHINE_ID. The default 123 is a placeholder and returns 404 MACHINE_NOT_FOUND; put in your own machine ID.

Response

200 OK, Content-Type: application/json; charset=utf-8. The body is at most 4096 bytes and every field is present.

Field	Type	Description
`machineId`	string	The requested decimal machine ID
`machineDid`	string	`did:peaq:<machineId>`
`homeChain.kind`	string	`"evm"` on peaq mainnet. The schema also defines `"solana"`, so clients should accept both
`homeChain.chainId`	string	EVM only: decimal chain ID (`"3338"` for peaq mainnet)
`homeChain.genesisHash`	string	Solana only: full base58 genesis hash of the cluster
`didController.kind`	string	Same as `homeChain.kind`
`didController.address`	string	The effective DID controller: EIP-55 address on EVM, base58 on Solana. Falls back to the owner when no controller is set
`operator.kind`	string	Same as `homeChain.kind`
`operator.address`	string	The machine NFT owner on EVM, the native machine owner on Solana. This address is the KYB subject
`verification.kyb.status`	string	`unverified`, `verified`, `expired` or `revoked`
`verification.chip.status`	string	`unverified`, `verified`, `expired` or `revoked`

The two statuses are independent. unverified means no record exists for that topic and is the normal answer for an existing machine whose operator has no KYB attestation or that has no chip record. revoked takes precedence over expired. There is no aggregate “verified” boolean, and the response carries no evidence, timestamps, block numbers or registry addresses.

Error responses

Errors use the coded envelope:

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

Status	`code`	Condition
400	`INVALID_MACHINE_ID`	`machineId` is not a canonical decimal in range
400	`INVALID_REQUEST`	A query string or a body was sent
404	`MACHINE_NOT_FOUND`	No machine with this ID on any chain the server reads
404	`VERIFY_ROUTE_NOT_FOUND`	Unknown path under `/v1/verify/`
405	`METHOD_NOT_ALLOWED`	Any method other than `GET`
406	`NOT_ACCEPTABLE`	`Accept` excludes JSON
413	`REQUEST_TOO_LARGE`	The request was rejected as too large before validation. A `GET` that carries a body gets `400 INVALID_REQUEST` instead
429	`RATE_LIMITED`	Over 60 requests per minute from one IP address
500	`INTERNAL_ERROR`	Unhandled server error
503	`VERIFY_READ_UNAVAILABLE`	The machine is homed on Solana, or the read could not complete (see below)

The schema allows a 429 to carry Retry-After (1 to 60 seconds); v1 sends no Retry-After. A 503 covers three cases: the machine is homed on Solana, the home chain or the registry could not be read within the request deadline, or the server could not build a valid record from what it read. A Solana-homed machine always gets 503 VERIFY_READ_UNAVAILABLE, so retrying does not help. For a peaq-homed machine the 503 can be transient: repeat the request after a short pause. The SDKs and the CLI do not retry for you. Branch on code, never on message. Only MACHINE_NOT_FOUND means there is no machine with this ID in the Verify service; every other error is a request or service failure and says nothing about the machine’s status.

Example

curl -H "Accept: application/json" "${PEAQOS_VERIFY_API_URL}/v1/verify/machines/123"

const PEAQOS_VERIFY_API_URL = process.env.PEAQOS_VERIFY_API_URL ?? "https://mcr.peaq.xyz";
const response = await fetch(`${PEAQOS_VERIFY_API_URL}/v1/verify/machines/123`, {
  headers: { Accept: "application/json" },
});
const data = await response.json();
console.log(data.homeChain.kind, data.verification.kyb.status, data.verification.chip.status);

import os

import requests

PEAQOS_VERIFY_API_URL = os.environ.get("PEAQOS_VERIFY_API_URL", "https://mcr.peaq.xyz")
response = requests.get(
    f"{PEAQOS_VERIFY_API_URL}/v1/verify/machines/123",
    headers={"Accept": "application/json"},
)
data = response.json()
print(data["homeChain"]["kind"], data["verification"]["kyb"]["status"], data["verification"]["chip"]["status"])

Illustrative response (peaq-homed machine). 123 is a placeholder; the live call returns 404 MACHINE_NOT_FOUND until you put in your own machine ID.

{
  "machineId": "123",
  "machineDid": "did:peaq:123",
  "homeChain": { "kind": "evm", "chainId": "3338" },
  "didController": { "kind": "evm", "address": "0x8617E340B3D01FA5F11F306F4090FD50E238070D" },
  "operator": { "kind": "evm", "address": "0x52908400098527886E0F7030069857D2E4169EE7" },
  "verification": {
    "kyb": { "status": "verified" },
    "chip": { "status": "unverified" }
  }
}

SDK and CLI

The SDKs wrap this route as VerifyReadClient.getMachineVerificationAcrossChains (JS) and VerifyReadClient.get_machine_verification_across_chains (Python): one request, a five-second deadline, a 4096-byte ceiling, no retry, no redirect, no cache. The CLI exposes it as peaqos verify status.

Chip intake routes

Two more routes exist on the same API for peaq’s onboarding service:

Route	Returns
`POST /v1/verify/chip/challenge`	`201` with the challenge context
`POST /v1/verify/chip/evidence`	`202` with a receipt

Both require Authorization: Bearer <onboarding token>; without it every request answers 401 ONBOARDING_AUTH_REQUIRED. Machine operators do not call them: the onboarding service hands you the challenge context, you produce the evidence with the SDK or peaqos verify chip, and the service submits it.

API reference overview lists all endpoints and common error patterns.
GET /machines/{machine_id} returns the Machine Card of the same machine.

⌘I

GET /v1/verify/machines/{machineId}

curl --request GET \
  --url https://mcr.peaq.xyz/v1/verify/machines/{machineId}

const options = {method: 'GET'};

fetch('https://mcr.peaq.xyz/v1/verify/machines/{machineId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mcr.peaq.xyz/v1/verify/machines/{machineId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://mcr.peaq.xyz/v1/verify/machines/{machineId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://mcr.peaq.xyz/v1/verify/machines/{machineId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

​Endpoint

​Path parameters

​Response

​Error responses

​Example

​SDK and CLI

​Chip intake routes

​Related endpoints

Endpoint

Path parameters

Response

Error responses

Example

SDK and CLI

Chip intake routes

Related endpoints