Onboarding quickstart

Onboarding a machine to peaqOS gives it a permanent identity (a ), an ownership record (a ) and a subscription that says the machine is committed to the network. From that point on it can build a credit history, be managed by its owner and operator, and sell the data it produces. This page walks you through that from a blank terminal to an activated machine. You don’t need to know how the contracts work; you need a terminal, a little PEAQ, and about half an hour for a first machine on peaq. A first machine on Solana takes longer, because it runs in three phases with a wait in between. Each step says what it does, what to type, and how you know it worked. The reference pages (Activate, peaqOS CLI, Onboard a machine on Solana) go deeper on any flag you want to understand.

First decision: where should the machine live?

A machine has a home chain: the chain that holds its identity, DID document and NFT. Today that is either peaq or Solana. The machine ID and the peaqID look the same either way, and both homes can use Stream to sell data.

	Home on peaq	Home on Solana
How activation works	One command	Three phases: reserve and bond on peaq, wait for peaq to mirror to Solana, create the machine on Solana
Who finishes it	You, with one confirmed transaction	peaq’s side, twice: it mirrors your bond to Solana before phase three, and links the machine back to peaq after it. You wait for both
Wallets you need	One wallet, funded with PEAQ	Two: an operator wallet funded with PEAQ and an owner wallet funded with SOL
Tiers available	Entry, Basic, Pro	Basic, Pro
Where the bond is held	peaq	peaq (paid by the operator wallet)
Where identity, DID and NFT live	peaq contracts	Solana accounts naming your Solana key as owner
Where events are recorded	peaq `EventRegistry`	Solana `EventRegistry` program
Credit rating (MCR)	Available	Provisioned at activation; scored once the MCR has indexed the machine’s Solana events
Monetize (opt-in)	Available through the 2.0 MCR	Coming: the SDK and CLI refuse the opt-in for Solana-homed machines until that write path is released
Machine Market (Scale)	Coming for Economics 2.0 machines	Coming

A good rule of thumb: choose peaq unless the machine’s owner, its buyers or its payments already live on Solana. If you are not sure, start on peaq; it is the shorter path.

What it costs

Activation costs the tier bond plus gas. The bond is priced in US dollars per tier and paid in PEAQ at the oracle’s most recently committed price. The preview (--dry-run) prints the exact PEAQ amount before anything is submitted. To size a wallet before you run anything, divide the tier’s dollar price by the current PEAQ price.

Tier	USD price per 365-day period	Available on
Entry	$0.02	peaq
Basic	$0.20	peaq, Solana
Pro	$40	peaq, Solana

The bond buys one 365-day subscription period, so budget it per machine per year. Renew with peaqos machine subscription renew <machine_id> before the period ends. After it ends you get a grace period, currently 14 days, then a runoff, currently another 14 days, in which the bond decays to zero, and then the machine is terminated and its Machine NFT is burned. Renewing late does not refund lost time: the new period runs from the old period end, not from the day you renew, and it costs a full bond. Suspending a machine does not pause any of this. The subscription lifecycle describes the whole sequence. On top of the bond you pay peaq gas (a few transactions, small) and, for a Solana home, SOL for network fees and account rent (the preview prints an estimate). The bond can be paid in USDT instead of PEAQ: on peaq that is --payment usdt --slippage-bps 50, and the second flag is required. On Solana the USDT flags differ; see the argument set. Gas is always PEAQ. Bonds are not withdrawable. Prices and the formula are on Economics 2.0.

Part 1: Set up once per fleet

Everything in this part you do once, and every machine you onboard afterwards reuses it.

Install the CLI

You need Python 3.10 or newer. Installing into a virtual environment keeps it separate from anything else on your machine.

python3 -m venv .peaqos-env && source .peaqos-env/bin/activate
pip install -U 'peaq-os-cli[solana,ows]>=0.0.12'
peaqos --version

