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, PEAQ for the bond (40 USD per Pro machine per year, paid in PEAQ), and about half an hour for a first machine on peaq. A Solana onboarding took about 10 minutes in the proven production runs on top of that, because it goes through seven stages on two chains with waits in between. One command runs them all. 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, one transaction	One command, seven stages: register the owner wallet on peaq (once), pay the bond into a request on Solana, settle it, mint the machine, push the link back to peaq
Who finishes it	You, with one confirmed transaction	Your Solana wallet sends the link push, then peaq’s Trust Validator node (the node) delivers it on peaq, and the command waits for that delivery. Earlier in the run, the node credits the request and peaq books the bond on its own; the command waits for both
Wallets you need	One wallet, funded with PEAQ	Two: an operator wallet with a little PEAQ on peaq for one registration, and an owner wallet on Solana holding the bond (PEAQ or USDC) and SOL
Tiers available	Entry, Basic, Pro	Entry, Basic, Pro (the proven runs used Basic)
Where the bond is held	peaq	Paid on Solana by the owner wallet, in PEAQ or USDC, and booked on peaq
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	The opt-in is refused for a Solana-homed machine (`SOLANA_MONETIZATION_UNVERIFIED`)

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, Solana
Basic	$0.20	peaq, Solana
Pro	$40	peaq, Solana

The bond buys one 365-day subscription period, so budget it per machine per year. For a peaq-homed machine, renew with peaqos machine subscription renew <machine_id> before the period ends; the CLI and SDKs do not renew a Solana-homed machine. A renewal keeps the machine’s tier: --tier is refused with RENEWAL_TIER_UNSUPPORTED before anything is sent, so pick the tier at activation. After the period ends you get a 14-day grace period, then a 14-day runoff in which the bond decays to zero, and then the machine is terminated: on peaq its Machine NFT is burned; on Solana the machine’s accounts stay, with the subscription status mirrored to its terminal record. 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, about 0.3 PEAQ in the measured run). A Solana home works differently: the owner wallet pays the bond on Solana, in PEAQ (bridged to Solana) or in USDC, and peaq books it. On 2026-10-06 a Basic bond was 4.744535245 PEAQ, or 0.200807 USDC through the swap; the price moves with the oracle, and the preview prints yours. The owner also pays about 0.0081 SOL of rent and fees per machine with the DID document below (8,122,140 lamports paying in PEAQ, 8,125,140 paying in USDC; a larger document costs a little more), and the operator wallet pays about 0.01 PEAQ of gas once, for the owner wallet’s registration. There is no messaging fee: peaq’s Trust Validator node delivers the link push. On peaq, USDT settlement of the bond (--payment usdt) is not configured on peaq mainnet; pay the bond in PEAQ. Gas on peaq 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]'
peaqos --version

You should see the CLI version and the SDK version it runs on. For a Solana home it must be CLI 0.0.19 or newer on SDK 0.11.2 or newer (0.0.17 and 0.0.18 onboard, but cannot send the machine’s events (0.0.17) or manage it (0.0.18) afterwards). Older releases implement a Solana flow that the current programs no longer accept. 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 and keep the deployment peaq-mainnet. For a Solana home, enter your own provider’s peaq RPC endpoint when it asks for the RPC URL; the public endpoint rate-limits a Solana run. When offered, choose wallet as the key source; it creates an encrypted wallet rather than a raw key. Name the wallet 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, including the Event Registry address (the wizard fills in the Economics 2.0 contract, 0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e). It fills in the contract addresses from its network defaults and finishes by running peaqos whoami to show what it wrote.

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: it signs one registration per owner wallet, which binds the owner to it, and becomes the operator that owns the machines’ points and revenue on peaq. The wizard already created it as fleet-operator. The owner wallet acts on Solana: it pays the bond, in PEAQ or USDC, plus rent and fees in SOL, and signs every Solana transaction. One pair can serve your whole fleet.

peaqos wallet create fleet-owner
peaqos wallet export fleet-owner        # store the seed phrase now
peaqos wallet show fleet-operator --json
peaqos wallet show fleet-owner --json

