Fleet onboarding (operator-controlled)

One operator, many machines. Under Economics 2.0 the account that signs activateMachine becomes the machine’s owner and pays its , so a fleet is built the other way round from Tokenomics 1.0: each machine signs its own activation with its own key, and your operator address is recorded as the machine’s DID controller. The operator then runs lifecycle, renewals, and DID updates for the whole fleet.

Operator-sponsored registration is gone. registerFor / register_for (the 1.0 proxy pattern where the operator paid and owned every identity) has no Economics 2.0 equivalent: MachineStateAndSync.activateMachine makes msg.sender both owner and payer, and the SDKs throw SPONSORED_ACTIVATION_UNSUPPORTED in Tokenomics mode. If a machine cannot hold a key and funds, there is no fallback; do not make the operator the owner instead, because the owner is the account that can transfer the NFT.

Rights in the machine-owned, operator-controlled model

Who	Can	Cannot
Machine wallet (owner)	Transfer the NFT; rotate or clear the controller; everything the controller can
Operator (controller)	Suspend and resume; renew the subscription (paying from the operator wallet); update verification methods, authentication, and service endpoints	Transfer the NFT; rotate or clear the controller

Credits from renewals (bonding reward and voucher credit) land on the owner, even when the controller pays. Both parties should know this before onboarding.

Prerequisites

Node.js ≥ 22 with @peaqos/peaq-os-sdk 0.7.0+, or Python 3.10+ with peaq-os-sdk 0.7.1+, or peaq-os-cli 0.0.8+ on peaq-os-sdk 0.7.1+
An operator wallet for gas (it signs nothing during activation, but signs later renewals and DID updates)
Each machine wallet funded with its tier bond plus gas. The bond is quoted per tier at the oracle rate; preview one activation first and fund every machine to that amount plus a gas margin. The operator can fund machine wallets from the Gas Station (2FA-gated) for gas and top up the bond from any PEAQ-holding address.
Environment variables configured per the install guide

JS examples load .env via import "dotenv/config". Python’s from_env() reads from the shell, so export the file first with set -a && source .env && set +a or call load_dotenv().

From the terminal

The CLI does one machine per command. --for and --machine-key switch to machine-owned mode: the machine key signs and pays, your PEAQOS_PRIVATE_KEY address becomes controller.

peaqos activate \
  --for 0xMachineAddress --machine-key ./machine.key \
  --machine-type Sensor --credential-subject-hex 0x<per-machine-anchor> \
  --manufacturer 0x3333333333333333333333333333333333333333 \
  --tier entry --did-document ./did.json --dry-run     # drop --dry-run to submit

Loop it over your key files with --json --yes for scripts. Afterwards the operator manages every machine with peaqos machine ... (status, suspend, resume, subscription renew, DID setters). See CLI: activate and CLI: machine.

Single machine, from code

Create the operator client

Used for funding, previews, and later management. It never signs an activation.

import "dotenv/config";
import { PeaqosClient } from "@peaqos/peaq-os-sdk";

const operator = PeaqosClient.fromEnv();
console.log("Operator:", operator.address);

from dotenv import load_dotenv
from peaq_os_sdk import PeaqosClient

load_dotenv()

operator = PeaqosClient.from_env()
print("Operator:", operator.address)

Generate a keypair for the machine

Each machine needs its own . Store the key on the device or in a secrets vault: it is the owner key of that machine’s NFT.

const machineKey = PeaqosClient.generateKeypair();
console.log("Machine address:", machineKey.address);

machine_address, machine_private_key = PeaqosClient.generate_keypair()
print("Machine address:", machine_address)

Fund the machine wallet

Gas from the Gas Station (2FA on the operator wallet), the bond from any PEAQ-holding address.

const FAUCET_URL = "https://depinstation.peaq.xyz";