You should see peaq-os-cli 0.0.12 (peaq_os_sdk 0.8.0) or newer, which is what this page is written for. The ows extra adds the encrypted wallet vault used below; solana is only needed for a Solana home. Everything here is mainnet.

Make a folder for the fleet and run the setup wizard

The CLI keeps three things in the folder you run it from: a .env file with your settings, your DID documents, and peaqos.log, a journal of every transaction it sends. The journal is what lets the CLI pick up safely after an interruption, so keep this folder and back it up. Your wallets are not in it: they live in the vault at ~/.ows/, which needs its own backup.

mkdir my-fleet && cd my-fleet
peaqos init

The wizard asks a handful of questions. Choose mainnet, choose wallet as the key source when offered (it creates an encrypted wallet rather than a raw key), and when it asks for a wallet name type fleet-owner for a peaq home or fleet-operator for a Solana home. It also asks for a passphrase; you need it for every command that signs with that wallet. Accept the defaults for the rest. It downloads the contract addresses for you, so stay online, and finishes by running peaqos whoami to show what it wrote.

One value to change by hand: open .env and set EVENT_REGISTRY_ADDRESS=0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e, the Economics 2.0 event contract. The wizard writes the Tokenomics 1.0 address, and an event sent there for a 2.0 machine is rejected, not recorded. A Solana-homed machine records its events on Solana instead, but leave the value set: every command that builds a client needs it.

Create and fund the wallet(s)

Wallets live in the vault at ~/.ows/, each protected by its own passphrase. For each wallet, run peaqos wallet export <name> once and store the seed phrase somewhere safe; nothing else can recover the key. The command prints the phrase to the terminal, so do not run it anywhere the output is logged. Creating a wallet does not put any funds in it: send PEAQ (and SOL, for a Solana home) to the addresses it prints.

Home on peaq
Home on Solana

The wizard already created fleet-owner and named it in .env as the signer. One wallet does everything: it pays the bond and gas and owns the machine.

peaqos wallet show fleet-owner --json

Copy the 0x… address and send PEAQ to it: the bond plus at least 0.5 PEAQ. Below 0.5 PEAQ a real peaqos activate run stops to fund the wallet for you through the Gas Station, which the first time means enrolling an authenticator app from a QR code. Staying above 0.5 PEAQ avoids it, and --skip-funding turns it off.If you would rather each machine own its own NFT while you keep control as operator, give each machine its own raw key file and activate with --for and --machine-key; the fleet guide explains that pattern and how to make the key files.

You need two wallets, split by role. The operator wallet acts on peaq, where it reserves the machine and pays the bond and gas in PEAQ. The wizard already created it as fleet-operator. The owner wallet acts on Solana, where it creates the machine and pays fees and rent in SOL. One pair can serve your whole fleet.

peaqos wallet create fleet-owner
peaqos wallet show fleet-operator --json
peaqos wallet show fleet-owner --json

create asks for a passphrase for the new wallet. Copy the 0x… address from the first show and send PEAQ to it, and the Solana (base58) address from the second and send SOL to it.Then tell the CLI which Solana network to use by adding two lines to .env:

PEAQOS_SVM_NETWORK=mainnet-beta
PEAQOS_SVM_RPC_URL=https://api.mainnet-beta.solana.com

Any Solana RPC provider works here; the public endpoint is fine for a handful of machines.

Write the DID document

The DID document is a small JSON file that describes the machine: which key speaks for it and where to find its data and documentation. Save it as did.json in the fleet folder. You can reuse one template for the whole fleet and change only the URLs if they differ per machine.For a first fleet, point the verification method at the wallet that will own the machines. On peaq, controller is the wallet’s 0x… address. On Solana it is the owner wallet’s base58 address. publicKeyMultibase carries the verifying key in multibase form (z6Mk… for an Ed25519 key). No peaqos command prints this value: if the machine has its own Ed25519 key, encode that; if not, leave the placeholder text for now. The chain stores the DID document as given and does not check these values against the wallet, so a fleet can start with the owner as controller and replace both fields later, when the machine has its own key, with peaqos machine did set-verification-methods.