create asks for a passphrase for the new wallet. Give it the same passphrase as fleet-operator: the onboarding command signs with both wallets in one run and asks for each wallet’s passphrase when it first needs it, so one shared passphrase is one value to remember (or one OWS_PASSPHRASE variable in a script). Fund them:

fleet-operator, the 0x… address from the first show: 0.05 PEAQ on peaq covers the registration gas (about 0.01 PEAQ, paid once).
fleet-owner, the Solana (base58) address from the second: the bond per machine in the token you will pay with, plus a little headroom, and at least 0.015 SOL per machine. For PEAQ, that is PEAQ on Solana (the OFT mint PEAQjk7SRS6rXHVFFmpRr7zrC4g5ZuEebpwTxvaLr3b), bridged over or bought there. For USDC, Solana USDC. A Basic bond was 4.74 PEAQ or 0.20 USDC on 2026-10-06; the preview prints the current figure.

Then tell the CLI which Solana network and RPC to use by adding two lines to .env:

PEAQOS_SVM_NETWORK=mainnet-beta
PEAQOS_SVM_RPC_URL=<your Solana RPC endpoint>

Any Solana RPC provider works here. The public https://api.mainnet-beta.solana.com works too: all six proven production runs used it, and the CLI waits out its rate limits and its lagging servers on reads, and warns once at the start of every run that writes. It can be slow to show fresh transactions, so a run against it occasionally stops and needs a rerun; a provider endpoint avoids that. The peaq endpoint in .env matters more: an onboarding makes bursts of peaq reads that the public peaq endpoints rate-limit (RPC_RATE_LIMITED), so set PEAQOS_RPC_URL to an endpoint from your own provider.

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. Replace the example URLs below with your own before you activate: they are written on chain and shown on the machine’s public MCR profile.For a first fleet, point the verification method at the wallet that will own the machines. publicKeyMultibase carries the verifying key in multibase form (z6Mk… for an Ed25519 key). No peaqos command prints it.

Home on peaq
Home on Solana

Set controller to the 0x… address of fleet-owner (from peaqos wallet show fleet-owner --json). The CLI accepts only a 0x address with 40 hex characters here.publicKeyMultibase takes an Ed25519 public key, and the 0x… address cannot give you one: it is a hash of the wallet’s key, not the key itself. If the machine already has an Ed25519 key, use its public key. Otherwise generate one. Run pip install base58 first (the CLI does not install it):

python3 -c 'import nacl.signing,base58,os; k=nacl.signing.SigningKey.generate(); fd=os.open("machine-ed25519.key",os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600); os.write(fd,bytes(k)); os.close(fd); print("z"+base58.b58encode(b"\xed\x01"+bytes(k.verify_key)).decode())'

It prints the z6Mk… value for publicKeyMultibase and writes the private key to machine-ed25519.key, readable only by your user. It refuses to overwrite an existing file. Keep that file safe: it is the key the verification method names.The value is stored exactly as you write it and nothing checks it. One key per machine is the clean setup. The chain does not reject a repeated key, so a first fleet can share one key through the template and give each machine its own later with peaqos machine did set-verification-methods.

Set controller to the base58 address of fleet-owner, the Solana owner wallet. The CLI accepts only a base58 public key that decodes to 32 bytes here, so a 0x… address is rejected.A Solana address is itself an Ed25519 public key, so compute publicKeyMultibase from that same address. Run pip install base58 first; the CLI does not install it:

python3 -c 'import base58,sys; k=base58.b58decode(sys.argv[1]); print("z"+base58.b58encode(b"\xed\x01"+k).decode())' <fleet-owner Solana address>

It prints a z6Mk… value. Nothing on chain checks it against the address. Every string in the DID document must stay within 128 bytes; the full limits are on the Solana page.

