Install

Install peaqOS via npm or pip.

Pick the SDK that matches your stack. The JS SDK, Python SDK and CLI reach the same onchain state; the ROS 2 node covers Tokenomics 1.0 machines only.

Requirements

Requirement	Value
Node.js	≥ 22
TypeScript	≥ 5 (for the JS SDK)
Python	≥ 3.10 for the Python SDK and the CLI
Peer dependency	viem ^2.54.2 (JS only; Python pulls web3 >= 6.0 automatically)
RPC access	peaq mainnet or agung testnet
Solana home (optional)	JS peer dependencies @solana/web3.js and @coral-xyz/anchor (onboarding, reads, management and events), Python extra peaq-os-sdk[solana], a Solana mainnet-beta RPC in PEAQOS_SVM_RPC_URL. Onboarding a machine on Solana needs CLI 0.0.17 (which needs click 8.4 or newer; pip install -U installs it), Python SDK 0.11.2 or JS SDK 0.11.2, or newer. Needed only for machines homed on Solana, see Onboard a machine on Solana
Gas	Handled by Gas Station on fresh wallets; needs 2FA for request

Install paths

Agent skill

Two pieces

# 1. Install the CLI (the skill drives it under the hood); the [ows] extra
#    gives the skill's onboarding flow `peaqos wallet ...`. Python 3.10 or newer.
pip install -U 'peaq-os-cli[ows,solana]'

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

Works with

The peaqos skill ships adapters for Claude Code, Cursor, and Windsurf, auto-detected or selected with --agent. Other agent frameworks load AGENT-PROMPT.md as their system prompt instead. The agent still needs to run shell commands, because every flow runs through the peaqos CLI; a hosted chat assistant without a shell cannot drive it.

The skill drives the Python SDK through the CLI. The tabs below apply once you start editing code yourself.

CLI

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
# write did.json first: the three-field DID document, schema on the CLI page (/peaqos/cli#did-document-schema)
peaqos activate --machine-type Sensor --credential-subject-hex 0xdeadbeef \
  --manufacturer 0x3333333333333333333333333333333333333333 --tier entry \
  --did-document ./did.json --dry-run     # preview; drop --dry-run to fund from the Gas Station and submit

--dry-run skips the Gas Station funding step, so on a wallet that cannot yet cover the net PEAQ plus 0.05 PEAQ of gas it exits 2 with INSUFFICIENT_PEAQ. Drop --dry-run to let the CLI fund the wallet first.

Needs Python 3.10 or newer. peaqos init writes TOKENOMICS_DEPLOYMENT_ID (peaq-mainnet or agung-2026-08-28); peaqos activate, peaqos machine, and peaqos monetize all require it. The Economics 2.0 contract addresses are not in .env: they ship inside the SDK’s deployment record. peaqos activate --chain solana (pip install -U 'peaq-os-cli[solana,ows]') is the seven-stage flow, one command, for a machine homed on Solana (CLI 0.0.19 or newer): Onboard a machine on Solana. Step by step, wallets and funding included: onboarding quickstart.

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. An event for a 2.0 machine sent to the 1.0 registry reverts with MachineNotFound.

On agung peaqos init prefills only TOKENOMICS_DEPLOYMENT_ID=agung-2026-08-28 and the DID and batch precompile addresses: it leaves the RPC, MCR and Gas Station URLs and the IdentityRegistry, IdentityStaking and MachineNFT addresses empty, the Event Registry prompt insists on a value, and --non-interactive exits 3 unless EVENT_REGISTRY_ADDRESS is set. The SDK constructor requires the Tokenomics 1.0 addresses even though activation does not read them.

Drives the same flows as the SDKs from your terminal: peaqos init, peaqos whoami, peaqos activate, peaqos machine (status, suspend, resume, subscription, transfer, DID updates), peaqos monetize, peaqos qualify event, peaqos verify, peaqos wallet, peaqos stream, peaqos scale. With TOKENOMICS_DEPLOYMENT_ID set, peaqos qualify mcr and peaqos show machine read machines by decimal DID from mcr.peaq.xyz, and peaqos show operator machines takes the operator’s address DID. There is no public MCR API for Tokenomics 1.0 machines. agung-2026-08-28 has no paired 2.0 MCR, so with that deployment ID qualify mcr, show machine, show operator machines and monetize status exit 3 with CONFIG_ERROR. See peaqOS CLI for the full command reference. CLI and SDK wallet helpers live on Wallets (OWS).

JavaScript

Package

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

