Monetization opt-in ships in
@peaqos/peaq-os-sdk 0.5.0+ (JS/TS) and peaq-os-sdk 0.5.0+ (Python) under the monetization namespace. It is the client for the MCR API’s PUT /machine/{key}/monetization and GET endpoints.Quick start
getMonetization / get_monetization accepts a numeric machine ID or a DID (did:peaq:0x...) as its second argument. The writes are stricter: optIn / optOut take the numeric machine ID there, and a DID is passed only as the optional third key argument (optIn(config, 42n, "did:peaq:0x..."), opt_in(config, 42, key="did:peaq:0x...")). Either way the signed message always carries the numeric machine ID; when you only know the DID, read the state first and take machineId from the response.
Configuration
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. Both SDKs also expose an offline self-check (verifyLocalRecovery / verify_local_recovery) that recovers the signer locally and compares it to the address you expect, catching a wrong or swapped signing key before a write burns a request. It cannot catch a wrong-environment chainId (a locally consistent signature still recovers fine); the built-in guards there are that a non-positive chainId is rejected client-side and the registry is always lowercased into the message for you.
The implemented opt-in is a pure signed on/off toggle: it carries no capability schema and no service subtype. Machine IDs can exceed 2^53, so the JS SDK treats
machineId as bigint end to end and parses the response’s machine_id losslessly.The response
Every call returns the monetization state:Errors
Server errors arrive as the coded envelope and map to a typed error carrying thecode; branch on the code, never on the message text. The full code table (with the opt-in-only bond and deactivation gates, the freshness window, and STALE_SIGNATURE replay protection) is on the PUT endpoint page.
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 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 wire contract, canonical message, and error codes