did.json

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

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. Use the serial exactly as printed on the unit and decide the format once for the fleet (case, leading zeros, no spaces): a one-character difference is a different machine for good. 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 seven stages on two chains, and one command runs them all. The operator wallet registers the owner wallet on peaq (first machine only). The owner wallet pays the bond into a request on Solana and settles the request. peaq books the bond. Then the owner wallet mints the machine and pushes the link back to peaq, where peaq’s Trust Validator node (the node) delivers it. Give each Solana machine its own working folder, so that its journal peaqos.log, its run record and its saved arguments stay together. The journal itself is scoped by machine ID. From the fleet folder:

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

If you come back to this folder in a new terminal, activate the virtual environment and source machine.vars (written in the next step) instead of pasting the variable block again; then rebuild ARGS.

Fill in the argument set

The two ceilings are limits the CLI will not exceed, not prices. A ceiling below the real cost refuses the stage before signing instead of warning. They are the ones the proven runs used. The block has # comments: paste it into bash, or run setopt interactive_comments first in an interactive zsh.

OWNER=<fleet-owner Solana address>
MANUFACTURER=<a Solana address to record as the maker>   # recorded, never verified; the owner address is fine
MACHINE_TYPE=<one word for the fleet>    # with the serial it fixes the machine ID for good, so pick it once
PAY_IN=PEAQ                              # or USDC
printf '%s=%q\n' OWNER "$OWNER" MANUFACTURER "$MANUFACTURER" MACHINE_TYPE "$MACHINE_TYPE" \
  CREDENTIAL_SUBJECT_HEX "$CREDENTIAL_SUBJECT_HEX" PAY_IN "$PAY_IN" > machine.vars
cat machine.vars

Check that every line has a value. OWNER must be the base58 address that peaqos wallet show fleet-owner printed: the request records it as the payer, and the mint and the link push need the same wallet. machine.vars keeps the values for a later terminal (source machine.vars).Then build the argument set. The escrow, --max-in, is added after the preview in the next step, which suggests it. For a Pro machine, change --tier basic to --tier pro. Every Solana write pays the default priority price of 10,000 micro-lamports per compute unit (about 4,900 lamports across a PEAQ onboarding, about 7,900 on USDC). Keep it: a write without priority can be dropped. The mint’s compute limit is sized from its simulation, so the consent quotes the fee the mint will pay (CLI 0.0.17 or newer). What each flag means: the argument set.

ARGS=(
  --chain solana
  --solana-owner "$OWNER" --manufacturer "$MANUFACTURER"
  --machine-type "$MACHINE_TYPE" --credential-subject-hex "$CREDENTIAL_SUBJECT_HEX"
  --tier basic --did-document ./did.json
  --pay-in "$PAY_IN"
  --max-native-fee-lamports 50000 --max-native-rent-lamports 6000000
  --timeout-seconds 300
)

Keep the identity, the owner wallet, the DID document, the tier, the rail, MAX_IN and the two ceilings unchanged between runs of one machine. The SDK fingerprints every onboarding input (identity, owner, controller, manufacturer, DID document and the two ceilings), so a changed one stops the next stage; the request freezes the tier, the rail and the escrow when it opens. Do not upgrade the CLI or the SDK in the middle of onboarding a machine either. Details: what stays fixed.

Preview the whole plan

No wallet needed, nothing is sent. The preview is one screen: whether the owner wallet is registered yet, the bond, the escrow it suggests against what the owner holds, the rents and the seven stages. Check that the owner holds at least the suggested escrow and the SOL.

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

It ends with Run it with --max-in <N>. Add that escrow to the argument set and save it with the other values:

MAX_IN=<the suggested escrow>
printf 'MAX_IN=%q\n' "$MAX_IN" >> machine.vars
ARGS+=(--max-in "$MAX_IN")

In a later terminal, source machine.vars, paste the ARGS=(...) block and run the ARGS+= line again.On PEAQ the escrow is the bond plus a 1% cushion; what the bond does not use comes back at settlement. On USDC it covers the swap’s estimated cost with the same cushion, and the remainder comes back in USDC.

Run the onboarding

