Quickstart

Install the or the CLI, pick a deployment, in one transaction.

New to web3? Terms with a dotted underline have a plain-English definition on hover or tap. The full list lives in the glossary.

Install

CLI
npm
pip
Agent skill
ROS 2

pip install peaq-os-cli
peaqos init

peaqos init writes a .env with your key, RPC, and TOKENOMICS_DEPLOYMENT_ID (peaq-mainnet or agung-2026-08-28). Needs Python 3.12 or newer. Full reference on the peaqOS CLI page.

npm install @peaqos/peaq-os-sdk viem dotenv

Economics 2.0 activation needs @peaqos/peaq-os-sdk 0.7.0 or newer (2026-09-11; older releases fail preflight with PEER_MISMATCH since the 2026-09-08 adapter re-point).

python3 -m venv .peaq-os
source .peaq-os/bin/activate
pip install "peaq-os-sdk>=0.7.1" python-dotenv

Needs Python 3.10 or newer. 0.7.1 (2026-09-11) is the minimum: older releases fail preflight with PEER_MISMATCH since the 2026-09-08 adapter re-point.

pip install 'peaq-os-cli[ows]<0.0.8' 'peaq-os-sdk<0.6.0'
npx skills add peaqnetwork/peaq-os-skills

The peaqos skill was last aligned with CLI 0.0.6 and still drives the Tokenomics 1.0 flags, so pin the CLI below 0.0.8 until the skill updates. Pin the SDK below 0.6.0 as well: the CLI pin alone resolves to CLI 0.0.7 with SDK 0.7.0, which breaks peaqos monetize. This pair needs Python 3.11 or newer. Auto-detects Claude Code, Cursor, or Windsurf. See the peaqOS AI page.

git clone https://github.com/peaqnetwork/peaq-robotics-ros2.git
cd peaq-robotics-ros2
source /opt/ros/jazzy/setup.bash
colcon build --packages-select \
  peaq_ros2_interfaces peaq_ros2_peaqos peaq_ros2_examples
source install/setup.bash

Wraps the SDKs as ROS 2 services. The ROS 2 services still drive the Tokenomics 1.0 register flow. Full reference on SDK: ROS 2.

Full install reference on the install page.

Configure

Create a .env file (or let peaqos init write it):

# peaq mainnet RPC. See /peaqos/install#public-rpc-endpoints for alternatives.
PEAQOS_NETWORK=mainnet
PEAQOS_RPC_URL=https://peaq.api.onfinality.io/public
PEAQOS_PRIVATE_KEY=0x...

# Economics 2.0 deployment. Selects the contract set; the addresses ship inside the SDK.
# Use agung-2026-08-28 for the testnet.
TOKENOMICS_DEPLOYMENT_ID=peaq-mainnet

# Required for the `peaqos activate` funding step; omit and use --skip-funding if you have your own gas.
PEAQOS_GAS_STATION_URL=https://depinstation.peaq.xyz

# Tokenomics 1.0 contracts. The SDK constructor still requires all six; activation does not read them.
# For agung testnet addresses see /peaqos/install#agung-testnet-contracts.
IDENTITY_REGISTRY_ADDRESS=0xb53Af985765031936311273599389b5B68aC9956
IDENTITY_STAKING_ADDRESS=0x11c05A650704136786253e8685f56879A202b1C7
EVENT_REGISTRY_ADDRESS=0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e   # Economics 2.0 EventRegistry; Tokenomics 1.0 machines use 0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA
MACHINE_NFT_ADDRESS=0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9
DID_REGISTRY_ADDRESS=0x0000000000000000000000000000000000000800
BATCH_PRECOMPILE_ADDRESS=0x0000000000000000000000000000000000000805

# Optional. Tokenomics 1.0 MCR API, read by `peaqos qualify` and `peaqos show`.
PEAQOS_MCR_API_URL=https://mcr.peaq.xyz

The wallet behind PEAQOS_PRIVATE_KEY becomes the machine’s owner and pays the plus . The bond is quoted per tier at the oracle rate; on 2026-09-04 at 20:20 UTC the Entry tier quoted 0.803 PEAQ on mainnet; the figure moves with the daily oracle price. See Economics 2.0. Full variable list on the environment variables table.

Activate

CLI
JavaScript
Python

