Self-managed onboarding

Activate a single machine where the owner is the operator. Generate keys, set up 2FA, fund via Gas Station, preview, and activate in one transaction.

One machine that owns itself: the machine’s own keypair signs the activation, so the machine wallet becomes owner, payer and DID controller. The wallet in your .env (PEAQOS_PRIVATE_KEY) only enrolls in the Gas Station and requests gas for the machine wallet; it gets no rights over the machine. This guide covers the full flow from environment setup through on-chain activation under Economics 2.0. To home the machine on Solana instead (two wallets, seven stages), follow Onboard a machine on Solana.

Prerequisites

• Node.js ≥ 22 with @peaqos/peaq-os-sdk and dotenv (npm i @peaqos/peaq-os-sdk dotenv; the examples use top-level await, so run them as an ES module), or Python 3.10+ with peaq-os-sdk and python-dotenv (pip install peaq-os-sdk python-dotenv)
• A funded EVM wallet holding the tier bond plus gas. The bond is quoted per tier at the daily oracle rate, so preview it before you fund. On peaq, bond and gas come out of the same PEAQ balance.
• Environment variables configured per the install guide

The onboarding quickstart does everything on this page with the CLI, for peaq and Solana homes. Flag reference on 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>

# SDK constructor variables: required by the constructor, not read by activation.
# IDENTITY_*, MACHINE_NFT_ADDRESS are Tokenomics 1.0 contracts; DID_REGISTRY and BATCH_PRECOMPILE are chain precompiles. For agung addresses see /peaqos/install#agung-testnet-contracts.
IDENTITY_REGISTRY_ADDRESS=0xb53Af985765031936311273599389b5B68aC9956
IDENTITY_STAKING_ADDRESS=0x11c05A650704136786253e8685f56879A202b1C7
EVENT_REGISTRY_ADDRESS=0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e   # 2.0 EventRegistry; 1.0 machines use 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

1. Initialize a client from the environment

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

   JS/TS

   import "dotenv/config";
   import { PeaqosClient, type ActivateMachineParams } from "@peaqos/peaq-os-sdk";
   
   const funder = PeaqosClient.fromEnv();
   console.log("Funding wallet:", funder.address);
   
2. Generate a keypair (optional)

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

   JS/TS

   const keypair = PeaqosClient.generateKeypair();
   console.log("Address:", keypair.address);
   // Store keypair.privateKey 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 (the later steps use keypair.address / keypair.privateKey in JS and address / private_key in Python, so assign those names from your existing wallet).

3. Set up 2FA on the funding wallet

   The Gas Station requires 2FA before it funds any address.

   JS/TS

   const FAUCET_URL = "https://depinstation.peaq.xyz";
   
   const enrollment = await funder.setupFaucet2FA(funder.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.
   
4. Confirm 2FA

   JS/TS

   await funder.confirmFaucet2FA(funder.address, FAUCET_URL, "123456"); // current TOTP code
   
5. 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.

   JS/TS

   const funding = await funder.fundFromGasStation(
     { ownerAddress: funder.address, targetWalletAddress: keypair.address, chainId: "peaq", twoFactorCode: "654321" },
     FAUCET_URL,
   );
   console.log(funding.status === "success" ? funding.txHash : funding.currentBalance);
   
6. 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.

   JS/TS

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

   The preview runs the activation’s checks up to the quote (chain, contracts, peers, pause state, price) and reports balance and allowance, without signing or spending. It does not reject a short balance or simulate the activation call; the activation does both before it submits. Use it to see the bond, any voucher credit, and the net PEAQ you must hold.

   JS/TS

   const params: ActivateMachineParams = {
     controller: keypair.address,
     verificationMethods: [{ id: "#key-1", methodType: "Ed25519VerificationKey2020", controller: keypair.address, publicKeyMultibase: "z6Mk..." }],
     authentication: [0n],
     serviceEndpoints: [
       { id: "#docs", serviceType: "peaq-documentation", serviceEndpoint: "https://example.com/docs" },
       { id: "#data", serviceType: "peaq-data-api", 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);
   

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

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

   JS/TS

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

   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: Environment variable PEAQOS_PRIVATE_KEY is required but not set	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 holds less than the net PEAQ bond	Top up the machine wallet with the net bond plus a gas margin and retry; this check does not reserve gas
TokenomicsActivationError CONTRACT_REVERTED naming ERC721InvalidSender	The same machineType + credentialSubject pair was activated before	Pick a new credential subject; the pair is permanent
TokenomicsPendingTransactionError PENDING_TRANSACTION (Python) / TokenomicsActivationError RECEIPT_UNAVAILABLE (JS)	Receipt did not arrive in time	Do not resubmit. Reconcile with reconcile_activation_transaction (Python) or re-check getMachineActivationState by machine ID (JS)
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

Tokenomics 1.0 path. registerMachine / register_machine, mintNft, and writeMachineDIDAttributes serve machines already onboarded under Tokenomics 1.0. They run on a client constructed without tokenomics20 and address the Tokenomics 1.0 contracts (1 PEAQ native bond, separate Machine NFT). They emit deprecation warnings and throw in Tokenomics mode. New machines use the activation flow above. See Activate: legacy flow.