> ## Documentation Index > Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Onboarding quickstart > Get a machine, or a whole fleet, onto peaqOS from the terminal: install the CLI, set up wallets, activate on peaq or on Solana, and know what to do next. export const KeyTerms = ({all = {}, ids = [], title = "Key terms in this guide"}) =>
{title}
{ids.map(id => { const t = all[id] || ({}); return
{t.term}. {t.def}
; })}
; export const G = { onchain: { id: "onchain", cat: "chain-infra", term: "On-chain vs off-chain", def: "On-chain means written to the shared public ledger every machine agrees on: permanent and readable by anyone. Off-chain means kept on a normal private server instead." }, blockchain: { id: "blockchain", cat: "chain-infra", term: "Chain / blockchain", def: "A shared, tamper-resistant public database maintained by a whole network of computers with no single owner. Different chains are separate such networks." }, peaqChain: { id: "peaqChain", cat: "chain-infra", term: "peaq chain", def: "The machine-focused blockchain peaqOS uses as home base for identity and credit records." }, transaction: { id: "transaction", cat: "chain-infra", term: "Transaction (tx) / tx hash", def: "A single signed request that changes the ledger. Its hash is a unique, receipt-like ID you can use to look it up later." }, rpcUrl: { id: "rpcUrl", cat: "chain-infra", term: "RPC URL / endpoint", def: "The network address your code calls to read from or write to a chain, like the base URL of the chain's API server." }, mainnet: { id: "mainnet", cat: "chain-infra", term: "Mainnet / testnet (agung)", def: "Mainnet is the real, live network where tokens have real value. Testnet is a free practice copy with worthless tokens; peaq's is called agung." }, evm: { id: "evm", cat: "chain-infra", term: "EVM / EVM-compatible", def: "The Ethereum Virtual Machine: the standard runtime many chains share, so the same 0x... addresses and tools work across all of them. peaq is EVM-compatible." }, node: { id: "node", cat: "chain-infra", term: "Node (RPC node)", def: "A server running the blockchain software that holds a copy of the ledger and answers queries. NOT a ROS 2 node, despite the shared word." }, chainId: { id: "chainId", cat: "chain-infra", term: "Chain ID", def: "A number that uniquely labels a chain so software doesn't confuse networks (peaq is 3338, Base is 8453)." }, precompile: { id: "precompile", cat: "chain-infra", term: "Precompile", def: "A built-in function baked into the chain at a fixed address that acts like a contract but runs as faster native code. The batch one bundles several actions into one all-or-nothing transaction." }, dataHash: { id: "dataHash", cat: "chain-infra", term: "Data hash (keccak256)", def: "A short, fixed-length fingerprint of a file, stored on-chain instead of the file itself, so data can be verified later while the raw data stays off-chain." }, wallet: { id: "wallet", cat: "wallet-keys", term: "Wallet", def: "An account on the chain, identified by a public address, that holds a machine's funds and approves its actions. Really just a pair of keys, not a place money is stored." }, keypair: { id: "keypair", cat: "wallet-keys", term: "Keypair", def: "The two matched secrets behind a wallet: a public address you can share, and a private key you keep secret that signs actions." }, privateKey: { id: "privateKey", cat: "wallet-keys", term: "Private key", def: "The secret string that proves you control a wallet. Anyone who has it has full control, like a master password that can never be reset." }, sign: { id: "sign", cat: "wallet-keys", term: "Sign / signature", def: "Using your private key to produce a cryptographic stamp proving you approved a specific action, without ever revealing the key." }, signer: { id: "signer", cat: "wallet-keys", term: "Signer / signing identity", def: "The wallet whose private key authorizes an action: the account the network treats as the one taking it. NOT a file or an app." }, address: { id: "address", cat: "wallet-keys", term: "Address (0x...)", def: "The public 0x... identifier of a wallet or contract you can freely share so others can send to it or look it up, like an account number." }, eoa: { id: "eoa", cat: "wallet-keys", term: "EOA (externally owned account)", def: "A plain wallet controlled directly by a private key, as opposed to one controlled by code. Here, the account that IS the machine." }, ows: { id: "ows", cat: "wallet-keys", term: "OWS / wallet vault", def: "An open standard for storing wallet keys in an encrypted local file (a vault) with a backup phrase and an activity log, instead of a bare key in a text file." }, passphrase: { id: "passphrase", cat: "wallet-keys", term: "Passphrase (OWS_PASSPHRASE)", def: "The password that unlocks the encrypted wallet vault so its key can be used to sign." }, mnemonic: { id: "mnemonic", cat: "wallet-keys", term: "Mnemonic / seed phrase", def: "A list of 12 or 24 ordinary words that encodes a wallet's secret key, used to back it up and recover it. Whoever has the words controls the wallet." }, derivation: { id: "derivation", cat: "wallet-keys", term: "Derivation path", def: "The deterministic recipe that turns one backup phrase into many specific keys and addresses, one per network or index." }, challenge: { id: "challenge", cat: "wallet-keys", term: "Challenge (sign-to-prove)", def: "A login-style handshake: the server sends a random message, you sign it with your key, and the signature proves you control the account without sending the key." }, eip191: { id: "eip191", cat: "wallet-keys", term: "EIP-191 / personal_sign", def: "A standard way to sign a plain message to prove you control an account, without sending any on-chain transaction." }, did: { id: "did", cat: "identity", term: "DID / peaqID", def: "A globally unique, self-owned ID for a machine that lives on the chain and isn't issued by any single company. peaqID is peaq's version, written did:peaq:0x..." }, register: { id: "register", cat: "identity", term: "Register a machine", def: "Putting a machine on the network for the first time, which gives it an ID, a DID, an ownership token, and a locked deposit. Under Economics 2.0 this is one activateMachine call signed by the machine's owner; registerMachine and registerFor are the older Tokenomics 1.0 calls." }, machineId: { id: "machineId", cat: "identity", term: "Machine ID", def: "Your machine's handle in every later call. Under Economics 2.0 it is derived from the machine type and credential subject (a large uint256, written as a decimal string); Tokenomics 1.0 machines got a small sequential number." }, ownerOperator: { id: "ownerOperator", cat: "identity", term: "Owner / operator", def: "The owner owns a machine; the operator runs it. They can be the same account (self-managed) or different (proxy-managed)." }, proxyOperator: { id: "proxyOperator", cat: "identity", term: "Proxy operator", def: "One account that registers and manages many machines on behalf of their owners, so a fleet operator can handle a whole fleet from one wallet." }, didAttributes: { id: "didAttributes", cat: "identity", term: "DID attributes", def: "Public name-value facts (a docs link, a data endpoint) attached to a machine's DID and stored on-chain for anyone to read. Writing them is a separate transaction from registration." }, pairing: { id: "pairing", cat: "identity", term: "Pairing / pairing token", def: "The verified link between an AI agent and a machine, set up by signing a challenge. The pairing token is the signed credential the agent sends with each request, like a temporary access badge." }, hardwareAttestation: { id: "hardwareAttestation", cat: "identity", term: "Hardware attestation", def: "A tamper-resistant chip on the machine cryptographically vouching that it's genuine hardware, so its identity can't be faked in software. This is the Verify layer." }, gas: { id: "gas", cat: "tokens-economics", term: "Gas", def: "The small fee, paid in the chain's token, that every action writing to the ledger costs, like a per-write transaction cost." }, peaqToken: { id: "peaqToken", cat: "tokens-economics", term: "PEAQ (token)", def: "The peaq network's own token, used to pay gas fees and to lock up as the deposit when registering a machine." }, gasStation: { id: "gasStation", cat: "tokens-economics", term: "Gas Station / faucet", def: "A peaq service that hands a brand-new, empty wallet a tiny starting amount of tokens so it can afford its first network fees. Gated by 2FA." }, bond: { id: "bond", cat: "tokens-economics", term: "Bond", def: "PEAQ locked when a machine activates, proving skin in the game. Under Economics 2.0 it is priced per tier in USD and converted to PEAQ at the oracle rate, and it is not withdrawable; Tokenomics 1.0 machines locked a fixed 1 PEAQ. Bonded means the deposit is in place." }, nft: { id: "nft", cat: "tokens-economics", term: "NFT", def: "A unique, one-of-a-kind ownership token recorded on the chain. Unlike a coin, no two are interchangeable." }, mint: { id: "mint", cat: "tokens-economics", term: "Mint / minting", def: "Creating a brand-new token on the chain and assigning it to an owner, like stamping a fresh serial-numbered certificate into existence." }, machineNft: { id: "machineNft", cat: "tokens-economics", term: "Machine NFT", def: "The unique token representing one specific physical machine and its financial profile. It can be sold or bridged on its own, separate from the machine's identity." }, identityNft: { id: "identityNft", cat: "tokens-economics", term: "Identity NFT", def: "A non-transferable (soulbound) token minted automatically when a machine registers, representing its identity. Its token ID equals the machine ID." }, tokenId: { id: "tokenId", cat: "tokens-economics", term: "Token ID", def: "The unique number identifying one specific token within a collection, like a serial number." }, mcr: { id: "mcr", cat: "tokens-economics", term: "Machine Credit Rating (MCR)", def: "A creditworthiness score for a machine (a Moody's-style grade AAA down to NR, plus a 0-100 number) computed from its recorded earnings and activity. Like a credit score for a robot." }, mcrApi: { id: "mcrApi", cat: "tokens-economics", term: "MCR API", def: "The public web service you call to fetch a machine's credit score and profile as JSON, and the one place a machine's monetization is switched on or off with a signed message. No login needed: reads are open, and the write is authorized by the signature itself." }, provisioned: { id: "provisioned", cat: "tokens-economics", term: "Provisioned / NR (Not Rated)", def: "Early MCR statuses. Provisioned means registered and bonded but with too little history to score yet. NR means no grade, because the score is too low or the machine isn't bonded." }, event: { id: "event", cat: "tokens-economics", term: "Event (revenue / activity)", def: "A recorded data point about a machine's work, submitted to the chain to feed its credit score. Revenue events report money earned; activity events report work with no money. NOT a ROS topic message." }, trustLevel: { id: "trustLevel", cat: "tokens-economics", term: "Trust level", def: "A label on each submitted event saying how strongly its truth is backed: the machine's word (0), a checkable on-chain record (1), or tamper-proof hardware proof (2)." }, escrow: { id: "escrow", cat: "tokens-economics", term: "Escrow", def: "Holding a buyer's payment in a neutral locked place until the service is delivered, then releasing it, so neither side has to trust the other first." }, paymentRail: { id: "paymentRail", cat: "tokens-economics", term: "Payment rail", def: "The specific method or channel a payment moves through, like choosing card vs bank transfer vs a particular token." }, x402: { id: "x402", cat: "tokens-economics", term: "x402", def: "A web payment standard where a server answers 'payment required' with exact instructions, and the buyer's wallet signs an authorization instead of sending a separate transaction — built for machines and agents paying per request." }, usdt: { id: "usdt", cat: "tokens-economics", term: "USDT", def: "A stablecoin token meant to hold a value of one US dollar, used to pay service providers without price swings." }, fractionalize: { id: "fractionalize", cat: "tokens-economics", term: "Fractionalize (ERC-3643)", def: "Splitting ownership of one machine into many small tradable shares so multiple people can each own a piece. ERC-3643 is the regulated-securities token standard used to do it." }, smartContract: { id: "smartContract", cat: "smart-contracts", term: "Smart contract / contract address", def: "A program deployed on the chain that runs exactly as written and that anyone can call, identified by its own 0x... address." }, registryContracts: { id: "registryContracts", cat: "smart-contracts", term: "Registry contracts", def: "On-chain programs that each keep an official, lookup-able list: IdentityRegistry tracks which machines exist, EventRegistry stores their events, IdentityStaking holds their deposits." }, smartAccount: { id: "smartAccount", cat: "smart-contracts", term: "Smart account (ERC-4337)", def: "A programmable wallet controlled by code instead of a single key, so it can enforce rules like spending limits. Each machine gets one at activation." }, submitEvent: { id: "submitEvent", cat: "smart-contracts", term: "submitEvent / batchSubmitEvents", def: "The calls that record one or many of a machine's revenue or activity entries onto the chain." }, revert: { id: "revert", cat: "smart-contracts", term: "Revert", def: "When an on-chain call is rejected and fully undone because a rule was broken, leaving no changes and usually a named error." }, soulbound: { id: "soulbound", cat: "smart-contracts", term: "Soulbound", def: "A token that can never be transferred or sold and stays permanently attached to one owner. The Identity NFT is soulbound." }, bridge: { id: "bridge", cat: "cross-chain", term: "Bridge / bridging", def: "Moving a token from one chain to another, so the same Machine NFT can exist on a different chain. peaq and Base are live today; bridging is mainnet-only." }, base: { id: "base", cat: "cross-chain", term: "Base", def: "Another blockchain network (built by Coinbase) that peaqOS can move Machine NFTs to and from. Paying fees on Base needs Base ETH." }, omniChain: { id: "omniChain", cat: "cross-chain", term: "Omni-chain / cross-chain", def: "Working across many separate chains at once, so a machine's identity and credit created on peaq can be read or used on other chains." }, homeChain: { id: "homeChain", cat: "cross-chain", term: "Home chain", def: "The chain where a record's canonical, authoritative copy lives. For a peaqOS machine that is peaq, or Solana for an Economics 2.0 machine created there; other chains hold mirrors. The subscription bond stays on peaq either way." }, satelliteChain: { id: "satelliteChain", cat: "cross-chain", term: "Satellite chain", def: "A chain carrying a read-only, automatically synced mirror of home-chain records, so apps there can use them without crossing back to the home chain." }, sourceChainId: { id: "sourceChainId", cat: "cross-chain", term: "sourceChainId / sourceTxHash", def: "Two fields recording which chain an action happened on and its hash there, so a cross-chain event can be traced back and verified." }, machineAgent: { id: "machineAgent", cat: "general-web3", term: "Machine Agent", def: "A third-party AI program (Claude, OpenAI, a custom bot) paired to a machine and given limited permission to find, buy, and pay for services on its behalf." }, delegationPolicy: { id: "delegationPolicy", cat: "general-web3", term: "Delegation policy", def: "The rules an owner gives an AI agent that cap how much it can spend per transaction and per day and which services it may use, so it transacts within guardrails." }, machineMarkets: { id: "machineMarkets", cat: "general-web3", term: "Machine Markets / Service Registry", def: "peaqOS's marketplace where machines list services they offer (Service Registry) and where agents discover, order, pay for, and run services from others." }, sdk: { id: "sdk", cat: "general-web3", term: "SDK (peaq-os-sdk)", def: "peaq's code library (Python and JS) you install to call all this functionality without writing low-level blockchain calls yourself." }, stream: { id: "stream", cat: "data-stream", term: "Stream (Data-as-a-Service)", def: "The peaqOS function where a machine sells the data it generates: it signs the data, encrypts what's sensitive, and grants buyers access. Selling data, as opposed to selling capacity (that's Monetize)." }, edgeAgent: { id: "edgeAgent", cat: "data-stream", term: "peaqOS Edge Agent", def: "Software that runs on the machine itself (as a ROS 2 node) and signs, encrypts, and ships the data it produces. The on-machine half of Stream." }, dataPackage: { id: "dataPackage", cat: "data-stream", term: "Signed data package", def: "A bundle of machine data stamped with the machine's identity (DID, timestamp, sequence number) and a signature, so anyone can prove which machine produced it and that it wasn't altered." }, dataEventMap: { id: "dataEventMap", cat: "data-stream", term: "Data Event Map", def: "The policy file a machine owner writes to control what streams out: which topics to read, which fields to keep, drop, or encrypt, and where the signed data goes." }, chunk: { id: "chunk", cat: "data-stream", term: "Chunk", def: "A bounded, individually encrypted slice of a data stream (by time window or size). The unit a buyer actually purchases and decrypts." }, chunkChain: { id: "chunkChain", cat: "data-stream", term: "Chunk chain", def: "A run of chunks linked in order, each referencing the one before it, so missing, reordered, or edited chunks are detectable. Tamper-evidence for a continuous stream." }, manifest: { id: "manifest", cat: "data-stream", term: "Manifest", def: "A signed record describing a chunk or dataset — its hashes, storage location, and encryption details — without the data itself. Buyers verify the manifest before trusting or buying." }, dataset: { id: "dataset", cat: "data-stream", term: "Dataset", def: "A group of chunks for one topic and time range, packaged for sale with a single fingerprint (a Merkle root) that covers every chunk in it." }, merkleRoot: { id: "merkleRoot", cat: "data-stream", term: "Merkle root", def: "One short hash that stands in for a whole set of items, letting you later prove a specific chunk belongs to a dataset without revealing the rest." }, envelopeEncryption: { id: "envelopeEncryption", cat: "data-stream", term: "Envelope encryption / key wrapping", def: "Encrypt the data once with a random key, then lock that key separately for each authorized reader. Granting a buyer access re-locks the key to their public key — the data itself is never re-encrypted." }, accessGrant: { id: "accessGrant", cat: "data-stream", term: "Access grant", def: "What a buyer receives after paying: the chunk keys they bought, each locked to their public key. They unlock with their private key and decrypt only those chunks." }, contextProvider: { id: "contextProvider", cat: "data-stream", term: "Context Provider", def: "A third party that buys machine data, normalizes it into datasets, and serves or resells it (for example, for AI training). The buyer side of Stream, such as DataHive." }, computeProvider: { id: "computeProvider", cat: "monetize", term: "Compute provider", def: "A machine that rents out its processing power to a compute network. Instead of sitting idle, the machine runs other people's workloads and earns for it." }, provisioningManifest: { id: "provisioningManifest", cat: "monetize", term: "Provisioning manifest", def: "A published, step-by-step install plan that turns a machine into a compute provider: the checks to run first, the commands to execute, and the probes that prove it worked. The machine pulls it on demand and runs it locally." }, heartbeat: { id: "heartbeat", cat: "monetize", term: "Heartbeat", def: "A short signed 'I'm here' message a machine sends out at a regular interval. As long as heartbeats keep arriving, the machine counts as online; if they stop, it's marked offline automatically." }, aggregator: { id: "aggregator", cat: "monetize", term: "Aggregator", def: "A network that pools capacity from many machines and sells it on, such as a decentralized compute marketplace. Machines connect to an aggregator, which then dispatches work to them." }, machineWallet: { id: "machineWallet", cat: "monetize", term: "Machine wallet", def: "The wallet that belongs to the machine itself, separate from its owner's or operator's wallet. Earnings from the machine's work land here by default." }, walrus: { id: "walrus", cat: "chain-infra", term: "Walrus", def: "A decentralized storage network where encrypted data chunks can be parked, referenced by walrus:// links. The data stays off the blockchain; only its reference and fingerprint are tracked on-chain." }, solana: { id: "solana", cat: "cross-chain", term: "Solana", def: "A high-throughput blockchain. peaqOS wallets hold a Solana account and sign Solana transactions, machine-economy payments can settle there, and an Economics 2.0 machine can be homed there (identity, DID and NFT as Solana accounts, bond on peaq)." } }; Onboarding a machine to peaqOS gives it a permanent identity (a peaqID), an ownership record (a Machine NFT) and a subscription bond 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/functions/activate), [peaqOS CLI](/peaqos/cli), [Onboard a machine on Solana](/peaqos/guides/onboard-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 ` 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](/peaqos/concepts/economics-2-0#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](/peaqos/guides/onboard-on-solana#the-argument-set). Gas is always PEAQ. Bonds are not withdrawable. Prices and the formula are on [Economics 2.0](/peaqos/concepts/economics-2-0#tiers). ## Part 1: Set up once per fleet Everything in this part you do once, and every machine you onboard afterwards reuses it. You need Python 3.10 or newer. Installing into a virtual environment keeps it separate from anything else on your machine. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} 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. 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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} 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. Wallets live in the OWS vault at `~/.ows/`, each protected by its own passphrase. For each wallet, run `peaqos wallet export ` 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. 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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} 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](/peaqos/guides/proxy-operator-fleet) 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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} 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`: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} 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. 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`. ```json did.json theme={"theme":{"light":"github-light-default","dark":"github-dark"}} { "verificationMethods": [ { "id": "#key-1", "methodType": "Ed25519VerificationKey2020", "controller": "", "publicKeyMultibase": "z6Mk" } ], "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](/peaqos/guides/onboard-on-solana#the-did-document). ## 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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} SERIAL= 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. Nothing is sent. The output shows the bond for your tier, any voucher credit, and the net PEAQ the wallet needs. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos activate \ --machine-type Sensor \ --credential-subject-hex "$CREDENTIAL_SUBJECT_HEX" \ --manufacturer 0x \ --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. 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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos activate \ --machine-type Sensor \ --credential-subject-hex "$CREDENTIAL_SUBJECT_HEX" \ --manufacturer 0x \ --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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos machine status --json ``` You should see your wallet as `owner`, your tier under `subscription`, and `is_homed_locally: true`. The machine's peaqID is `did:peaq:`. 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: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} 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. 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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # read one value; .env is unquoted and holds secrets PEAQOS_RPC_URL=$(grep -m1 '^PEAQOS_RPC_URL=' .env | cut -d= -f2-) OWNER= OPERATOR= MANUFACTURER= # 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](/peaqos/guides/onboard-on-solana#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](/peaqos/guides/onboard-on-solana#what-the-cli-fingerprints). 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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos activate "${ARGS[@]}" --dry-run ``` This claims the machine ID for your Solana owner. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} PEAQOS_OWS_WALLET=fleet-operator peaqos activate "${ARGS[@]}" --phase reservation ``` The output includes `machine_id`. It stays the same for every later step. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} 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. 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: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos activate "${ARGS[@]}" --phase native_onboarding --dry-run ``` ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} 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`. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos machine status --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 **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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos qualify event --machine-id --type activity --value 0 \ --ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" peaqos qualify mcr did:peaq: ``` 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](/peaqos/cli#peaqos-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. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} PEAQOS_OWS_WALLET=fleet-owner peaqos qualify event --machine-id \ --type activity --value 0 --ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" ``` `peaqos qualify mcr did:peaq:` 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](/peaqos/cli#peaqos-machine). **Renew it.** The bond sits on peaq, so renewal runs there with the operator wallet and takes no `--chain`: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} PEAQOS_OWS_WALLET=fleet-operator peaqos machine subscription renew ``` **Sell its data.** Both homes can package and sell machine data through [Stream](/peaqos/functions/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](/peaqos/install#peaq-mainnet-contracts). | | `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](/peaqos/guides/onboard-on-solana#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](/peaqos/cli#exit-codes) and [Solana onboarding: resume after an interruption](/peaqos/guides/onboard-on-solana#resume-after-an-interruption). ## Where to go next * [Activate](/peaqos/functions/activate): what activation creates and why it is one transaction * [Self-managed onboarding](/peaqos/guides/self-managed-onboarding): the peaq flow from the SDKs instead of the CLI * [Fleet onboarding with an operator](/peaqos/guides/proxy-operator-fleet): machines that own themselves while you operate them * [Onboard a machine on Solana](/peaqos/guides/onboard-on-solana): every Solana flag, state and recovery path * [Wallets (OWS)](/peaqos/wallets), [Install](/peaqos/install), [Economics 2.0](/peaqos/concepts/economics-2-0)