Monetize: Opt-in

Toggle a machine’s monetization on or off from the SDK, and read its state: the client for the MCR API’s signed opt-in endpoint.

An authorized signer turns a machine’s monetization on or off with a signed EIP-191 toggle, and anyone can read the current state. The SDK builds the byte-exact canonical message, signs it, and handles the coded error envelope, so you never assemble the message by hand. State is stored off-chain in the MCR server; no on-chain transaction is made.

Opting in requires the machine to be bonded and not deactivated (server-enforced). Opting out is always allowed. The read is public and doubles as the pre-provisioning check.

Economics 2.0

The configuration is a deployment ID. The SDK resolves the MCR URL (https://mcr.peaq.xyz for peaq-mainnet), chain ID, MachineRegistry address, and protocol version from the same deployment record that activation uses; callers cannot supply or override any of them.

JavaScript

import {
  optIn,
  optOut,
  getMonetization,
  eip191SignerFromPrivateKey,
  type MonetizationConfig,
} from "@peaqos/peaq-os-sdk";

// The machine's current owner or DID controller key
const privateKey = process.env.PEAQOS_PRIVATE_KEY as `0x${string}`;

const config: MonetizationConfig = {
  deploymentId: "peaq-mainnet",
  signer: eip191SignerFromPrivateKey(privateKey),
};

const machineId = 57896044618658097711785492504343953926634992332820282019728792003956564819975n;

// Opt in (machine must be bonded and not deactivated).
const state = await optIn(config, machineId);
console.log(state.status); // "OPTED_IN"

// Public read, no signer needed: the pre-provisioning check.
const current = await getMonetization(config, machineId);
if (current.status !== "OPTED_IN") {
  throw new Error("Opt in before provisioning");
}

// Opt out later to turn monetization off (always allowed).
await optOut(config, machineId);

For a machine homed on Solana (guide) both SDKs carry the owner-signed path (solanaSigner / solana_signer in MonetizationConfig, a five-line message with home_chain: 5, plain Ed25519 signMessage, body with signer_pubkey), but Solana-homed writes are refused. When solanaSigner / solana_signer is set, the SDK first reads the machine’s home chain (a compatibility GET and a profile GET) and refuses a Solana-homed write with MonetizationValidationError (JS) / ValidationError (Python) code SOLANA_MONETIZATION_UNVERIFIED before anything is signed. Without a Solana signer the SDK does not check the home chain and sends the EIP-191 write. Reads work for every home. Details: SDK JS, SDK Python.

Machine key

Reads take the machine as a full-width uint256 (bigint in JS, int in Python) or as did:peaq:<canonical decimal machine id>; optIn / opt_in and optOut / opt_out take the numeric machineId / machine_id, the DID form goes into their separate key argument. Address-form DIDs (did:peaq:0x…), decimal strings in JS, leading zeros, signs, and exponents are rejected locally before any HTTP. There is no lookup from a 1.0 address DID to a 2.0 machine ID.

Who may sign

The machine’s current MachineRegistry owner or DID controller. A legacy machine-wallet key or a 1.0 EventRegistry operator key is not authorized (403 UNAUTHORIZED_SIGNER). The canonical message binds registry: <MachineRegistry address, lowercased> and chain_id: 3338.

Configuration

Field	Notes
deploymentId / deployment_id	"peaq-mainnet" only. "agung-2026-08-28" has no paired MCR and raises TokenomicsConfigError DEPLOYMENT_UNAVAILABLE.
signer	Owner or controller key. Writes only; reads are unsigned.
solanaSigner / solana_signer	The native owner’s Solana signer (JS: PeaqosClient.solanaSignerFromWallet(name); Python: any object with a base58 address and sign_message(bytes) -> bytes). When set, a write to a Solana-homed machine is refused with SOLANA_MONETIZATION_UNVERIFIED before signing.
fetch (JS) / transport (Python)	Optional low-level HTTP adapter. It receives only SDK-built, deployment-bound URLs and cannot change the base URL.

The resolved values are readable (api_base, registry, chain_id, api_version in Python) but not settable. apiBase, registry, and chainId as constructor fields are gone; passing them is a TypeError in Python and a type error in TypeScript.

Compatibility check

Before every read and write the SDK fetches GET {apiBase}/.well-known/peaq-monetization and requires the exact protocol version (tokenomics-2.0-monetization-v1, exported as TOKENOMICS_MONETIZATION_API_VERSION), the canonical decimal chain ID, and the lowercased MachineRegistry address from the selected deployment. A write runs this check before invoking the signer. Missing, malformed, or mismatched signals raise MonetizationCompatibilityError (code MONETIZATION_API_INCOMPATIBLE). Not cached, cannot be bypassed.

Retries, deadline, cancellation

Option	Default	Behaviour
maxUnavailableRetries / max_unavailable_retries	2	Retries a write after 503 MACHINE_UNAVAILABLE, the only retryable code. Each attempt re-signs with a fresh timestamp. Reads are not retried.
unavailableRetryDelayMs / unavailable_retry_delay_seconds	1000 ms / 1.0 s	Pause before each retry.
timeoutMs / timeout_seconds	30000 ms / 30.0 s	One end-to-end deadline covering validation, the compatibility check, signing, retries, and response parsing. Retries do not reset it. Raises MonetizationTimeoutError.
signal / cancel	none	Caller abort. Raises MonetizationCancellationError (JS) / MonetizationCancelledError (Python).

Python passes these through GetMonetizationOptions and SetMonetizationOptions.

The response

Field	Notes
machineId / machine_id	The machine ID, parsed losslessly. On the wire it is a canonical decimal string; a JSON number is rejected.
status	"PENDING", "OPTED_IN", or "OPTED_OUT". PENDING means never opted in or out. 2.0 machines start at PENDING; 1.0 decisions are not imported.
signer	Key that authorized the current state; null/None only when PENDING. An EVM address, or a base58 Solana public key for a Solana-homed machine (string | null in JS); the two forms are syntactically disjoint, there is no signerKind field.
updatedAt / updated_at	Unix seconds of the last change; null/None only when PENDING.

Errors

Class (JS / Python)	Code	Meaning
TokenomicsConfigError	DEPLOYMENT_UNKNOWN, DEPLOYMENT_UNAVAILABLE, DEPLOYMENT_NOT_CONFIGURED	Bad or missing deployment; agung has no monetization
MonetizationCompatibilityError	MONETIZATION_API_INCOMPATIBLE	The /.well-known/peaq-monetization signal is missing or does not match the deployment
MonetizationApiError / MonetizationError	UNAUTHORIZED_SIGNER, MACHINE_NOT_BONDED, MACHINE_DEACTIVATED, STALE_SIGNATURE, MACHINE_UNAVAILABLE (503, retryable), INVALID_REQUEST, …	Server-side coded envelope; branch on the code, never the message. Full table on the PUT endpoint page
MonetizationNetworkError, MonetizationResponseError, MonetizationTimeoutError, MonetizationCancellationError / MonetizationCancelledError		Transport, malformed response, deadline, caller abort
MonetizationValidationError / ValidationError	UNSUPPORTED_HOME_CHAIN, SIGNER_INCOMPATIBLE_WITH_HOME, SOLANA_MONETIZATION_UNVERIFIED, SIGNER_NOT_NATIVE_OWNER, AUTHORIZATION_CONTEXT_CHANGED, INVALID_SIGNER_OUTPUT (exported as MONETIZATION_REFUSAL_CODE in both SDKs)	Rejected machine key or option locally, raised before any HTTP; and the refusal of a Solana-homed write, raised after the home-chain read and before signing

Re-sending the identical signed request surfaces STALE_SIGNATURE; re-signing the same state with a newer timestamp succeeds, so the toggle is idempotent to retry.

From the terminal

The CLI wraps this surface as peaqos monetize opt-in | opt-out | status; all signing and HTTP stay in the SDK.

Related

• Monetize function: where opt-in fits in the flow
• Provisioning SDK reference: the step after opting in
• PUT /machine/{key}/monetization: the wire contract, canonical message, and error codes
• Economics 2.0: what changed and what is live