# Optional, only for machines homed on Solana:
npm install @solana/web3.js @coral-xyz/anchor

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.

Python

Package

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

pip install -U "peaq-os-sdk" python-dotenv

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

# Optional, only for machines homed on Solana:
pip install -U "peaq-os-sdk[solana,ows]"

python-dotenv is optional but recommended: PeaqosClient.from_env() reads os.environ and does not load .env itself, so load_dotenv() at the top of your entry file is the simplest way to load it.

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.

ROS 2

The ROS 2 node drives Tokenomics 1.0 machines only: its services take a uint64 machine ID and have no Economics 2.0 activation. For 2.0 machines use the CLI or an SDK.

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: install requirements.txt into a venv created with --system-site-packages (see ROS 2 installation)

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: set peaq_os.enabled: true,
# peaq_os.faucet.base_url: https://depinstation.peaq.xyz, and
# peaq_os.contracts.event_registry: 0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA
# (the example file ships an older faucet host and EventRegistry address).

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 for fromEnv() / from_env(); the CLI skips it when PEAQOS_OWS_WALLET is set	n/a	Owner wallet private key (hex, 0x...)
PEAQOS_NETWORK	CLI only	n/a	mainnet (alias peaq) or testnet (alias agung). Selects the address and URL defaults for peaqos init --non-interactive; the interactive wizard asks for the network itself. peaqos whoami prints it. SDK clients ignore it.
PEAQOS_GAS_STATION_URL	CLI only	n/a	Faucet base URL. Set to https://depinstation.peaq.xyz 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.
TOKENOMICS_DEPLOYMENT_ID	CLI only	n/a	Economics 2.0 deployment record: peaq-mainnet or agung-2026-08-28. Written by peaqos init. Required by peaqos activate, peaqos machine, peaqos monetize, and peaqos monetize provision run. fromEnv() / from_env() read it too; the explicit constructor form is tokenomics20: { deploymentId } (JS) or tokenomics20=Tokenomics20Config(deployment_id=...) (Python). Contract addresses travel with the record; they are never environment variables.
PEAQOS_SVM_NETWORK	CLI, Solana only	n/a	Solana cluster for machines homed on Solana: mainnet-beta. Overridden by the root flag --svm-network. Selecting a cluster never selects a machine’s home; peaqos activate --chain solana does.
PEAQOS_SVM_RPC_URL	CLI, Solana only	n/a	Solana JSON-RPC endpoint, separate from PEAQOS_RPC_URL (peaq). Needed by every command that reaches a Solana-homed machine, not only onboarding: qualify event and machine … --chain solana too (CLI 0.0.19). Never defaulted: the SDK checks the endpoint’s genesis hash against the deployment record before reading. Overridden by --svm-rpc-url. The SDKs take it as svm: { deploymentId: "solana-mainnet", rpcUrl } (JS) or Tokenomics20Config(solana_rpc_url=...) (Python).
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 contract (ERC-721; bridged through MachineNFTAdapter)
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	No	http://127.0.0.1:8000	Not used for Economics 2.0 reads. With TOKENOMICS_DEPLOYMENT_ID set, qualify, show, and monetize take the MCR host from the deployment record (https://mcr.peaq.xyz for peaq-mainnet) and do not read this variable. On peaq mainnet peaqos init pre-fills https://mcr.peaq.xyz and writes it to .env. peaqos whoami prints this variable (or the default), not the host the MCR commands use.
PEAQOS_VERIFY_API_URL	Verify only	n/a	HTTPS origin of the Verify API, read by peaqos verify status (or passed as the root --verify-api-url). No default; a missing or non-HTTPS value exits 3. Set it to https://mcr.peaq.xyz, where the Verify API is served next to the MCR API. The SDK read clients take the origin as a constructor argument and do not read this variable.
PEAQOS_MANIFEST_REPO_URL	Monetize only	n/a	Base URL of the provisioning-manifest repo, read by peaqos monetize provision (or passed as --manifest-repo). There is no default and it is never hardcoded; ask peaq for the current published base URL. The SDK resolves each manifest as <base>/<provider>/<version>.yaml. Missing it exits 3.
PEAQOS_MACHINE_WALLET_ADDRESS	Monetize	n/a	Machine wallet address used as the provisioning wallet context by peaqos monetize provision. --machine takes a decimal machine ID or did:peaq:<decimal id> (address DIDs are rejected), so this variable is the only way to supply the payout address. Unset it before provisioning a different machine. This value feeds the manifest’s commission/payout context.
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_S3_ACCESS_KEY_ID, PEAQOS_S3_SECRET_ACCESS_KEY, PEAQOS_S3_REGION, PEAQOS_S3_ENDPOINT	Stream only	n/a	Credentials, region and endpoint for peaqos stream publish --s3 and peaqos stream distribute --delivery s3 (needs the [s3] extra). The --s3-region and --s3-endpoint flags win over the region and endpoint variables.
PEAQOS_ORDER_STEP_DELAY_SEC	Scale only	n/a	Non-negative seconds to pause between peaqos scale order placement steps; unset means no delay.
PEAQOS_TELEMETRY	No	on	Anonymous usage telemetry toggle for the JS and Python SDKs, and for the CLI, which runs on the Python SDK. Set to 0 to disable. See Telemetry.
DO_NOT_TRACK	No	n/a	Cross-vendor opt-out convention: set to 1 to disable SDK and CLI 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). The CLI runs on the Python SDK, so CLI commands send the same events. 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, for the SDKs and the CLI alike.