await operator.fundFromGasStation(
  { ownerAddress: operator.address, targetWalletAddress: machineKey.address, chainId: "peaq", twoFactorCode: "654321" },
  FAUCET_URL,
);
// Then transfer the previewed netPeaqAmount (plus a margin) to machineKey.address from your treasury wallet.

FAUCET_URL = "https://depinstation.peaq.xyz"

operator.fund_from_gas_station(
    owner_address=operator.address, target_wallet_address=machine_address, chain_id="peaq",
    two_factor_code="654321", faucet_base_url=FAUCET_URL,
)
# Then transfer the previewed net_peaq_amount (plus a margin) to machine_address from your treasury wallet.

Build the machine client in Tokenomics mode

const machine = new PeaqosClient<"tokenomics20">({
  rpcUrl: operator.rpcUrl,
  privateKey: machineKey.privateKey,
  contracts: operator.contracts,
  tokenomics20: { deploymentId: "peaq-mainnet" },
});

from peaq_os_sdk import Tokenomics20Config

machine = PeaqosClient(
    rpc_url=operator.rpc_url,
    private_key=machine_private_key,
    identity_registry=operator.contracts.identity_registry,
    identity_staking=operator.contracts.identity_staking,
    event_registry=operator.contracts.event_registry,
    machine_nft=operator.contracts.machine_nft,
    did_registry=operator.contracts.did_registry,
    batch_precompile=operator.contracts.batch_precompile,
    tokenomics20=Tokenomics20Config(deployment_id="peaq-mainnet"),
)

Activate with the operator as controller

controller is the operator address. The machine signs, owns the NFT, and pays the bond.

const params = {
  controller: operator.address,
  verificationMethods: [{ id: "#key-1", methodType: "Ed25519VerificationKey2020", controller: operator.address, publicKeyMultibase: "z6Mk..." }],
  authentication: [0n],
  serviceEndpoints: [{ id: "#docs", serviceType: "Documentation", serviceEndpoint: "https://example.com/docs" }],
  machineType: "Sensor",
  credentialSubject: "0x<per-machine-anchor>",
  manufacturer: "0x3333333333333333333333333333333333333333",
  tier: 0,
};

const preview = await machine.previewMachineActivation(params);
const result = await machine.activateMachine(params);
console.log("machine", result.machineId.toString(), "owner", result.owner, "controller", result.controller);

from peaq_os_sdk import ActivateMachineParams, ServiceEndpointInput, VerificationMethodInput

params = ActivateMachineParams(
    controller=operator.address,
    verification_methods=(VerificationMethodInput(id="#key-1", method_type="Ed25519VerificationKey2020", controller=operator.address, public_key_multibase="z6Mk..."),),
    authentication=(0,),
    service_endpoints=(ServiceEndpointInput(id="#docs", service_type="Documentation", service_endpoint="https://example.com/docs"),),
    machine_type="Sensor",
    credential_subject=bytes.fromhex("<per-machine-anchor>"),
    manufacturer="0x3333333333333333333333333333333333333333",
    tier=0,
)

preview = machine.preview_machine_activation(params)
result = machine.activate_machine(params)
print("machine", result.machine_id, "owner", result.owner, "controller", result.controller)

Manage from the operator client

From here the operator client (constructed with the same tokenomics20 deployment) runs the fleet. Renewals paid by the operator credit the owner.

const ops = new PeaqosClient<"tokenomics20">({ ...operatorConfig, tokenomics20: { deploymentId: "peaq-mainnet" } });

const state = await ops.getMachineManagementState(result.machineId);
await ops.suspendMachine(result.machineId);
await ops.resumeMachine(result.machineId);

const renewal = await ops.previewMachineRenewal({ machineId: result.machineId, payment: "peaq" });
await ops.renewMachine({ machineId: result.machineId, payment: "peaq", maxNetPeaqAmount: renewal.maxNetPeaqAmount });

await ops.setMachineServiceEndpoints(result.machineId, [
  { id: "#docs", serviceType: "Documentation", serviceEndpoint: "https://example.com/docs/v2" },
]);