cat > did.json <<'JSON'
{
  "verificationMethods": [
    { "id": "#key-1", "methodType": "Ed25519VerificationKey2020",
      "controller": "0xYourAddress", "publicKeyMultibase": "z6Mk..." }
  ],
  "authentication": [0],
  "serviceEndpoints": [
    { "id": "#docs", "serviceType": "Documentation", "serviceEndpoint": "https://example.com/docs" }
  ]
}
JSON

# Preview the bond and the net PEAQ. Submits nothing.
peaqos activate --machine-type Sensor --credential-subject-hex 0xdeadbeef \
  --manufacturer 0x3333333333333333333333333333333333333333 --tier entry \
  --did-document ./did.json --dry-run

# Same command without --dry-run submits the one transaction.

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

const legacy = PeaqosClient.fromEnv();
const client = new PeaqosClient<"tokenomics20">({
  rpcUrl: legacy.rpcUrl,
  privateKey: process.env.PEAQOS_PRIVATE_KEY!,
  contracts: legacy.contracts,
  tokenomics20: { deploymentId: "peaq-mainnet" },
});

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

const preview = await client.previewMachineActivation(params);
console.log("Will pay", preview.netPeaqAmount, "wei of PEAQ for machine", preview.machineId);

const result = await client.activateMachine(params);
console.log("Activated machine ID:", result.machineId.toString());

import os
from dotenv import load_dotenv
from peaq_os_sdk import (
    ActivateMachineParams, PeaqosClient, ServiceEndpointInput,
    Tokenomics20Config, VerificationMethodInput,
)

load_dotenv()
legacy = PeaqosClient.from_env()
client = PeaqosClient(
    rpc_url=legacy.rpc_url,
    private_key=os.environ["PEAQOS_PRIVATE_KEY"],
    identity_registry=legacy.contracts.identity_registry,
    identity_staking=legacy.contracts.identity_staking,
    event_registry=legacy.contracts.event_registry,
    machine_nft=legacy.contracts.machine_nft,
    did_registry=legacy.contracts.did_registry,
    batch_precompile=legacy.contracts.batch_precompile,
    tokenomics20=Tokenomics20Config(deployment_id="peaq-mainnet"),
)

params = ActivateMachineParams(
    controller=client.address,
    verification_methods=(VerificationMethodInput(id="#key-1", method_type="Ed25519VerificationKey2020", controller=client.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("deadbeef"),
    manufacturer="0x3333333333333333333333333333333333333333",
    tier=0,
)

preview = client.preview_machine_activation(params)
print("Will pay", preview.net_peaq_amount, "wei of PEAQ for machine", preview.machine_id)

result = client.activate_machine(params)
print("Activated machine ID:", result.machine_id)

Fleets activate each machine with the machine’s own key and record the operator as DID controller. See the self-managed and fleet guides.

What just happened

The client resolved the Economics 2.0 contract addresses from the peaq-mainnet deployment record and verified them against InfoDesk.peer(role) on chain.
activateMachine sent one transaction that minted the machine’s ERC-721 in MachineRegistry, stored the DID document, bonded PEAQ on the Entry tier in MachineSubscription, and recorded peaq as the home chain.
The is keccak256(machineType, credentialSubject) as a uint256. It is also the NFT token ID and the DID is did:peaq:<that id>. It is the handle for every later call: peaqos machine status, renewals, transfers, DID updates.
The SDK only returned after the receipt carried MachineOnboarded, MachineMinted, and Activated and the on-chain state matched what you asked for.
The machine shows up on the Machine Explorer at machines.peaq.xyz/machine/<decimal machine id> once the indexer has picked up the block.

Machines onboarded before Economics 2.0

Machines registered through registerMachine / register_machine before 2026-09-01 live on the Tokenomics 1.0 contracts. The SDKs keep that path when you construct a client without tokenomics20; the 1.0 MCR API at mcr.peaq.xyz serves them. See Activate: legacy flow.

Self-managed onboarding

Owner = operator. One machine, one wallet, funded through the Gas Station.

Fleet onboarding

Many machines, each owning its NFT, one operator as controller.

Scale: pair an agent, buy services

Pair an AI agent to your machine and let it discover and consume services through the Machine Markets API.

Welcome

Get Started

Concepts

Functions

Guides

Next

Self-managed onboarding

Fleet onboarding

Scale: pair an agent, buy services

​Next

Self-managed onboarding

Fleet onboarding

Scale: pair an agent, buy services

Next