Public RPC endpoints

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

peaq mainnet

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

peaq mainnet contracts

Core contracts 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.

Economics 2.0

Use the current releases of @peaqos/peaq-os-sdk, peaq-os-sdk and peaq-os-cli. Upgrade an existing environment with pip install -U peaq-os-cli peaq-os-sdk.

Selected by TOKENOMICS_DEPLOYMENT_ID=peaq-mainnet (CLI) or deploymentId: "peaq-mainnet" (SDKs). These are not environment variables: the addresses ship inside the SDK’s deployment record and are verified against InfoDesk.peer(role) before every write. Listed here so you can check what peaqos whoami resolves.

Contract	Address
InfoDesk	0x6C7426ada37212D94477Ac4CFcA43A38177D6A82
MachineRegistry	0x64b93Cc29b251fAFa83BD110cDB1C24207f85536
MachineStateAndSync	0xcD1917FB2a56459AcA34FDD118e08776dE0890f2
MachineSubscription	0x9e37AD189c334C92e6B8a812Ca4c02f35Ac43895
CrossChainMirror	0x71DCB313977d6884212395505f081a2991Bfe8E5
MachineBridgeAdapter	0x791087c35484b567c53f392a624d2e4BaDcC53DF
SubscriptionTokenProvisionPool	0x7088Cf400081428a41a4287B75AC633071c0e92A

The full 18-contract set, including PriceOracle and TrustValidatorStaking, is on Smart contracts.

Tokenomics 1.0 (required by the SDK constructor)

Variable	Address
IDENTITY_REGISTRY_ADDRESS	0xb53Af985765031936311273599389b5B68aC9956
IDENTITY_STAKING_ADDRESS	0x11c05A650704136786253e8685f56879A202b1C7
EVENT_REGISTRY_ADDRESS	0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA (Tokenomics 1.0; Economics 2.0 machines use 0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e, which peaqos init writes on CLI 0.0.13 and newer)
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 bridging into peaq from Base. 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 agung. Precompile addresses are identical to mainnet (same fixed slots on every peaq runtime).

Economics 2.0

Selected by TOKENOMICS_DEPLOYMENT_ID=agung-2026-08-28 or deploymentId: "agung-2026-08-28". Not environment variables.

Contract	Address
InfoDesk	0x72b66AF120c55371cA6e5Ce38D4e10dF1bA30Bb1
MachineRegistry	0x538da35489B1F0035799a8351E67835ae4ABb377
MachineStateAndSync	0xA7D33726232aae30622643a18047f0Ca3e159da9
MachineSubscription	0xaDCc5dD8CD57E3198B881c3388F25D2fD69B5aDc
CrossChainMirror	0xd5F8d5944c5d488B1cD698D642FC8156a8CD0c0c
MachineBridgeAdapter	0x0406e7bE522AEa626aee54f6258D415215e59F76
SubscriptionTokenProvisionPool	0x8A3692Ad0AcF79BB89413514Af9957d95032e19B

Tokenomics 1.0 (required by the SDK constructor)

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)
ADMIN_FLAGS_ADDRESS	0x4181a2Aa34aFb247450FfcBd65be5aBD4Cbee658	MCR API server (negative-flag + trust-override reads)

Bridging cannot be exercised on agung. LayerZero deprecated the agung endpoint (EID 40299), so bridgeNft / bridge_nft cannot relay. Leave MACHINE_NFT_ADAPTER_ADDRESS unset on agung and 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 limits funding requests per owner within an hourly window. 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.