PUT /machine/{key}/monetization

PUT

machine

{key}

monetization

curl --request PUT \
  --url https://mcr.peaq.xyz/machine/{key}/monetization \
  --header 'Content-Type: application/json' \
  --data '
{
  "opted_in": true,
  "timestamp": 123,
  "signature": "<string>"
}
'

import requests

url = "https://mcr.peaq.xyz/machine/{key}/monetization"

payload = {
    "opted_in": True,
    "timestamp": 123,
    "signature": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({opted_in: true, timestamp: 123, signature: '<string>'})
};

fetch('https://mcr.peaq.xyz/machine/{key}/monetization', 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/machine/{key}/monetization",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'opted_in' => true,
    'timestamp' => 123,
    'signature' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://mcr.peaq.xyz/machine/{key}/monetization"

	payload := strings.NewReader("{\n  \"opted_in\": true,\n  \"timestamp\": 123,\n  \"signature\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://mcr.peaq.xyz/machine/{key}/monetization")
  .header("Content-Type", "application/json")
  .body("{\n  \"opted_in\": true,\n  \"timestamp\": 123,\n  \"signature\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://mcr.peaq.xyz/machine/{key}/monetization")

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

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"opted_in\": true,\n  \"timestamp\": 123,\n  \"signature\": \"<string>\"\n}"

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

Endpoint

PUT /machine/{key}/monetization

Sets a machine’s monetization state (opt in or opt out). This is the MCR API’s only signature-verified write endpoint: the caller proves authority with an (personal_sign) signature over a canonical message. A machine’s owner, its , or its on-chain operator may sign (the same authorization triple as EventRegistry.submitEvent). No on-chain transaction is made. Opting in requires the machine to be and not deactivated. Opting out is always allowed (a machine can always exit), so it skips those checks.

Path parameters

string

required

Machine DID (did:peaq:0x...) or a decimal machine ID (e.g. 42).

Request body

boolean

required

true to opt in, false to opt out. Must be a JSON boolean (not "true" or 1).

integer

required

Unix seconds when the message was signed. Must be a positive JSON integer inside the freshness window (see below).

string

required

The EIP-191 signature: 0x followed by exactly 130 hex characters (65 bytes).

Canonical message

The client must build and sign this exact string, byte for byte. Fields are LF-separated (\n) with no trailing newline:

peaq-mcr monetization
registry: <identity_registry_address, lowercased>
chain_id: <chain id>
machine_id: <numeric machine ID>
opted_in: <true|false>
timestamp: <timestamp>

registry is the server’s identity registry address, lowercased.
chain_id is the chain the server reads from. Together with the registry it binds the signature to one deployment, so a signature captured on one chain does not authorize the same action on another.
machine_id is the numeric machine ID. Even when the URL key is a DID, the signed message uses the resolved numeric ID.
opted_in is the lowercase string true or false, matching the body field.

Sign it with personal_sign (JS) or eth_account’s encode_defunct(text=message) (Python).

Freshness window

The timestamp must fall within the freshness window (by default up to 300 seconds in the past and 30 seconds of future clock skew). Replaying an old signature after the window closes is rejected, and within the window a strictly newer timestamp is required to overwrite a previously applied decision (see STALE_SIGNATURE).

Response

200 OK

Field	Type	Description
`machine_id`	integer	The resolved numeric machine ID
`status`	string	The stored state after this write: `"OPTED_IN"` or `"OPTED_OUT"`
`signer`	string	The address recovered from the signature (EIP-55 checksum) that authorized the change
`updated_at`	integer	Unix seconds when the server applied the change

Error responses

Errors use a coded envelope: {"detail": {"code", "message"}}. Branch on code, never on message. The one exception is a body that is not valid JSON: that returns 422 with detail as a list of validation objects carrying no code.

Status	`code`	Condition
400	`INVALID_REQUEST`	Malformed body (wrong types, missing field), bad signature format, non-positive timestamp, unparseable `key`, or machine ID out of the int64 range
400	`TIMESTAMP_OUT_OF_WINDOW`	`timestamp` is outside the freshness window
401	`INVALID_SIGNATURE`	The signature bytes cannot be recovered to any address
403	`UNAUTHORIZED_SIGNER`	The recovered signer is not the machine’s owner, machine wallet, or on-chain operator
404	`MACHINE_NOT_FOUND`	The `key` does not resolve to an existing machine
409	`MACHINE_NOT_BONDED`	Opt-in only: the machine has not posted a stake bond
409	`MACHINE_DEACTIVATED`	Opt-in only: the machine is deactivated
409	`STALE_SIGNATURE`	A newer or equal `timestamp` has already been applied for this machine
500	`INTERNAL_ERROR`	The state could not be persisted
503	`CHAIN_UNAVAILABLE`	An on-chain read failed while resolving or authorizing

Example

curl -X PUT "${PEAQOS_MCR_API_URL}/machine/42/monetization" \
  -H 'Content-Type: application/json' \
  -d '{
        "opted_in": true,
        "timestamp": 1712000000,
        "signature": "0x<130 hex chars>"
      }'

