Install

Pick the that matches your stack. Both paths converge on the same state.

Requirements

Requirement	Value
Node.js	≥ 22
TypeScript	≥ 5 (for the JS SDK)
Python	≥ 3.10 (for the Python SDK)
Peer dependency	`viem >= 2.47.10` (JS only; Python pulls `web3 >= 6.0` automatically)
RPC access	peaq mainnet or agung testnet
Gas	Handled by Gas Station on fresh wallets; needs 2FA for request

Install paths

Agent skill
CLI
JavaScript
Python
ROS 2

Two pieces

# 1. Install the CLI (the skill drives it under the hood); include the [ows] extra
#    so `peaqos wallet ...` works inside the skill's onboarding flow.
pip install 'peaq-os-cli[ows]'

# 2. Add the peaqos skill to your agent (auto-detects Claude Code, Cursor, or Windsurf)
npx skills add peaqnetwork/peaq-os-skills

Then invoke /peaqos in any Claude Code session. To target a specific runtime explicitly, add --agent claude-code | cursor | windsurf. See the peaqOS AI page for details and the manual upload path for ChatGPT / custom GPTs.

Works with

The peaqos skill ships first-class adapters for Claude Code, Cursor, and Windsurf — auto-detected, or selected with --agent. Hosted assistants without a local CLI (ChatGPT, Claude Projects, custom GPTs) can load AGENT-PROMPT.md as a system prompt manually.The skill calls the JavaScript and Python SDKs through the CLI. Tabs below apply once you start editing code yourself.

One command

pip install peaq-os-cli

# Optional: include OWS wallet commands (peaqos wallet create / import / list / …)
pip install 'peaq-os-cli[ows]'

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 peaq mainnet contracts table on this page. A known bug in the init wizard can silently write a contract address to the wrong variable name. If any address is missing or wrong, correct it manually before running peaqos activate.

Drives the same flows as the SDKs from your terminal: peaqos init, peaqos whoami, peaqos activate, peaqos qualify event, peaqos qualify mcr, peaqos show machine, peaqos show operator machines, peaqos wallet. See peaqOS CLI for the full command reference. CLI and SDK wallet helpers live on Wallets (OWS).

Package

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

OWS wallet helpers (createWallet, importWallet, PeaqosClient.fromWallet, …) work out of the box; @open-wallet-standard/core is bundled as a regular dependency of @peaqos/peaq-os-sdk. See Wallets (OWS) for the full surface.dotenv is optional but recommended: PeaqosClient.fromEnv() reads from process.env, so import "dotenv/config" at the top of your entry file is the simplest way to load .env.

Language + runtime

Node.js ≥ 22
TypeScript ≥ 5
Package exports both ESM and CJS builds; no bundler workarounds required.

Imports

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

Full method reference on SDK JS. Error class hierarchy on errors.

Package

python3 -m venv .peaq-os
source .peaq-os/bin/activate

pip install "peaq-os-sdk>=0.4.0" python-dotenv

# Optional: include the OWS wallet helpers (createWallet, importWallet, …)
pip install "peaq-os-sdk[ows]>=0.4.0"

python-dotenv is optional but recommended: PeaqosClient.from_env() reads from dotenv, so load_dotenv() at the top of your entry file is the simplest way to load .env.

Language + runtime

Python ≥ 3.10
web3.py pulled in automatically.
Virtualenv strongly recommended. The commands above set one up.

Imports

from peaq_os_sdk import PeaqosClient

Full method reference on SDK Python. Error class hierarchy on errors.

Workspace

git clone https://github.com/peaqnetwork/peaq-robotics-ros2.git
cd peaq-robotics-ros2

Build

source /opt/ros/jazzy/setup.bash
# Docker image: source /opt/ros/humble/setup.bash
# Native host only: python3 -m pip install -r requirements.txt

colcon build --packages-select peaq_ros2_interfaces peaq_ros2_peaqos peaq_ros2_examples
source install/setup.bash

Run

cp peaq_ros2_examples/config/peaq_robot.example.yaml peaq_ros2_examples/config/peaq_robot.yaml
# Edit peaq_ros2_examples/config/peaq_robot.yaml and set peaq_os.enabled: true.

ros2 run peaq_ros2_peaqos peaqos_node --ros-args \
  -p config.yaml_path:=peaq_ros2_examples/config/peaq_robot.yaml

Full method mapping on ROS 2 SDK reference. End-to-end commands on ROS 2 machine runtime.

Environment variables