did.json

{
  "verificationMethods": [
    {
      "id": "#key-1",
      "methodType": "Ed25519VerificationKey2020",
      "controller": "<owner wallet address>",
      "publicKeyMultibase": "z6Mk<public key in multibase>"
    }
  ],
  "authentication": [0],
  "serviceEndpoints": [
    { "id": "#data", "serviceType": "DataAPI", "serviceEndpoint": "https://api.example.com/machines" },
    { "id": "#docs", "serviceType": "Documentation", "serviceEndpoint": "https://docs.example.com" }
  ]
}

Keep the three keys above and nothing else at the top level: id and controller are rejected there, because the machine’s ID is computed on chain and the CLI sets the controller itself. authentication lists which verification methods may authenticate, by position (0 is the first one). Solana has size limits on these fields, listed on the Solana page.

Part 2: Activate each machine

Two inputs define a machine forever: a machine type, one word or phrase you use for the whole fleet (Sensor, Robot, Vehicle, Charger…), and a credential subject, some bytes that identify this particular unit. The serial number is the usual choice. Together they produce the machine ID, and that pair cannot be activated a second time while the machine exists, so pick them deliberately.

SERIAL=<the machine's serial number>
CREDENTIAL_SUBJECT_HEX=0x$(printf '%s' "$SERIAL" | od -An -v -tx1 | tr -d ' \n')
echo "$CREDENTIAL_SUBJECT_HEX"

Check that echo prints more than 0x before you go on. An unset SERIAL produces an empty credential subject, which is accepted and cannot be changed afterwards. Now follow the tab for your home chain. Every activate and machine write first shows you what it is about to do and asks for confirmation, and most take --dry-run, which shows the same preview and stops.

Home on peaq
Home on Solana

Preview

Nothing is sent. The output shows the bond for your tier, any voucher credit, and the net PEAQ the wallet needs.

peaqos activate \
  --machine-type Sensor \
  --credential-subject-hex "$CREDENTIAL_SUBJECT_HEX" \
  --manufacturer 0x<manufacturer address> \
  --tier basic \
  --did-document ./did.json \
  --dry-run

--manufacturer is any EVM address you choose to record as the maker; the network stores it but does not check it. --tier is entry, basic or pro. If the preview says the wallet is short, top it up and preview again.

Activate

The same command without --dry-run. Read the terms it prints and confirm. In a script, add --yes to confirm and --json for machine-readable output, and set OWS_PASSPHRASE (no PEAQOS_ prefix on this one) to the signing wallet’s passphrase or it still stops to ask.

peaqos activate \
  --machine-type Sensor \
  --credential-subject-hex "$CREDENTIAL_SUBJECT_HEX" \
  --manufacturer 0x<manufacturer address> \
  --tier basic \
  --did-document ./did.json

Activation is one atomic call: it mints the NFT, stores the DID document, bonds the tier and records peaq as the home. When your wallet’s allowance does not already cover the bond, the CLI sends a separate token approval before it, so you may see two transactions go out. The output includes the machine_id, a long decimal number. Keep it; every later command identifies the machine by it.

Check

peaqos machine status <machine_id> --json

You should see your wallet as owner, your tier under subscription, and is_homed_locally: true. The machine’s peaqID is did:peaq:<machine_id>.

On Solana, activation is three phases run one at a time, and each phase must be given the same complete set of arguments. Setting them once in a shell array avoids typos between phases. Give each Solana machine its own working folder; the CLI’s journal check treats the folder as one attempt. From the fleet folder:

mkdir "../machine-$SERIAL" && cp .env did.json "../machine-$SERIAL/" && cd "../machine-$SERIAL"

If you open a new terminal here, run the serial block at the top of Part 2 again so CREDENTIAL_SUBJECT_HEX is set.

Fill in the argument set

