Quickstart

Activate your first machine in five minutes.

Install the SDK or the CLI, pick a deployment, activate a machine 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.

1. Install

   CLI

   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.10 or newer. On macOS with the python.org installer, run Install Certificates.command from the Python folder first: without it peaqos init cannot download the contract addresses, leaves IDENTITY_REGISTRY_ADDRESS and the other Tokenomics 1.0 addresses empty, and peaqos whoami fails. Full reference on the peaqOS CLI page.

   npm

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

   Needs Node.js 22 or newer. Economics 2.0 activation on peaq-mainnet needs the current @peaqos/peaq-os-sdk release.

   pip

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

   Needs Python 3.10 or newer; use the current release for peaq-mainnet.

   Agent skill

   pip install -U 'peaq-os-cli[ows,solana]'
   npx skills add peaqnetwork/peaq-os-skills
   

   The skill drives the current CLI release. Needs Python 3.10 or newer. Auto-detects Claude Code, Cursor, or Windsurf. See the peaqOS AI page.

   ROS 2

   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. These services drive the Tokenomics 1.0 register flow. Full reference on SDK: ROS 2.

   Use the current releases of the CLI, @peaqos/peaq-os-sdk and peaq-os-sdk for peaq-mainnet. Older releases fail peaq-mainnet activation with READ_FAILED (CLI: RPC_FAILED), PEER_MISMATCH or DEPLOYMENT_UNAVAILABLE. To home a machine on Solana, see Onboard on Solana. Full install reference on the install page.

2. Configure

   Create a .env file (or let peaqos init write it). On peaq mainnet peaqos init (CLI 0.0.13 or newer) fills EVENT_REGISTRY_ADDRESS with the Economics 2.0 registry 0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e. CLI 0.0.12 and older fill the Tokenomics 1.0 registry 0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA instead: upgrade with pip install -U peaq-os-cli, or export EVENT_REGISTRY_ADDRESS=0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e before peaqos init (an exported value takes precedence over the default) or edit .env afterwards.

   # 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
   
   # MCR reads come from the deployment record (https://mcr.peaq.xyz for peaq-mainnet).
   # With TOKENOMICS_DEPLOYMENT_ID set the MCR commands do not read PEAQOS_MCR_API_URL; `peaqos whoami` still prints it.
   

   The wallet behind PEAQOS_PRIVATE_KEY becomes the machine’s owner and pays the bond plus gas. The bond is quoted per tier at the oracle rate and the PEAQ figure moves with the daily oracle price, so preview before you fund. See Economics 2.0. Full variable list on the environment variables table.

3. Activate

   CLI

   # Replace 0xYourAddress with your wallet address and z6Mk... with the machine's
   # Ed25519 public key (multibase).
   cat > did.json <<'JSON'
   {
     "verificationMethods": [
       { "id": "#key-1", "methodType": "Ed25519VerificationKey2020",
         "controller": "0xYourAddress", "publicKeyMultibase": "z6Mk..." }
     ],
     "authentication": [0],
     "serviceEndpoints": [
       { "id": "#docs", "serviceType": "peaq-documentation", "serviceEndpoint": "https://example.com/docs" }
     ]
   }
   JSON
   
   # Preview the bond and the net PEAQ. Submits nothing. On an unfunded wallet it
   # prints the quote, then stops with INSUFFICIENT_PEAQ (exit 2).
   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 activation, after a PEAQ approval
   # transaction if one is needed.
   

   JavaScript

   import "dotenv/config";
   import { PeaqosClient, type ActivateMachineParams, type Tokenomics20DeploymentId } 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: process.env.TOKENOMICS_DEPLOYMENT_ID as Tokenomics20DeploymentId },
   });
   
   const params: ActivateMachineParams = {
     controller: client.address,
     verificationMethods: [{ id: "#key-1", methodType: "Ed25519VerificationKey2020", controller: client.address, publicKeyMultibase: "z6Mk..." }],
     authentication: [0n],
     serviceEndpoints: [{ id: "#docs", serviceType: "peaq-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());
   

   Save it as activate.mts (top-level await needs an ES module) and run npx tsx activate.mts.

   Python

   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=os.environ["TOKENOMICS_DEPLOYMENT_ID"]),
   )
   
   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="peaq-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)
   

   Replace Sensor, 0xdeadbeef and the z6Mk... key with your machine’s own values before you submit. The machine type and credential subject fix the machine ID for good: everyone who copies the sample values gets the same ID, and only the first activation succeeds. Nothing checks the key value, so a placeholder is stored as given.

   For the full terminal walkthrough, wallets and costs included, follow the onboarding quickstart. 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 machine ID is uint256(keccak256(abi.encode(machineType, credentialSubject))). 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 Economics 2.0 shipped live on the Tokenomics 1.0 contracts. The SDKs keep that path when you construct a client without tokenomics20. There is no public MCR API for Tokenomics 1.0 machines. See Activate: legacy flow.

Next

Onboarding quickstart

From a blank terminal to an activated machine on peaq, with the CLI.

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. Paused: Machine Market registration does not work today for Tokenomics 1.0 or Economics 2.0 machines.