This command runs all seven stages with both wallets. It prints a plan block, then each stage’s terms (signer, every amount in base units with the exact token figure, each cap) and asks you to confirm it (add --yes in a script). It asks for each wallet’s passphrase when it first needs it (or reads OWS_PASSPHRASE). After each confirmed stage it prints an indented landed after 1 send line (the mint’s also shows its compute use). A send the network dropped is sent again with the same signed bytes while it can still land, so a higher count never means a second payment. While the command waits, it prints a “still waiting” line every two minutes and “landed in …” when a wait ends. The proven runs took about 10 minutes.

peaqos activate "${ARGS[@]}" \
  --operator-wallet fleet-operator --owner-wallet fleet-owner \
  --wait-minutes 60

There is no link fee to cap: production’s link push goes to peaq’s Trust Validator node, with no messaging fee. It ends with a summary: the machine_id, every transaction reference, link seq 1 applied, and a Spent block read from the receipts (what the operator paid on peaq, what the owner paid on Solana). Done means exit 0; with --json, jq -r .next_step.phase on the output reads complete. Keep the machine_id; it stays the same for every later command. The folder now also holds onboarding-<machine_id>.json, a record of the run.If the command stops before complete (its wait budget ran out, you pressed Ctrl-C, the connection dropped), nothing is lost and nothing is paid twice: run the same command again. It reads its journal, skips every stage that already landed and continues from the first unfinished one. The output also prints the command to run next as resume_command.

Check

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

machine history lists every transaction of the onboarding on both chains, who sent it and what it cost, from the chains alone; the link push’s delivery reads node. In machine status, identity shows the Solana owner and the link block shows peaq’s watermark for the machine; that watermark is what made the run complete.