Most of these are ceilings the CLI will not exceed, not prices, and a ceiling set below the real cost fails the run instead of warning. 20 PEAQ covers a Basic machine; for a Pro machine set PEAQ_CAP to 200 times that, 4,000 PEAQ, before previewing.

# read one value; .env is unquoted and holds secrets
PEAQOS_RPC_URL=$(grep -m1 '^PEAQOS_RPC_URL=' .env | cut -d= -f2-)
OWNER=<fleet-owner Solana address>
OPERATOR=<fleet-operator 0x address>
MANUFACTURER=<a Solana address to record as the maker>   # recorded, never verified; the owner address is fine
PEAQ_CAP=20000000000000000000            # 20 PEAQ, in base units (18 decimals)
FEE_CAP=100000                           # Solana network + priority fees, in lamports
RENT_CAP=10000000                        # Solana account rent, in lamports (0.01 SOL)
COMPUTE_LIMIT=600000
PRIORITY_PRICE=0
# the finalized block, not the chain head: a start ahead of finalized is rejected
HISTORY_START=$(curl -s -X POST -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["finalized",false]}' \
  "$PEAQOS_RPC_URL" | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"]["number"],16))')
printf '%s\n' "$OWNER" "$OPERATOR" "$MANUFACTURER" "$HISTORY_START"

ARGS=(
  --chain solana --json
  --solana-owner "$OWNER" --evm-operator "$OPERATOR" --manufacturer "$MANUFACTURER"
  --machine-type Sensor --credential-subject-hex "$CREDENTIAL_SUBJECT_HEX"
  --tier basic --did-document ./did.json
  --payment peaq --max-net-peaq-amount "$PEAQ_CAP"
  --max-native-fee-lamports "$FEE_CAP" --max-native-rent-lamports "$RENT_CAP"
  --from-block "$HISTORY_START"
  --compute-unit-limit "$COMPUTE_LIMIT" --compute-unit-price-micro-lamports "$PRIORITY_PRICE"
)

printf should print four lines: two addresses, the manufacturer and a block number. An empty line means that value is not set (the manufacturer is recorded unchecked, so an empty one would be kept), and an empty last line means the RPC read failed. Fix that before going on. For a Pro machine, change --tier basic to --tier pro. What each flag means in detail: the argument set.

Save these values and did.json together, and do not change them between phases. The CLI fingerprints the wallets, the machine inputs, the tier, the ceilings and the DID document, and a later phase run with a changed value stops until you put the original back. Once the bond is paid there is no cancel and no refund, so a machine whose original inputs are gone cannot be finished. Do not upgrade the CLI or the SDK in the middle of onboarding a machine either. The full list of what is fingerprinted, and the three flags you may change, is on the Solana page.

Preview the whole plan

No wallet needed, nothing is sent. Read the bond quote and the Solana fee and rent estimates, raise a ceiling if the preview asks for it, and make sure both wallets hold enough.

peaqos activate "${ARGS[@]}" --dry-run

Reserve the machine on peaq (operator wallet)

This claims the machine ID for your Solana owner.

PEAQOS_OWS_WALLET=fleet-operator peaqos activate "${ARGS[@]}" --phase reservation

The output includes machine_id. It stays the same for every later step.

Pay the bond on peaq (operator wallet)

PEAQOS_OWS_WALLET=fleet-operator peaqos activate "${ARGS[@]}" --phase subscription

This is two transactions under the hood (an approval, then the subscription itself); the CLI handles both and tells you when the subscription is active.

Wait for peaq to mirror to Solana

peaq now pushes the reservation and the subscription status to Solana. Delivery happens outside the CLI, so a peaq receipt does not mean it has arrived. Run the preview for the final phase until it reports both prerequisites ready:

peaqos activate "${ARGS[@]}" --phase native_onboarding --dry-run

Create the machine on Solana (owner wallet)

PEAQOS_OWS_WALLET=fleet-owner peaqos activate "${ARGS[@]}" --phase native_onboarding

