Self-managed onboarding

Owner equals operator. One , one machine, one identity. This guide covers the full flow from environment setup through activation under Economics 2.0.

Prerequisites

Node.js ≥ 22 with @peaqos/peaq-os-sdk 0.7.0+, or Python 3.10+ with peaq-os-sdk 0.7.1+
A funded holding the tier plus . The bond is quoted per tier at the oracle rate (Entry quoted 0.803 PEAQ on mainnet on 2026-09-04 at 20:20 UTC; the figure moves with the daily oracle price); preview it before you fund. On peaq, bond and gas come out of the same PEAQ balance.
Environment variables configured per the install guide

Prefer the terminal? peaqos init then peaqos activate ... --dry-run does everything on this page in two commands. See CLI: activate.

Environment setup

.env

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

# Tokenomics 1.0 contracts. The SDK constructor still requires every variable below;
# activation does not read them. For agung 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

The Economics 2.0 contract addresses are not environment variables. You select a deployment record (peaq-mainnet or agung-2026-08-28) in code and the SDK verifies its addresses against InfoDesk.peer(role) on chain.

JS examples load the file via import "dotenv/config". Python’s from_env() reads from the shell, so export the file first with set -a && source .env && set +a or call load_dotenv().

Full flow

Initialize a client from the environment

fromEnv reads the required variables. Throws ValidationError if any is missing.

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

const owner = PeaqosClient.fromEnv();
console.log("Owner:", owner.address);

from dotenv import load_dotenv
from peaq_os_sdk import PeaqosClient

load_dotenv()

owner = PeaqosClient.from_env()
print("Owner:", owner.address)

Generate a keypair (optional)

If the machine does not already have a wallet, generate one. Local operation, no chain interaction.

const keypair = PeaqosClient.generateKeypair();
console.log("Address:", keypair.address);
// Store keypair.privateKey securely. It cannot be recovered.

address, private_key = PeaqosClient.generate_keypair()
print("Address:", address)
# Store private_key securely. It cannot be recovered.

If the machine already has a funded wallet, skip to step 6 and build the machine client with that key.

Set up 2FA on the owner wallet

The requires 2FA before it funds any address.

const FAUCET_URL = "https://depinstation.peaq.xyz";

const enrollment = await owner.setupFaucet2FA(keypair.address, FAUCET_URL);
console.log("OTPAuth URI:", enrollment.otpauthUri);
console.log("QR image:", enrollment.qrImageUrl);
// Scan the QR or paste the URI into your authenticator app. The QR URL expires after roughly 2 minutes.

FAUCET_URL = "https://depinstation.peaq.xyz"

enrollment = owner.setup_faucet_2fa(owner_address=address, faucet_base_url=FAUCET_URL)
print("OTPAuth URI:", enrollment["otpauth_uri"])
print("QR image:", enrollment["qr_image_url"])

Confirm 2FA

await owner.confirmFaucet2FA(keypair.address, FAUCET_URL, "123456"); // current TOTP code

owner.confirm_faucet_2fa(owner_address=address, faucet_base_url=FAUCET_URL, two_factor_code="123456")

Fund the machine wallet

Request initial gas from the Gas Station. The faucet funds the wallet or skips if the balance already suffices. The faucet covers gas, not the bond: top up the bond from any PEAQ-holding address after you have previewed the quote in step 7.

const result = await owner.fundFromGasStation(
  { ownerAddress: keypair.address, targetWalletAddress: keypair.address, chainId: "peaq", twoFactorCode: "654321" },
  FAUCET_URL,
);
console.log(result.status === "success" ? result.txHash : result.currentBalance);

result = owner.fund_from_gas_station(
    owner_address=address, target_wallet_address=address, chain_id="peaq",
    two_factor_code="654321", faucet_base_url=FAUCET_URL,
)
print(result["tx_hash"] if result["status"] == "success" else result["current_balance"])

Build the machine client in Tokenomics mode

The machine’s own key signs the activation, so the machine becomes owner, payer, and controller. Passing tokenomics20 selects the Economics 2.0 deployment.

const machine = new PeaqosClient<"tokenomics20">({
  rpcUrl: owner.rpcUrl,
  privateKey: keypair.privateKey,
  contracts: owner.contracts,
  tokenomics20: { deploymentId: "peaq-mainnet" }, // "agung-2026-08-28" for the testnet
});

from peaq_os_sdk import Tokenomics20Config

machine = PeaqosClient(
    rpc_url=owner.rpc_url,
    private_key=private_key,
    identity_registry=owner.contracts.identity_registry,
    identity_staking=owner.contracts.identity_staking,
    event_registry=owner.contracts.event_registry,
    machine_nft=owner.contracts.machine_nft,
    did_registry=owner.contracts.did_registry,
    batch_precompile=owner.contracts.batch_precompile,
    tokenomics20=Tokenomics20Config(deployment_id="peaq-mainnet"),  # "agung-2026-08-28" for the testnet
)

Preview the activation

The preview runs every check the activation runs (chain, contracts, peers, price, balance, allowance) without signing or spending. Use it to see the bond, any voucher credit, and the net PEAQ you must hold.