const message = [
  "peaq-mcr monetization",
  `registry: ${REGISTRY_ADDRESS.toLowerCase()}`,
  `chain_id: ${CHAIN_ID}`,
  `machine_id: ${machineId}`,
  `opted_in: true`,
  `timestamp: ${timestamp}`,
].join("\n");

const signature = await wallet.signMessage(message); // EIP-191 personal_sign

await fetch(`${PEAQOS_MCR_API_URL}/machine/${machineId}/monetization`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ opted_in: true, timestamp, signature }),
});

from eth_account import Account
from eth_account.messages import encode_defunct
import requests, time

timestamp = int(time.time())
message = "\n".join([
    "peaq-mcr monetization",
    f"registry: {REGISTRY_ADDRESS.lower()}",
    f"chain_id: {CHAIN_ID}",
    f"machine_id: {machine_id}",
    "opted_in: true",
    f"timestamp: {timestamp}",
])

signed = Account.sign_message(encode_defunct(text=message), private_key=key)

requests.put(
    f"{PEAQOS_MCR_API_URL}/machine/{machine_id}/monetization",
    json={"opted_in": True, "timestamp": timestamp, "signature": signed.signature.to_0x_hex()},
)

Response

{
  "machine_id": 42,
  "status": "OPTED_IN",
  "signer": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
  "updated_at": 1712000004
}

SDK and CLI support

Both SDKs wrap this endpoint, building and signing the canonical message for you: see the opt-in SDK reference (optIn / optOut in JS, opt_in / opt_out in Python). The CLI exposes it as peaqos monetize opt-in | opt-out.

GET /machine//monetization reads the current state without a signature.
GET /mcr/ returns the machine’s credit rating.

GET /machine/{key}/monetizationRead a machine's current monetization state.

⌘I

PUT /machine/{key}/monetization

curl --request PUT \
  --url https://mcr.peaq.xyz/machine/{key}/monetization \
  --header 'Content-Type: application/json' \
  --data '
{
  "opted_in": true,
  "timestamp": 123,
  "signature": "<string>"
}
'

import requests

url = "https://mcr.peaq.xyz/machine/{key}/monetization"

payload = {
    "opted_in": True,
    "timestamp": 123,
    "signature": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({opted_in: true, timestamp: 123, signature: '<string>'})
};

fetch('https://mcr.peaq.xyz/machine/{key}/monetization', 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/machine/{key}/monetization",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'opted_in' => true,
    'timestamp' => 123,
    'signature' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://mcr.peaq.xyz/machine/{key}/monetization"

	payload := strings.NewReader("{\n  \"opted_in\": true,\n  \"timestamp\": 123,\n  \"signature\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://mcr.peaq.xyz/machine/{key}/monetization")
  .header("Content-Type", "application/json")
  .body("{\n  \"opted_in\": true,\n  \"timestamp\": 123,\n  \"signature\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://mcr.peaq.xyz/machine/{key}/monetization")

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

request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"opted_in\": true,\n  \"timestamp\": 123,\n  \"signature\": \"<string>\"\n}"

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

​Endpoint

​Path parameters

​Request body

​Canonical message

​Freshness window

​Response

​Error responses

​Example

​SDK and CLI support

​Related endpoints

Endpoint

Path parameters

Request body

Canonical message

Freshness window

Response

Error responses

Example

SDK and CLI support

Related endpoints