When this confirms, the machine exists on Solana. The link back to peaq is a separate transaction that peaq’s side sends, not you. Rerun the same command to check on it: once the Solana creation is in the journal the CLI only reads, so it signs nothing and asks for nothing. Onboarding is finished once it reports "phase": "complete" under onboarding_state.evidence.stage.

Check

peaqos machine status <machine_id> --json --chain solana

You should see the Solana owner under identity. Under mirrors, subscription_terminal_status is "1" for active and subscription_terminal_tier is "1" for Basic or "2" for Pro. Both come back as strings.

For the next machine, go back to the top of Part 2 with the next serial number. The wallets and your .env are reused either way; a peaq machine can run from the same fleet folder, a Solana machine gets its own folder. Keep a list of serial number to machine_id as you go: the machine ID is how every later command, and peaq support, identifies the machine.

Part 3: After activation

Home on peaq
Home on Solana

Record what the machine does. Events are how a machine builds its credit history. An activity event says “I did work”; a revenue event says “I earned this much” (in the currency’s smallest unit, so cents for USD). qualify event submits straight away, with no preview and no confirmation prompt, so check the values before you run it.

peaqos qualify event --machine-id <machine_id> --type activity --value 0 \
  --ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
peaqos qualify mcr did:peaq:<machine_id>

The second command reads the machine’s credit rating.Manage it. peaqos machine covers the lifecycle: status, suspend, resume, subscription renew, transfer, and the did set-… commands to update the DID document. The two subscription writes prompt for confirmation but have no --dry-run. Details on CLI: machine.

Record what the machine does. Events go to the Solana EventRegistry program, signed by the owner wallet. The first event for a machine also creates its event-log account, so it costs a little extra rent.

PEAQOS_OWS_WALLET=fleet-owner peaqos qualify event --machine-id <machine_id> \
  --type activity --value 0 --ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)"

peaqos qualify mcr did:peaq:<machine_id> answers for a Solana-homed machine too. A fresh machine reads mcr: "Provisioned", mcr_score: 0 and rating_unavailable: "no_events_yet", with home_chain: 5 marking Solana; the score is computed once the MCR has indexed the machine’s Solana events.Manage it. Add --chain solana to the peaqos machine commands: status, suspend, resume, the did set-… commands, transfer --unsafe (Solana has no “safe transfer” variant, hence the flag) and set-evm-operator if you ever move the machine to a different peaq operator wallet. Details on CLI: machine.Renew it. The bond sits on peaq, so renewal runs there with the operator wallet and takes no --chain:

PEAQOS_OWS_WALLET=fleet-operator peaqos machine subscription renew <machine_id>

Sell its data. Both homes can package and sell machine data through Stream: peaqos stream publish encrypts and signs a data file, stream distribute delivers it to a buyer once their payment is confirmed, and stream grant hands a buyer access directly when you have checked payment yourself. Buyers pay with the native token or an ERC-20 on peaq or Base, or with SOL or an SPL token on Solana.

If something goes wrong

The CLI is designed so that a failed or interrupted step is safe to run again: it reads its journal first and never sends a duplicate transaction. Don’t delete peaqos.log, don’t change the arguments, and rerun the step.

On peaq

