Skip to main content
Economics 2.0 monetization is live on peaq-mainnet since 2026-09-05. @peaqos/peaq-os-sdk 0.6.0 and peaq-os-sdk 0.6.0 talk to the 2.0 MCR at https://mcr-20.peaq.xyz, which now publishes the /.well-known/peaq-monetization signal (tokenomics-2.0-monetization-v1, chain 3338, the MachineRegistry address). Reads were verified against the mirrored 2.0 machines on 2026-09-05 (getMonetization returns PENDING for a machine that never opted in); writes were not exercised. agung-2026-08-28 still has no paired MCR (DEPLOYMENT_UNAVAILABLE). Tokenomics 1.0 machines stay on mcr.peaq.xyz through @peaqos/peaq-os-sdk@0.5.0 / peaq-os-sdk==0.5.0 (Python 3.11 or newer) with the 1.0 configuration.
An authorized signer turns a machine’s monetization on or off with a signed 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 (SDK 0.6.0+)

The configuration is a deployment ID. The SDK resolves the MCR URL, chain ID, MachineRegistry address, and protocol version from the same deployment record that activation uses; callers cannot supply or override any of them.

Machine key

Every call takes the machine as a full-width uint256 (bigint in JS, int in Python) or as did:peaq:<canonical decimal machine id>. 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

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

Python passes these through GetMonetizationOptions and SetMonetizationOptions.

The response

Errors

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.

Tokenomics 1.0 (SDK 0.5.0)

The previous client targets mcr.peaq.xyz and serves machines registered through IdentityRegistry. Available by pinning @peaqos/peaq-os-sdk@0.5.0 / peaq-os-sdk==0.5.0 (Python 3.11 or newer), or from peaq-os-cli<0.0.8 pinned together with peaq-os-sdk<0.6.0. The CLI pin alone resolves to CLI 0.0.7 with SDK 0.7.0, and peaqos monetize then crashes with a TypeError.
In 1.0 the signed message binds the IdentityRegistry address, the authorized signers are the machine wallet, the owner, or the on-chain operator, getMonetization also accepts did:peaq:0x<address>, and machine IDs fit a JS number range but the SDK still uses bigint. registry plus chainId are the domain binding: a signature made against the wrong pair recovers a non-authorized address and the server rejects it with 403 UNAUTHORIZED_SIGNER; verifyLocalRecovery / verify_local_recovery recovers the signer locally so you catch a wrong key before a write.

From the terminal

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