Running one stage at a time with --phase, interrupted runs, state reads and the Python and JavaScript scripts are in Onboard a machine on Solana.

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. For a fleet on Solana, run the machines one after another, each in its own folder. The owner wallet’s registration is sent once, by the first machine; every later machine reconciles it and sends nothing on peaq. At about 10 minutes per machine, 28 machines take about 5 hours; script Part 2 per serial with --yes --json and OWS_PASSPHRASE exported, write each run’s JSON to a file in the machine’s folder, and read machine_id and spent from there.

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). On peaq, qualify event submits straight away, with no preview and no confirmation prompt, so check the values before you run it (--dry-run previews native Solana submissions only).

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 buys one 365-day period, the same as on peaq. Renewing a Solana-homed machine is not covered on these pages yet; check this guide again before its period ends.

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 reconciles a pending transaction instead of sending it twice. Don’t delete peaqos.log, don’t change the arguments, and rerun the step. For peaqos machine writes this covers pending writes only: once a write is recorded as confirmed, running the same command again is a new write (a second subscription renew pays again), so check machine status before repeating one that already went through. A Solana onboarding run is different: every confirmed phase is reconciled from the journal and never sent again, so rerunning it with the same inputs never pays twice.

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.
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.
`NOT_ECONOMIC_AUTHORITY`	`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.
`RENEWAL_TIER_UNSUPPORTED` on `subscription renew --tier`	A renewal cannot change the tier. Run it again without `--tier`; it renews at the machine’s current tier. Nothing was sent.
`peaqos init` stops at the Event Registry prompt	On agung the prompt has no default. Agung has no Economics 2.0 EventRegistry, so `peaqos qualify event` for a 2.0 machine needs peaq mainnet. To finish `peaqos init` on agung, type the agung Tokenomics 1.0 `EVENT_REGISTRY_ADDRESS` from the agung contract tables, `0x2DAD8905380993940e340C5cE6d313d5c2780040`, then check the other addresses in `.env` against the same tables.
`qualify mcr` answers `NOT_FOUND` with a 404	Either the machine ID is wrong or not registered on this deployment, or the rating service has not indexed the machine yet. Check the ID with `machine status` first; if it is registered, try again later.

On Solana

You see	What it means and what to do
`PENDING` (exit `2`) after the wait, naming `credit` or `bond`	peaq’s node has not committed the credit, or peaq has not booked the bond, yet. The credit landed within about 2 minutes and the bond within about 5 in the proven runs; the command stops waiting after 3 and 6 minutes, whatever `--wait-minutes` says. Rerun the command; it continues waiting. If nothing has moved after 30 minutes, the node may be down: post your `machine_id` in the peaq Discord. peaq’s Trust Validator node (the node) can stall for hours; it did on 2026-10-07 and again on 2026-10-08. While the node is stalled, every Solana onboarding stops at `[3/7]` with `PENDING`. The request expires after an hour; once the node is back it cancels and refunds the request (or you cancel it with `--phase cancel_request`), and the rerun opens a new request. Nothing is lost: the escrow and the rents come back.
`PENDING` after the wait, naming `link_application`	The node has not delivered your link push on peaq yet. Rerun the command; the push is never sent twice.
`REQUEST_EXPIRED`	The node did not credit the request within its hour, so it can no longer settle. Nothing was settled. The node cancels it on its own once it is back, returning the escrow and the request’s rents; or cancel it yourself with `peaqos activate "${ARGS[@]}" --phase cancel_request --owner-wallet fleet-owner`, which prints `Cancel request on Solana: confirmed <signature>`. Then rerun the command: it opens a new request, even though `peaqos.log` still holds the old one (CLI 0.0.17 or newer; before, the rerun could take the old request for a live one and stop at `[3/7]` with `ActivationRequest absent`).
`COMMIT_EXPIRED`	The credit expired before the settlement. Nothing was settled. Cancel as above, then rerun.
`REQUEST_CLOSED`	You ran a single `--phase` (`finalise` or `cancel_request`) on a request that had already been cancelled or refunded. Nothing was signed. Rerun the command without `--phase`: it opens a new request.
`ESCROW_BELOW_BOND` or `INSUFFICIENT_BALANCE`	`MAX_IN` is below the bond, or the owner wallet holds less than `MAX_IN` in the pay-in token on Solana. Nothing was signed. Take the preview’s suggested `--max-in`, or fund the owner wallet, and rerun.
`ACTIVATION_REFUNDED`	peaq refused the bond after the settlement; the Trust Validator returned it in PEAQ to the owner wallet. Rerun the command: it opens a new request.
`INSUFFICIENT_SOL`	The owner wallet cannot pay a write’s fee and rent and still keep its own minimum balance. Nothing was signed. Top up its SOL and rerun.
A stage that stays unconfirmed for minutes after “signed and journaled”	The transaction may have been dropped before landing. While its blockhash is still valid (about 80 s), the SDK re-sends the same signed bytes on its own (SDK 0.11.2 or newer). After that, rerun once: the rerun reconciles the journaled transaction and does not sign it again. A request, settlement or cancellation that failed, or expired without landing, is replaced by a fresh one. A mint that never landed is proven dead and minted again on the next run (since CLI 0.0.16; the dead signature is printed as `expired`), and so is a mint that ran out of compute and created nothing (CLI 0.0.17 or newer). A link push is never signed again. If it still reads unconfirmed, post your `machine_id` in the peaq Discord.
`STATE_MISMATCH` with `Select the accepted phase's wallet`	The wrong wallet for the stage, usually when running single stages. Nothing was submitted. The registration takes the operator wallet, every Solana write the owner wallet.
A conflict about inputs, signer or account	The wallet or one of the fingerprinted arguments differs from the original run. Restore the saved values and the original `did.json` and rerun.
`MACHINE_ALREADY_ACTIVE` in the preview	The machine type and serial pair is already a machine with a subscription, and a pair cannot be activated twice. If it is not one you onboarded, change the serial format or the machine type and start again with a new folder.
`OPTION_NOT_FOR_CHAIN`	An option of the old reservation flow (`--payment`, `--max-net-peaq-amount`). The error names the replacement (`--pay-in`, `--max-in`).
`TECHNICALLY_PAUSED`	The programs are mid-upgrade. Nothing was signed. Rerun later; the preview shows `upgrade lock released` once it is over.
`RPC_RATE_LIMITED`, or `RPC_FAILED` naming `-32016`	An endpoint kept rate-limiting reads, or a Solana server behind the chain kept answering. Rerun; if it repeats, switch `PEAQOS_RPC_URL` (or the Solana endpoint) to one from your own provider. Nothing was sent twice.

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 and troubleshoot.

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