Skip to main content
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.
An authorized signer (the , the owner, or the on-chain operator) 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. Opting in requires the machine to be registered, , and not deactivated (server-enforced). Opting out is always allowed. The read is public and doubles as the pre-provisioning check.

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 the code; 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.
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.