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-widthuint256 (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 currentMachineRegistry 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 fetchesGET {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 targetsmcr.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.
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 aspeaqos 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 1.0 wire contract, canonical message, and error codes
- Economics 2.0: what changed and what is live

