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>",
  "signer_pubkey": "<string>"
}
'

import requests

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

payload = {
    "opted_in": True,
    "timestamp": 123,
    "signature": "<string>",
    "signer_pubkey": "<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>',
    signer_pubkey: '<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>',
    'signer_pubkey' => '<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  \"signer_pubkey\": \"<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  \"signer_pubkey\": \"<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  \"signer_pubkey\": \"<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 a signature over a canonical message. For a peaq-homed machine the signature is (personal_sign), and the machine’s owner or its controller (set in MachineRegistry) may sign. For a Solana-homed machine the signature is Ed25519, and only the owner recorded on the machine account may sign. No on-chain transaction is made. Opting in requires the machine to be , and a peaq-homed machine must also be available (not deactivated or paused). Opting out is always allowed (a machine can always exit), so it skips those checks.

Path parameters

string

required

Machine DID (did:peaq:<decimal machine id>) or the bare decimal machine ID. An address-form DID (did:peaq:0x...) or a raw address returns 400 INVALID_REQUEST.

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). When signer_pubkey is present, a base58 Ed25519 signature of at most 88 characters instead.

string

For a machine homed on Solana: the owner’s base58 Ed25519 public key (at most 44 characters). When present, the server verifies signature as a base58 Ed25519 signature by this key over the Solana canonical message instead of EIP-191, and only the machine’s owner may sign. Sending it for a peaq-homed machine returns 403 UNAUTHORIZED_SIGNER. null is rejected with 400 INVALID_REQUEST; omit the field for the EIP-191 path.

Canonical message

The client must build and sign this exact string, byte for byte. Fields are LF-separated (\n) with no trailing newline. For a peaq-homed machine (EIP-191):

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

registry is the server’s MachineRegistry address, lowercased. The server publishes it, with chain_id, at GET /.well-known/peaq-monetization.
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 decimal machine ID. Even when the URL key is a DID, the signed message uses the resolved decimal 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). For a Solana-homed machine (Ed25519, with signer_pubkey in the body), the registry and chain_id lines are replaced by audience and home_chain:

peaq-mcr monetization
audience: <chain id>
home_chain: <home protocol chain id>
machine_id: <decimal machine ID>
opted_in: <true|false>
timestamp: <timestamp>

audience is the chain ID of the server’s deployment (the chain_id published at GET /.well-known/peaq-monetization), so a signature cannot be replayed against another deployment that serves the same machine.
home_chain is the machine’s home protocol chain ordinal (5 for Solana), so a signature cannot be replayed if the machine relocates.

Sign the UTF-8 bytes of this exact text with the owner’s Ed25519 key, with no transaction and no envelope (what a wallet’s plain signMessage produces), and send the signature base58-encoded. Both SDKs refuse a Solana-homed write before signing (SOLANA_MONETIZATION_UNVERIFIED), so this path is for direct HTTP calls. See Monetization opt-in.

Freshness window

The timestamp must fall within the freshness window: 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`	string	The resolved machine ID as a decimal string
`status`	string	The stored state after this write: `"OPTED_IN"` or `"OPTED_OUT"`
`signer`	string	Who authorized the change: the address recovered from an EIP-191 signature (EIP-55 checksum), or the owner’s base58 public key for a Solana-homed machine
`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. Two responses carry no code: a body that is not valid JSON returns 422 with detail as a list of validation objects, and a caller over the rate limit gets 429 with the body {"error": "Rate limit exceeded: 90 per 1 minute"}.

Status	`code`	Condition
400	`INVALID_REQUEST`	Malformed body (wrong types, missing field, `signer_pubkey: null`), bad signature format, non-positive timestamp, address-form DID, unparseable `key`, or machine ID above `2^256-1`
400	`TIMESTAMP_OUT_OF_WINDOW`	`timestamp` is outside the freshness window
401	`INVALID_SIGNATURE`	The EIP-191 signature cannot be recovered to any address, or the Ed25519 signature does not verify for `signer_pubkey`
403	`UNAUTHORIZED_SIGNER`	The signer is not the machine’s owner or controller (peaq-homed) or not its owner (Solana-homed), or `signer_pubkey` was sent for a peaq-homed machine
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: a peaq-homed machine is deactivated
409	`STALE_SIGNATURE`	A newer or equal `timestamp` has already been applied for this machine
409	`MACHINE_HOMED_ELSEWHERE`	The machine is homed on a chain this server cannot read; the body carries `home_protocol_chain_id`
500	`INTERNAL_ERROR`	The state could not be persisted
503	`CHAIN_UNAVAILABLE`	An on-chain read failed while resolving or authorizing
503	`MACHINE_UNAVAILABLE`	The machine is relocating to another chain, or (opt-in only) a peaq-homed machine is temporarily unavailable; retry later

Example

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

import { privateKeyToAccount } from "viem/accounts";

const PEAQOS_MCR_API_URL = process.env.PEAQOS_MCR_API_URL ?? "https://mcr.peaq.xyz";
const REGISTRY_ADDRESS = "0x64b93Cc29b251fAFa83BD110cDB1C24207f85536"; // peaq mainnet MachineRegistry
const CHAIN_ID = 3338; // peaq mainnet
const account = privateKeyToAccount(process.env.PEAQOS_PRIVATE_KEY); // owner or controller key
const machineId = "108934426058480933785963234320575706003575332367737915173645220784539698794848";
const timestamp = Math.floor(Date.now() / 1000);

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

const signature = await account.signMessage({ message }); // EIP-191 personal_sign

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

import os
import time

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

PEAQOS_MCR_API_URL = os.environ.get("PEAQOS_MCR_API_URL", "https://mcr.peaq.xyz")
REGISTRY_ADDRESS = "0x64b93Cc29b251fAFa83BD110cDB1C24207f85536"  # peaq mainnet MachineRegistry
CHAIN_ID = 3338  # peaq mainnet
key = os.environ["PEAQOS_PRIVATE_KEY"]  # owner or controller key
machine_id = "108934426058480933785963234320575706003575332367737915173645220784539698794848"

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)

response = requests.put(
    f"{PEAQOS_MCR_API_URL}/machine/{machine_id}/monetization",
    json={"opted_in": True, "timestamp": timestamp, "signature": signed.signature.to_0x_hex()},
)
print(response.json()["status"])  # "OPTED_IN"

Response

{
  "machine_id": "<decimal machine id>",
  "status": "OPTED_IN",
  "signer": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
  "updated_at": 1712000004
}

SDK and CLI support

For a peaq-homed machine 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. For a Solana-homed machine the SDKs refuse before signing (SOLANA_MONETIZATION_UNVERIFIED); use the direct HTTP flow above.

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

⌘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>",
  "signer_pubkey": "<string>"
}
'

import requests

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

payload = {
    "opted_in": True,
    "timestamp": 123,
    "signature": "<string>",
    "signer_pubkey": "<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>',
    signer_pubkey: '<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>',
    'signer_pubkey' => '<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  \"signer_pubkey\": \"<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  \"signer_pubkey\": \"<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  \"signer_pubkey\": \"<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