from peaq_os_sdk import PreviewMachineRenewalParams, RenewMachineParams

ops = PeaqosClient(..., tokenomics20=Tokenomics20Config(deployment_id="peaq-mainnet"))  # operator key

state = ops.get_machine_management_state(result.machine_id)
ops.suspend_machine(result.machine_id)
ops.resume_machine(result.machine_id)

renewal = ops.preview_machine_renewal(PreviewMachineRenewalParams(result.machine_id, payment="peaq"))
ops.renew_machine(RenewMachineParams(result.machine_id, payment="peaq", max_net_peaq_amount=renewal.max_net_peaq_amount))

ops.set_machine_service_endpoints(result.machine_id, (
    ServiceEndpointInput(id="#docs", service_type="Documentation", service_endpoint="https://example.com/docs/v2"),
))

Batch activation

Activate machines sequentially; each iteration builds a machine client from that machine’s key and records the operator as controller. Persist every returned machine ID: there is no on-chain fleet index in 2.0 yet (the 1.0 machines DID attribute and GET /operator/{did}/machines do not cover 2.0 machines).

import "dotenv/config";
import { PeaqosClient } from "@peaqos/peaq-os-sdk";

const operator = PeaqosClient.fromEnv();
const keys = loadMachineKeys(); // [{ address, privateKey, credentialSubject }], funded with bond + gas
const fleet: { address: string; machineId: string }[] = [];

for (const [i, k] of keys.entries()) {
  const machine = new PeaqosClient<"tokenomics20">({
    rpcUrl: operator.rpcUrl, privateKey: k.privateKey, contracts: operator.contracts,
    tokenomics20: { deploymentId: "peaq-mainnet" },
  });
  const params = {
    controller: operator.address,
    verificationMethods: [{ id: "#key-1", methodType: "Ed25519VerificationKey2020", controller: operator.address, publicKeyMultibase: "z6Mk..." }],
    authentication: [0n],
    serviceEndpoints: [],
    machineType: "Sensor",
    credentialSubject: k.credentialSubject,
    manufacturer: "0x3333333333333333333333333333333333333333",
    tier: 0,
  };
  try {
    const result = await machine.activateMachine(params);
    fleet.push({ address: k.address, machineId: result.machineId.toString() }); // decimal string at the JSON boundary
    console.log(`[${i + 1}/${keys.length}] activated ${k.address} as ${result.machineId}`);
  } catch (err) {
    console.error(`[${i + 1}/${keys.length}] failed for ${k.address}:`, err);
    // A RECEIPT_UNAVAILABLE here means the tx may still mine. Never re-run activation for that machine; check getMachineActivationState.
  }
}
// Persist `fleet` to a file or database. It is your fleet index.

from peaq_os_sdk import ActivateMachineParams, PeaqosClient, Tokenomics20Config, VerificationMethodInput

operator = PeaqosClient.from_env()
keys = load_machine_keys()  # [(address, private_key, credential_subject_bytes)], funded with bond + gas
fleet = []

for i, (address, key, anchor) in enumerate(keys):
    machine = PeaqosClient(
        rpc_url=operator.rpc_url, private_key=key,
        identity_registry=operator.contracts.identity_registry, identity_staking=operator.contracts.identity_staking,
        event_registry=operator.contracts.event_registry, machine_nft=operator.contracts.machine_nft,
        did_registry=operator.contracts.did_registry, batch_precompile=operator.contracts.batch_precompile,
        tokenomics20=Tokenomics20Config(deployment_id="peaq-mainnet"),
    )
    params = ActivateMachineParams(
        controller=operator.address,
        verification_methods=(VerificationMethodInput(id="#key-1", method_type="Ed25519VerificationKey2020", controller=operator.address, public_key_multibase="z6Mk..."),),
        authentication=(0,), service_endpoints=(),
        machine_type="Sensor", credential_subject=anchor,
        manufacturer="0x3333333333333333333333333333333333333333", tier=0,
    )
    try:
        result = machine.activate_machine(params)
        fleet.append({"address": address, "machine_id": str(result.machine_id)})  # decimal string at the JSON boundary
        print(f"[{i + 1}/{len(keys)}] activated {address} as {result.machine_id}")
    except Exception as err:
        print(f"[{i + 1}/{len(keys)}] failed for {address}: {err}")
        # A PENDING_TRANSACTION here means the tx may still mine. Never re-run activation for that machine; reconcile it.