Variable	Required	Default	Purpose
`PEAQOS_RPC_URL`	Yes	n/a	peaq chain RPC endpoint
`PEAQOS_PRIVATE_KEY`	Yes	n/a	Owner wallet private key (hex, `0x...`)
`PEAQOS_NETWORK`	CLI only	n/a	`mainnet` or `testnet`. Selects address + URL defaults for the CLI’s `peaqos init`. SDK clients ignore it.
`PEAQOS_GAS_STATION_URL`	CLI only	n/a	Faucet base URL. Set to `https://depinstation.peaq.network` for the public peaq-hosted Gas Station. Required for the `peaqos activate` funding step unless `--skip-funding` is set or the wallet already meets the gas threshold.
`OWS_PASSPHRASE`	No	n/a	OWS vault passphrase used by the SDK and CLI wallet helpers (`createWallet`, `importWallet`, `exportWallet`, …). The SDK raises `PeaqosError` if neither this nor the inline `passphrase` arg is set (no interactive prompt). The CLI reads it when `PEAQOS_OWS_WALLET` is set, prompting interactively if unset. See Wallets (OWS).
`IDENTITY_REGISTRY_ADDRESS`	Yes	n/a	Identity Registry contract. See peaq mainnet contracts for the canonical address.
`IDENTITY_STAKING_ADDRESS`	Yes	n/a	Identity Staking contract
`EVENT_REGISTRY_ADDRESS`	Yes	n/a	Event Registry contract
`MACHINE_NFT_ADDRESS`	Yes	n/a	Machine NFT (ONFT) contract
`DID_REGISTRY_ADDRESS`	Yes	n/a	DID Registry precompile address (`0x...0800` on every peaq runtime)
`BATCH_PRECOMPILE_ADDRESS`	Yes	n/a	Batch precompile for multi-call bonding (`0x...0805` on every peaq runtime)
`MACHINE_ACCOUNT_FACTORY_ADDRESS`	No	n/a	`MachineAccountFactory`. Required only for smart-account deploy / predict.
`MACHINE_NFT_ADAPTER_ADDRESS`	No	n/a	`MachineNFTAdapter` (LayerZero ONFT adapter). Required only for `bridge_nft` / `bridgeNft` when `source="peaq"`.
`PEAQOS_OWS_WALLET`	CLI only	n/a	Active OWS vault wallet name. When set, the CLI loads the wallet via `OWS_PASSPHRASE` and skips `PEAQOS_PRIVATE_KEY`. Set by `peaqos wallet use` or `peaqos init` (`wallet` path).
`PEAQOS_MCR_API_URL`	Set for mainnet	`http://127.0.0.1:8000`	MCR API base URL. The default is for self-hosted dev. Set to `https://mcr.peaq.xyz` to read from the public peaq-hosted MCR.
`PEAQOS_ORCHESTRATION_URL`	Scale only	n/a	Machine Markets orchestrator base URL. The canonical peaq-managed endpoint is `https://orchestration.peaq.xyz`. Read by the SDK (`client.orchestration`) and CLI (`peaqos scale ...`).
`PEAQOS_API_KEY`	SDK, optional	n/a	Platform API key sent as `x-api-key` on `client.orchestration` requests. Required only when the orchestrator runs with `PEAQOS_REQUIRE_API_AUTH=true`.
`PEAQOS_ORCH_API_KEY`	CLI, optional	n/a	Same platform API key as `PEAQOS_API_KEY` but under the CLI-specific name. `peaqos init` writes this; `peaqos scale ...` reads it. Set both names to the same value if you use the CLI and SDK in the same env.
`PEAQOS_TELEMETRY`	No	on	Anonymous SDK usage telemetry toggle. Set to `0` to disable. SDK only (JS + Python); the CLI sends none. See Telemetry.
`DO_NOT_TRACK`	No	n/a	Cross-vendor opt-out convention: set to `1` to disable SDK telemetry (same effect as `PEAQOS_TELEMETRY=0`).

Full reference with defaults on SDK JS environment and SDK Python environment.

Telemetry

The JavaScript and Python SDKs emit anonymous usage telemetry — which SDK operations run, tagged with a random install ID and with IP collection off (via PostHog, EU-hosted) — to help prioritize the roadmap. No private keys, wallet secrets, or machine data are sent. Telemetry is on by default; disable it with PEAQOS_TELEMETRY=0 or the cross-vendor DO_NOT_TRACK=1. The CLI sends none.

Public RPC endpoints

Use any of the below for PEAQOS_RPC_URL. QuickNode is the primary set; OnFinality and PublicNode are fallbacks. All of them accept JSON-RPC calls. For private dedicated endpoints, see the QuickNode and OnFinality guides. Full list on Connecting to peaq.

https://quicknode1.peaq.xyz
https://quicknode2.peaq.xyz
https://quicknode3.peaq.xyz

# Secondary / fallback
https://peaq.api.onfinality.io/public
https://peaq-rpc.publicnode.com

https://peaq-agung.api.onfinality.io/public
https://wss-async-agung.peaq.xyz

peaq mainnet contracts

Core are UUPS upgradeable proxies; treat the addresses as the current proxy pointers. For the architecture diagram and what each contract is responsible for, see Smart contracts.

Required

Variable	Address
`IDENTITY_REGISTRY_ADDRESS`	`0xb53Af985765031936311273599389b5B68aC9956`
`IDENTITY_STAKING_ADDRESS`	`0x11c05A650704136786253e8685f56879A202b1C7`
`EVENT_REGISTRY_ADDRESS`	`0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA`
`MACHINE_NFT_ADDRESS`	`0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9`
`DID_REGISTRY_ADDRESS`	`0x0000000000000000000000000000000000000800` (peaq DID precompile)
`BATCH_PRECOMPILE_ADDRESS`	`0x0000000000000000000000000000000000000805` (peaq batch precompile)