You see	What it means and what to do
`INSUFFICIENT_PEAQ` or a short-balance message	The wallet named in the message needs more funds. Top it up to the quoted amount plus gas and rerun.
A QR code and a prompt for a six-digit code	The signing wallet holds under 0.5 PEAQ, so the CLI is funding it for you through the Gas Station. Nothing has been quoted or spent on chain at this point. Either complete the enrollment, or fund the wallet yourself and rerun with `--skip-funding`. A preview does not run this step, so a wallet that previewed clean can still meet it on the real run.
`PENDING`	The transaction was sent but not yet confirmed when the CLI stopped waiting. Rerun the same command; it will report the outcome.
A run failed after its token approval confirmed	The approval stands and the next run skips it. It is for the exact amount quoted, never unlimited, and it is what bounds the transfer on chain on the rerun, because the activation call itself carries no spending limit when paying in PEAQ. USDT is capped in the call and is not affected.
Two machines from one wallet at once	Finish one machine before starting the next from the same wallet. The duplicate guard is per machine, so a still-pending activation and a fresh one can collide on the same nonce.
`RPC_FAILED` mentioning `isEconomicAuthority` or `fullMode`	Your CLI and the network’s contracts are on different versions. Run `pip install -U 'peaq-os-cli[solana,ows]>=0.0.12'` and try again.
`NOT_ECONOMIC_AUTHORITY`	Not a version problem. `TOKENOMICS_DEPLOYMENT_ID` in `.env` names a deployment that is not the economic authority. Set it to `peaq-mainnet`.
`QUOTE_MOVED`	The cost rose above the amount the preview showed. Rerun to see the current quote.
`ORACLE_UNPRICED`	The price oracle has no usable PEAQ price, so the bond cannot be quoted. Nothing local fixes it; try again later.
`TECHNICALLY_PAUSED`	The contracts are paused. It is caught before the quote, so nothing is spent. Try again later.
`peaqos init` stops at the Event Registry prompt	The address download failed. Type the Economics 2.0 address from the note in Part 1, `0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e`, then check the other addresses in `.env` against the install page tables.
`qualify mcr` answers `NOT_FOUND` with a 404	The rating service has not indexed the machine yet. It is not a wrong ID; try again later.

On Solana

You see	What it means and what to do
`QUOTE_MOVED`	The cost rose above the preview or above a ceiling you set. Raise `PEAQ_CAP`, which Pro needs, or rerun to see the current quote.
`STATE_MISMATCH` with `Select the accepted phase's wallet`	The wrong wallet for the phase, usually a missing `PEAQOS_OWS_WALLET=` prefix. Nothing was submitted. Reservation and subscription take the operator wallet, native onboarding the owner wallet.
A conflict about inputs, signer or account	The wallet or one of the fingerprinted arguments differs from the original attempt. Restore the saved values and the original `did.json` and rerun. If they are gone, the machine cannot be finished.
The final preview says a mirror or the subscription is still pending	Delivery to Solana has not landed yet. Run the preview again. If it stays pending for hours, contact peaq with your `machine_id`.
The machine was created but the link is not `complete`	Rerun `--phase native_onboarding`, which only reads at this point, until it reports `complete`. If it does not, contact peaq with your `machine_id`.
`RPC_FAILED`, `STATE_MISMATCH` or “reservation discovery is unavailable” while reading reservation history	Either the RPC or `HISTORY_START` is the problem, and the fix depends on which: follow resume after an interruption.

Exit codes: 1 means something in your input or a declined confirmation, 2 a chain or network failure, 3 a configuration problem such as a missing setting or extra. With --json, the error_code field says exactly which. Full tables live on CLI: exit codes and Solana onboarding: resume after an interruption.

Where to go next

Activate: what activation creates and why it is one transaction
Self-managed onboarding: the peaq flow from the SDKs instead of the CLI
Fleet onboarding with an operator: machines that own themselves while you operate them
Onboard a machine on Solana: every Solana flag, state and recovery path
Wallets (OWS), Install, Economics 2.0

Welcome

Get Started

Concepts

Functions

Guides

Onboarding quickstart

First decision: where should the machine live?

What it costs

Part 1: Set up once per fleet

Part 2: Activate each machine

Part 3: After activation

If something goes wrong

On peaq

On Solana

Where to go next

​First decision: where should the machine live?

​What it costs

​Part 1: Set up once per fleet

​Part 2: Activate each machine

​Part 3: After activation

​If something goes wrong

​On peaq

​On Solana

​Where to go next

First decision: where should the machine live?

What it costs

Part 1: Set up once per fleet

Part 2: Activate each machine

Part 3: After activation

If something goes wrong

On peaq

On Solana

Where to go next