# Persist `fleet` to a file or database. It is your fleet index.

Key management

Approach	How it works	Trade-offs
Per-machine key on the device	The device holds its owner key and signs its own activation and, later, its own transactions.	Strongest isolation. Required if the device should ever transfer its NFT or rotate its controller.
Per-machine key in the operator’s vault	The operator generates and stores one key per machine (HSM, secrets manager) and signs activations from a provisioning host.	The machine still owns its NFT on chain; operationally the operator controls both roles. A vault leak exposes the fleet.

A single shared key for every machine is not possible under 2.0: each machine ID maps to one owner, and a wallet may own many machines, but the machine’s DID controller and owner are what the SDK checks. Use setMachineApprovalForAll / peaqos machine approve-all if a second address must be able to transfer the fleet’s NFTs.

Fleet queries

The 1.0 fleet listing (GET /operator/{did}/machines, built on the proxy’s machines DID attribute) does not know 2.0 machines. Read 2.0 machines by ID from your own index:

for m in fleet:
    state = ops.get_machine_management_state(int(m["machine_id"]))
    print(m["machine_id"], state.subscription.status, state.is_available, state.is_relocating)

Error handling

Error	Cause	Resolution
`TokenomicsUnsupportedError` `SPONSORED_ACTIVATION_UNSUPPORTED`	`registerFor` / `register_for` called in Tokenomics mode	Activate with the machine key and set the operator as `controller`
`TokenomicsActivationError` `INSUFFICIENT_BALANCE`	The machine wallet does not hold the net PEAQ plus gas	Fund the machine wallet, not the operator’s
`TokenomicsActivationError` `NOT_OWNER_OR_CONTROLLER`	Operator tried a management write on a machine that does not list it as controller	Have the owner call `setMachineController`
`TokenomicsActivationError` `NOT_MACHINE_OWNER`	Operator tried `setMachineController`, `transferMachine`, or a clear-controller	Owner-only operations; sign with the machine key
`TokenomicsPendingTransactionError` `PENDING_TRANSACTION` (Python) / `TokenomicsActivationError` `RECEIPT_UNAVAILABLE` (JS)	Receipt did not arrive in time	Never resubmit; reconcile the recorded hash

Full code tables on errors.

Fleets onboarded before Economics 2.0

Machines registered with registerFor / register_for before 2026-09-01 are Tokenomics 1.0 machines owned by the proxy. They keep working on a client constructed without tokenomics20 and through the 1.0 MCR API (GET /operator/{did}/machines). peaq mirrors partner fleets into Economics 2.0 through the MachineMigrationHub; see Economics 2.0: legacy machines.

Welcome

Get Started

Concepts

Functions

Guides

Fleet onboarding (operator-controlled)

Rights in the machine-owned, operator-controlled model

Prerequisites

From the terminal

Single machine, from code

Batch activation

Key management

Fleet queries

Error handling

Fleets onboarded before Economics 2.0

​Rights in the machine-owned, operator-controlled model

​Prerequisites

​From the terminal

​Single machine, from code

​Batch activation

​Key management

​Fleet queries

​Error handling

​Fleets onboarded before Economics 2.0

Rights in the machine-owned, operator-controlled model

Prerequisites

From the terminal

Single machine, from code

Batch activation

Key management

Fleet queries

Error handling

Fleets onboarded before Economics 2.0