Optional

Set only if you use the corresponding SDK method.

Variable	Address	Needed for
`MACHINE_ACCOUNT_FACTORY_ADDRESS`	`0x4A808d5A90A2c91739E92C70aF19924e0B3D527f`	`deploySmartAccount` / `getSmartAccountAddress` (ERC-4337)
`MACHINE_NFT_ADAPTER_ADDRESS`	`0x9AD5408702EC204441A88589B99ADfC2514AFAE6`	`bridgeNft` / `bridge_nft` when `source="peaq"` (LayerZero V2 ONFT)

Base mainnet contracts

Needed when into peaq from . Pass baseNftAddress / base_nft_address to the bridge method.

Contract	Address
`MachineNFTBase` (LayerZero ONFT)	`0xee8A521eA434b11F956E2402beC5eBfa753Babfa`

Agung testnet contracts

Use these to point the SDK or CLI at . addresses are identical to mainnet (same fixed slots on every peaq runtime).

Required

Variable	Address
`IDENTITY_REGISTRY_ADDRESS`	`0x9E9463a65c7B74623b3b6Cdc39F71be7274e5971`
`IDENTITY_STAKING_ADDRESS`	`0x55f336714aDb0749DbFE33b057a1702405564E3d`
`EVENT_REGISTRY_ADDRESS`	`0x2DAD8905380993940e340C5cE6d313d5c2780040`
`MACHINE_NFT_ADDRESS`	`0xB41C2A4f1c19b6B06beaAce0F5CD8439e77C4b1c`
`DID_REGISTRY_ADDRESS`	`0x0000000000000000000000000000000000000800` (peaq DID precompile)
`BATCH_PRECOMPILE_ADDRESS`	`0x0000000000000000000000000000000000000805` (peaq batch precompile)

Optional

Variable	Address	Needed for
`MACHINE_ACCOUNT_FACTORY_ADDRESS`	`0x65a4DfEB799dFf8CF15f13816d648a7805d6b1F9`	`deploySmartAccount` / `getSmartAccountAddress` (ERC-4337)
`MACHINE_NFT_ADAPTER_ADDRESS`	`0x63fD7e64A38e50D1486Bc569B4CaCeD38528De22`	`bridgeNft` / `bridge_nft` when `source="peaq"` (LayerZero V2 ONFT)
`ADMIN_FLAGS_ADDRESS`	`0x4181a2Aa34aFb247450FfcBd65be5aBD4Cbee658`	MCR API server (negative-flag + trust-override reads)

Bridging cannot be exercised on agung. MachineNFTAdapter is deployed, but LayerZero V2 has no DVN routes between agung and Base. bridgeNft / bridge_nft calls will not relay end-to-end. Test the bridge on peaq mainnet ↔ Base mainnet only.

Troubleshooting

INVALID_2FA: OTP code rejected

The OTP from your authenticator app was wrong or expired. Generate a fresh code and retry. See full error code reference.

2FA_LOCKED: too many invalid attempts

The faucet throttles owners after repeated bad OTPs. Wait out the lockout window and retry. See error code reference.

RATE_LIMITED: faucet rate limit reached

The faucet enforces a per-IP and per-wallet cap. Retry after the cooldown. See error code reference.

CAP_EXCEEDED_OWNER: daily owner cap reached

The same owner address has hit the daily funding cap. Wait 24 hours or contact support. See error code reference.

Missing PEAQOS_RPC_URL

Set PEAQOS_RPC_URL in your environment to a valid peaq chain RPC endpoint (e.g., https://peaq.api.onfinality.io/public). Without it, PeaqosClient.fromEnv() raises a ValidationError. See Public RPC endpoints for the full list. Full error taxonomy on errors.

Welcome

Get Started

Concepts

Functions

Guides

Requirements

Install paths

Two pieces

Works with

One command

Package

Language + runtime

Imports

Package

Language + runtime

Imports

Workspace

Build

Run

Environment variables

Telemetry

Public RPC endpoints

peaq mainnet contracts

Required

Optional

Base mainnet contracts

Agung testnet contracts

Required

Optional

Troubleshooting

​Requirements

​Install paths

​Two pieces

​Works with

​One command

​Package

​Language + runtime

​Imports

​Package

​Language + runtime

​Imports

​Workspace

​Build

​Run

​Environment variables

​Telemetry

​Public RPC endpoints

​peaq mainnet contracts

​Required

​Optional

​Base mainnet contracts

​Agung testnet contracts

​Required

​Optional

​Troubleshooting

Requirements

Install paths

Two pieces

Works with

One command

Package

Language + runtime

Imports

Package

Language + runtime

Imports

Workspace

Build

Run

Environment variables

Telemetry

Public RPC endpoints

peaq mainnet contracts

Required

Optional

Base mainnet contracts

Agung testnet contracts

Required

Optional

Troubleshooting