const params = {
  controller: keypair.address,
  verificationMethods: [{ id: "#key-1", methodType: "Ed25519VerificationKey2020", controller: keypair.address, publicKeyMultibase: "z6Mk..." }],
  authentication: [0n],
  serviceEndpoints: [
    { id: "#docs", serviceType: "Documentation", serviceEndpoint: "https://example.com/docs" },
    { id: "#data", serviceType: "DataApi", serviceEndpoint: "https://example.com/events" },
  ],
  machineType: "Sensor",
  credentialSubject: "0xdeadbeef",     // your identity anchor bytes; fixes the machine ID together with machineType
  manufacturer: "0x3333333333333333333333333333333333333333",
  tier: 0,                             // 0 Entry, 1 Basic, 2 Pro
};

const preview = await machine.previewMachineActivation(params);
console.log("machine ID", preview.machineId.toString());
console.log("bond", preview.bondAmount, "voucher", preview.voucherCredit, "net", preview.netPeaqAmount);
console.log("balance", preview.balance, "approval needed", preview.approvalRequired);

from peaq_os_sdk import ActivateMachineParams, ServiceEndpointInput, VerificationMethodInput

params = ActivateMachineParams(
    controller=address,
    verification_methods=(VerificationMethodInput(id="#key-1", method_type="Ed25519VerificationKey2020", controller=address, public_key_multibase="z6Mk..."),),
    authentication=(0,),
    service_endpoints=(
        ServiceEndpointInput(id="#docs", service_type="Documentation", service_endpoint="https://example.com/docs"),
        ServiceEndpointInput(id="#data", service_type="DataApi", service_endpoint="https://example.com/events"),
    ),
    machine_type="Sensor",
    credential_subject=bytes.fromhex("deadbeef"),  # your identity anchor bytes; fixes the machine ID together with machine_type
    manufacturer="0x3333333333333333333333333333333333333333",
    tier=0,  # 0 Entry, 1 Basic, 2 Pro
)

preview = machine.preview_machine_activation(params)
print("machine ID", preview.machine_id)
print("bond", preview.bond_amount, "voucher", preview.voucher_credit, "net", preview.net_peaq_amount)
print("balance", preview.balance, "approval needed", preview.approval_required)

If balance is below netPeaqAmount plus gas, top up the machine wallet now.

Activate

One transaction. The SDK approves exactly the net amount to MachineSubscription if needed, re-quotes, simulates, submits once, then requires the three receipt events and a matching on-chain state before returning.

const result = await machine.activateMachine(params);
console.log("Activated machine", result.machineId.toString());
console.log("Paid", result.netPeaqAmount, "wei of PEAQ; bonded", result.bondAmount);

result = machine.activate_machine(params)
print("Activated machine", result.machine_id)
print("Paid", result.net_peaq_amount, "wei of PEAQ; bonded", result.bond_amount)

The machine now has a peaqID (did:peaq:<machine id>), its Machine NFT (token ID equals the machine ID), and a tier bond. Confirm with getMachineActivationState / get_machine_activation_state: subscription.periodStart != 0 means activated (tier 0 is a valid tier, so never test the tier).

Error handling

Error	Cause	Resolution
`ValidationError: PEAQOS_PRIVATE_KEY is required`	Missing environment variable	Check your `.env` and shell export
`TokenomicsConfigError` `DEPLOYMENT_UNKNOWN`	Typo in the deployment ID	Use `peaq-mainnet` or `agung-2026-08-28`
`TokenomicsActivationError` `PRICE_NOT_AVAILABLE`	The oracle holds no PEAQ price for this chain	Chain-side condition; retry after the trust validator’s next daily stamp
`TokenomicsActivationError` `INSUFFICIENT_BALANCE`	Wallet does not hold the net PEAQ plus gas	Top up the machine wallet and retry
`TokenomicsActivationError` `CONTRACT_REVERTED` with `MachineAlreadyExists` or similar	The same `machineType` + `credentialSubject` pair was activated before	Pick a new credential subject; the pair is permanent
`TokenomicsPendingTransactionError` / `PENDING_TRANSACTION`	Receipt did not arrive in time	Do not resubmit. Reconcile with `reconcile_activation_transaction` (Python) or re-check `getMachineActivationState` by machine ID
`RuntimeError: Invalid 2FA code` / `ApiError: Invalid 2FA code`	TOTP code expired or mistyped	Wait for a fresh code and retry
`RuntimeError: Faucet rate limit exceeded` / `ApiError`	Too many funding requests	Retry after a short interval

Full code tables on errors.

What the machine receives

peaqID did:peaq:<machine id> with the DID document you supplied (verification methods, authentication, service endpoints)
Machine NFT in MachineRegistry, token ID equal to the machine ID
Subscription on the chosen tier for 365 days, bonded in PEAQ; renew before the 14-day grace and 14-day runoff windows end. See Economics 2.0
Home chain record on peaq
Gas Station funding (if requested)

Machines onboarded before Economics 2.0

registerMachine / register_machine, mintNft, and writeMachineDIDAttributes still work on a client constructed without tokenomics20 and still address the Tokenomics 1.0 contracts (1 PEAQ native bond, separate Machine NFT). They emit deprecation warnings and throw in Tokenomics mode. Use them only to maintain machines onboarded before 2026-09-01. See Activate: legacy flow.

Welcome

Get Started

Concepts

Functions

Guides

Self-managed onboarding

Prerequisites

Environment setup

Full flow

Error handling

What the machine receives

Machines onboarded before Economics 2.0

​Prerequisites

​Environment setup

​Full flow

​Error handling

​What the machine receives

​Machines onboarded before Economics 2.0

Prerequisites

Environment setup

Full flow

Error handling

What the machine receives

Machines onboarded before Economics 2.0