Activate

Put your machine on-chain: peaqID, Machine NFT, and a tier bond. Activation is one transaction on peaq and seven stages on Solana.

Activate is the entry point to peaqOS. One transaction registers a machine on peaq chain, mints its Machine NFT, stores its peaqID document, and bonds it on a subscription tier under Economics 2.0. A machine can also be homed on Solana; that takes seven stages instead of one transaction, run from one CLI command or one SDK script (see Home chain: Solana).

Requires the current @peaqos/peaq-os-sdk, peaq-os-sdk (Python 3.10 or newer) or peaq-os-cli release; a Solana home needs CLI 0.0.19, Python SDK 0.11.2 or JS SDK 0.11.2, or newer (older CLIs onboard, but cannot send the machine’s events (0.0.17) or manage it (0.0.18) afterwards). The earlier register-then-mint flow (registerMachine, mintNft, writeMachineDIDAttributes) is the Tokenomics 1.0 path. It serves machines already onboarded under Tokenomics 1.0, on an SDK client constructed without a Tokenomics 2.0 deployment, and is documented in the legacy section below. New machines use the activation flow on this page. The CLI has no legacy path.

What ships

Component	Description
peaqID	W3C DID stored on-chain as a DID document (verification methods, authentication, service endpoints). Its id is did:peaq:<machine id>.
Machine NFT	On peaq, one ERC-721 in MachineRegistry, minted by the activation call; on Solana, the Machine account the native_onboarding stage creates. The machine ID is the token ID. No separate Identity NFT.
Subscription bond	PEAQ bonded on the tier you choose (Entry, Basic, or Pro, on either home chain). Quoted per tier at the oracle rate when you activate; a machine homed on Solana pays it on Solana, in PEAQ or USDC. Not withdrawable. See Economics 2.0.
Home chain record	CrossChainMirror records the machine’s home chain: peaq for the one-transaction flow on this page, Solana for a machine created there (see Home chain: Solana).
Machine wallet	Per-machine EVM keypair, generated by the SDK or the CLI. A machine homed on Solana is owned by a Solana keypair instead, which also pays its bond; a peaq operator wallet registers that keypair once.

Machine ID

The machine ID is derived, not sequential:

machineId = uint256(keccak256(abi.encode(machineType, credentialSubject)))

Only machineType and the exact credentialSubject bytes contribute. Neither can change after activation, and the same pair cannot be activated a second time while the machine exists. IDs are full-width uint256 values (routinely 77 digits): bigint in JavaScript, int in Python, and a decimal string in JSON, URLs, and CLI output. The 2.0 DID form is did:peaq:<decimal machine id>, not an address.

How activation works

Select a deployment (peaq-mainnet or agung-2026-08-28), preview the quote, then activate. Contract addresses travel with the deployment record inside the SDK; you never set them.

CLI

# .env: TOKENOMICS_DEPLOYMENT_ID=peaq-mainnet (peaqos init writes it)
peaqos activate \
  --machine-type Sensor \
  --credential-subject-hex 0xdeadbeef \
  --manufacturer 0x3333333333333333333333333333333333333333 \
  --tier entry \
  --did-document ./did.json \
  --dry-run          # preview the bond and the net PEAQ, submit nothing

# Same command without --dry-run submits the one transaction.

USDT settlement (--payment usdt --slippage-bps 50) is not configured on peaq mainnet; pay the bond in PEAQ. --for 0xMachine --machine-key ./machine.key switches to machine-owned, operator-controlled mode (see Two ownership modes). Full flag table on CLI: activate.

JavaScript

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

const client = new PeaqosClient<"tokenomics20">({
  rpcUrl: process.env.PEAQOS_RPC_URL!,
  privateKey: process.env.PEAQOS_PRIVATE_KEY!,
  contracts: PeaqosClient.fromEnv().contracts, // the six legacy addresses are still required by the constructor
  tokenomics20: { deploymentId: "peaq-mainnet" }, // or "agung-2026-08-28"
});

