Quickstart - peaq

Install the , generate a , .

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

Agent skill
CLI
npm
pip
ROS 2

pip install peaq-os-cli
npx skills add peaqnetwork/peaq-os-skills

Auto-detects Claude Code, Cursor, or Windsurf. Invoke /peaqos in Claude Code and it drives the whole flow below. To target a specific runtime, add --agent claude-code | cursor | windsurf — see the peaqOS AI page.

pip install peaq-os-cli
peaqos init && peaqos activate --doc-url "https://example.com/docs" --data-api "https://example.com/events"

After running peaqos init, open your .env and verify every contract address against the mainnet contracts table. A known bug in the init wizard can silently write an address to the wrong variable name — correct any mismatches before running peaqos activate.

Wraps the SDK into terminal commands. Full reference on the peaqOS CLI page.

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

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

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. Full reference on SDK: ROS 2.

Full install reference on the install page.

Configure

Create a .env file:

# 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...

# 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.network

# Mainnet contracts auto-populated by fromEnv(); shown here for reference. Override only for custom deploys.
# For agung testnet addresses see /peaqos/install#agung-testnet-contracts.
IDENTITY_REGISTRY_ADDRESS=0xb53Af985765031936311273599389b5B68aC9956
IDENTITY_STAKING_ADDRESS=0x11c05A650704136786253e8685f56879A202b1C7
EVENT_REGISTRY_ADDRESS=0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA
MACHINE_NFT_ADDRESS=0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9
DID_REGISTRY_ADDRESS=0x0000000000000000000000000000000000000800
BATCH_PRECOMPILE_ADDRESS=0x0000000000000000000000000000000000000805

# Optional. Defaults to http://127.0.0.1:8000
PEAQOS_MCR_API_URL=https://mcr.peaq.xyz

(identity, staking, event, NFT, DID, batch) populate automatically with PeaqosClient.fromEnv(), so you don’t need to set them manually. See the environment variables table for the full list and the public RPC endpoints section for QuickNode primary plus OnFinality/PublicNode fallbacks.

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

const client = PeaqosClient.fromEnv();

// Register the client's own wallet as a new machine.
// The call sends the minimum bond (1 PEAQ) with the transaction.
const machineId = await client.registerMachine();

console.log("Registered machine ID:", machineId);

register machines on behalf of another . See the self-managed and proxy operator guides for the fleet flow with registerFor.

What just happened

PeaqosClient.fromEnv() bound the from PEAQOS_PRIVATE_KEY and loaded contract addresses from the environment.
registerMachine sent 1 as msg.value (the ), registered the identity in IdentityRegistry, and returned the newly assigned .
The machine ID is the handle for every downstream call: the (mintNft), writing , submitting , and queries.

Self-managed onboarding

Owner = operator. One machine, one wallet.

Proxy operator fleet

One owner, many machines, registerFor.

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.

​Next

Self-managed onboarding

Proxy operator fleet

Scale: pair an agent, buy services

Next