const params: ActivateMachineParams = {
  controller: client.address,
  verificationMethods: [
    {
      id: "#key-1",
      methodType: "Ed25519VerificationKey2020",
      controller: client.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",
  manufacturer: "0x3333333333333333333333333333333333333333",
  tier: 0, // 0 Entry, 1 Basic, 2 Pro
};

const preview = await client.previewMachineActivation(params);
console.log(preview.machineId, preview.bondAmount, preview.voucherCredit, preview.netPeaqAmount);

const result = await client.activateMachine(params);
console.log(result.machineId);        // bigint, the permanent machine ID
console.log(result.netPeaqAmount);    // PEAQ actually transferred
console.log(result.isHomedLocally);   // true, confirmed on-chain

Python

import os
from dotenv import load_dotenv
from peaq_os_sdk import (
    ActivateMachineParams,
    PeaqosClient,
    ServiceEndpointInput,
    Tokenomics20Config,
    VerificationMethodInput,
)

load_dotenv()
legacy = PeaqosClient.from_env()  # from_env() also reads TOKENOMICS_DEPLOYMENT_ID; the explicit constructor below is equivalent

client = PeaqosClient(
    rpc_url=legacy.rpc_url,
    private_key=os.environ["PEAQOS_PRIVATE_KEY"],
    identity_registry=legacy.contracts.identity_registry,
    identity_staking=legacy.contracts.identity_staking,
    event_registry=legacy.contracts.event_registry,
    machine_nft=legacy.contracts.machine_nft,
    did_registry=legacy.contracts.did_registry,
    batch_precompile=legacy.contracts.batch_precompile,
    tokenomics20=Tokenomics20Config(deployment_id="peaq-mainnet"),  # or "agung-2026-08-28"
)

params = ActivateMachineParams(
    controller=client.address,
    verification_methods=(
        VerificationMethodInput(
            id="#key-1",
            method_type="Ed25519VerificationKey2020",
            controller=client.address,
            public_key_multibase="z6Mk...",
        ),
    ),
    authentication=(0,),
    service_endpoints=(
        ServiceEndpointInput(id="#docs", service_type="peaq-documentation", service_endpoint="https://example.com/docs"),
        ServiceEndpointInput(id="#data", service_type="peaq-data-api", service_endpoint="https://example.com/events"),
    ),
    machine_type="Sensor",
    credential_subject=bytes.fromhex("deadbeef"),
    manufacturer="0x3333333333333333333333333333333333333333",
    tier=0,  # 0 Entry, 1 Basic, 2 Pro
)

preview = client.preview_machine_activation(params)
print(preview.machine_id, preview.bond_amount, preview.voucher_credit, preview.net_peaq_amount)

result = client.activate_machine(params)
print(result.machine_id)        # int, the permanent machine ID
print(result.net_peaq_amount)   # PEAQ actually transferred
print(result.is_homed_locally)  # True, confirmed on-chain

What the call does

1. Validates every input locally.
2. Verifies the connected chain, that all seven Tokenomics 2.0 contracts have bytecode, that the peer addresses match InfoDesk.peer(role), and that MachineSubscription.isEconomicAuthority() is true.
3. Computes the machine ID, reads MachineStateAndSync.isTechnicalPausedGlobal() and isTechnicalPaused(machineId) (a set flag stops here with TECHNICALLY_PAUSED, before any approval), and quotes the bond: bond = requiredPeaqAmount(tier), voucher = min(pendingVoucherCredit, bond), net = bond - voucher.
4. Resolves the PEAQ token from InfoDesk.peaqToken(), checks balance and allowance, and approves exactly net to MachineSubscription if the allowance is short.
5. Re-reads the quote, simulates, and submits the one MachineStateAndSync.activateMachine transaction.
6. Requires three correlated receipt events (MachineOnboarded, MachineMinted, Activated) and reconciles the resulting state (ownerOf, controllerOf, subscription tier and period, isHomedLocally) before returning.

The transaction sender becomes the machine’s owner and bond payer. manufacturer is recorded on-chain and never verified by the contract. On peaq, PEAQ is the native-balance precompile at 0x…0809, so bond and gas come out of the same balance: a wallet holding exactly the net amount still fails on gas.

A transaction whose receipt does not arrive in time is reported as pending with its hash (PENDING_TRANSACTION in the Python SDK, RECEIPT_UNAVAILABLE in the JS SDK, PENDING at exit 2 in the CLI), and it may still mine. Never submit a second activation for the same machine: reconcile the recorded hash instead (reconcile_activation_transaction in Python, re-running the same command in the CLI).

Two ownership modes

Mode	Who signs and pays	Controller	Use when
Self-owned	Your configured signer owns the machine, pays the bond, and is its DID controller.	Same address as the owner	One machine, one wallet.
Machine-owned, operator-controlled	The machine wallet signs, owns the NFT, and pays gas and the bond.	Your operator address, recorded in the DID document	Fleets where the operator manages many machines.

Rights differ by role and both parties should know them:

Who	Can	Cannot
Machine wallet (owner)	Transfer the NFT; rotate or clear the controller
Operator (controller)	Lifecycle (suspend, resume), subscription renewals, DID updates	Transfer the NFT; rotate or clear the controller

Operator-sponsored onboarding has no 2.0 equivalent. MachineStateAndSync.activateMachine makes msg.sender the owner and the payer, so an operator cannot activate a machine it does not own, and registerFor / register_for throw SPONSORED_ACTIVATION_UNSUPPORTED in Tokenomics mode. The supported fleet pattern is the machine-owned, operator-controlled mode above. Full guide: Fleet onboarding.

Home chain: Solana

A machine can be created on Solana instead of peaq. The identity, DID document and NFT become Solana accounts that name a Solana key as owner, and that key pays the bond on Solana, in PEAQ or USDC, through the subscription terminal; peaq books it. The flow is seven stages instead of one transaction: a peaq operator wallet registers the Solana owner wallet on peaq (once per owner wallet), the owner opens an activation request on Solana, peaq’s Trust Validator node credits it, the owner settles it, peaq books the bond, and the owner mints the machine (native_onboarding) and sends the link push (linkage) back to peaq, where the node delivers it with no messaging fee. The CLI runs all seven from one peaqos activate --chain solana command, or one stage at a time with --phase; the Python and JavaScript SDKs cover the same stages: register_solana_operator / registerSolanaOperator for the registration, then activate_machine / activateMachine for the rest. The full walkthrough, with the costs and the scripts that onboarded the proven machines, is Onboard a machine on Solana.

Confirm activation

state = client.get_machine_activation_state(result.machine_id)   # result from activate_machine above
activated = state.subscription.period_start != 0   # tier 0 is a valid tier, so never test the tier

peaqos machine status <machine-id> --json

Or open the machine on the Machine Explorer: https://machines.peaq.xyz/machine/<decimal machine id> for a machine activated under Economics 2.0, https://machines.peaq.xyz/machine/0x<address> for a Tokenomics 1.0 or mirrored legacy machine. The explorer indexes from chain, so allow a few minutes after the transaction.

The MCR addresses 2.0 machines by decimal ID: mcr.peaq.xyz answers a did:peaq:0x<address> DID with 400 Invalid machine DID format. Call queryMcr / query_mcr on a tokenomics20 client, or GET https://mcr.peaq.xyz/mcr/did:peaq:<decimal id> instead. See API reference.

After activation

Next step	Function	Status
Manage the machine: suspend, resume, renew, transfer, DID updates	CLI: machine, SDK	Live
Build a credit rating from revenue and activity events	Qualify	Live. 2.0 ratings come from mcr.peaq.xyz. A machine homed on Solana submits its events to the Solana EventRegistry program (guide)
Pair an AI agent with delegated spending and run market search	Scale	Paused. Market registration fails for Tokenomics 1.0 machines (503 PEAQOS_IDENTITY_UNAVAILABLE, mcr.peaq.xyz does not serve did:peaq:0x<address> DIDs), and the SDKs refuse identity-binding orchestration calls on a tokenomics20 client
Provision the machine as a compute provider and earn to its wallet	Monetize	Live. 2.0 opt-in reaches mcr.peaq.xyz. With a Solana signer set, the SDK checks the home chain and refuses opt-in for a Solana-homed machine with SOLANA_MONETIZATION_UNVERIFIED before signing (details)
Get the machine attested (chip and operator KYB) and read its verification state	Verify	Beta. Reads and chip preflight in the SDKs and the CLI; peaq is the only attester in v1
Fractionalize the machine for investor ownership	Tokenize	Coming Soon

Legacy flow (Tokenomics 1.0)

Machines onboarded before Economics 2.0 live in IdentityRegistry with a 1 PEAQ native bond and a separate MachineNFT token. The SDKs keep this path when you construct a client without tokenomics20: registerMachine / register_machine (self-managed) or registerFor / register_for (proxy), then mintNft, tokenIdOf, and writeMachineDIDAttributes. Each of these emits a deprecation warning and throws a typed error in Tokenomics mode.

Legacy machines can be mirrored into Economics 2.0 through the MachineMigrationHub; that path is operated by peaq for partner fleets, not exposed in the SDKs. See Economics 2.0: legacy machines.

Concepts

Economics 2.0

Tiers, bonds, credits, grace and runoff, trust validators.

peaqID

W3C DID, DID document, portable identity.

Machine NFT

The ERC-721 whose token ID is the machine ID.

Smart contracts

Addresses on peaq mainnet and agung.

Gas Station

2FA-gated faucet for initial machine gas.

Machine Credit Rating

Rating from a machine’s history.

SDK reference

• activateMachine / activate_machine: the one-transaction activation on peaq, or the Solana phases with a phase in both SDKs.
• previewMachineActivation / preview_machine_activation: quote without signing.
• getMachineActivationState / get_machine_activation_state: confirm the result.
• fundFromGasStation / fund_from_gas_station: request gas for a fresh wallet.
• generateKeypair / generate_keypair: create a machine keypair.
• Machines homed on Solana: SDK JS: Solana (SVM), SDK Python: Solana.

Guides

Onboarding quickstart

Terminal walkthrough: CLI, wallets, costs, activation on peaq or Solana, recovery.

Self-managed onboarding

Single machine, owner-operated.

Fleet onboarding

Machine-owned, operator-controlled: N machines from one operator.

Solana onboarding

Home the machine on Solana: pay the bond on Solana in PEAQ or USDC, mint the machine there, link it back to peaq.