peaqOS CLI

Drive activate, qualify, scale, and operator flows from your terminal.

The peaqOS CLI wraps the SDK into a terminal surface for the most common machine flows: activating a machine under Economics 2.0, managing its lifecycle and subscription, submitting events, querying credit ratings, running operator-controlled fleets, reading a machine’s Verify record and preparing its chip evidence, and the full Scale loop: pairing an AI agent, searching the Machine Markets catalogue, placing and confirming orders. It’s the same on-chain and orchestration path as the JS and Python SDKs, scripted.

Install

pip install peaq-os-cli
peaqos --version

Python 3.10 or newer. Ships to PyPI as peaq-os-cli and exposes the peaqos command. Wraps the Python SDK: same on-chain path, scripted.

Install the current release with pip install -U peaq-os-cli. Solana flows need the extras and CLI 0.0.19 or newer: pip install -U 'peaq-os-cli[solana,ows]'. 0.0.17 onboards, but its qualify event and machine … --chain solana cannot reach a Solana-homed machine; 0.0.18 sends events, but its --chain solana management writes fail at submit. Since 0.0.17 the CLI needs click 8.4 or newer; the CLI pins it, and pip install -U installs it. The CLI declares the minimum peaq-os-sdk it needs. There is no Tokenomics 1.0 onboarding path in the CLI. To drive 1.0 machines from the terminal, pin both packages: pip install "peaq-os-cli<0.0.8" "peaq-os-sdk<0.6.0" (Python 3.11 or newer). Pinning the CLI alone resolves an SDK that peaqos monetize cannot use.

peaqos --version prints both the CLI and the underlying peaq_os_sdk versions on a single line. Global flags -v / --verbose and -q / --quiet toggle DEBUG and ERROR-only logging respectively (mutually exclusive; logs go to stderr). --orchestration-url <url> and --orch-api-key <key> are global overrides for the corresponding env vars on any peaqos scale ... invocation.

Configure

The CLI reads the same environment variables as the SDKs. Full table on Install.

export PEAQOS_RPC_URL=https://peaq.api.onfinality.io/public
export PEAQOS_PRIVATE_KEY=0x...

# Economics 2.0 deployment record: peaq-mainnet or agung-2026-08-28.
# Required by activate, machine, and monetize. The contract addresses travel with it.
# qualify mcr and show also read the MCR server from it (https://mcr.peaq.xyz for peaq-mainnet).
export TOKENOMICS_DEPLOYMENT_ID=peaq-mainnet

# Solana (machines homed on Solana, see "Solana home" under activate). Two RPCs, not one.
# Needed after onboarding too: qualify event and every machine command with --chain solana.
export PEAQOS_SVM_NETWORK=mainnet-beta
export PEAQOS_SVM_RPC_URL=https://api.mainnet-beta.solana.com

# Verify API origin, read by `peaqos verify status` only (no default).
export PEAQOS_VERIFY_API_URL=https://mcr.peaq.xyz

The root flags --svm-rpc-url and --svm-network (before the command name) override the two Solana variables, which override .env.

Other RPC endpoints are available. See Public RPC endpoints.

Or scaffold a .env interactively with peaqos init.

Commands

peaqos init

Interactive wizard that scaffolds a .env with the required peaqOS variables. Prompts, in this order, for network, private key source (paste, generate, or wallet), RPC URL, the Economics 2.0 deployment ID (TOKENOMICS_DEPLOYMENT_ID, default peaq-mainnet on mainnet and agung-2026-08-28 on testnet; it selects the MCR and Event Registry defaults that follow), MCR API URL, Gas Station URL, the Event Registry address, and last PEAQOS_ORCHESTRATION_URL and PEAQOS_ORCH_API_KEY for Machine Markets (leave both empty if you do not use them). The other five Tokenomics 1.0 addresses, labelled legacy and still required by the SDK constructor, are filled without a prompt: the two precompiles from built-in values, and on mainnet IdentityRegistry, IdentityStaking and MachineNFT from peaqos.json, which the wizard downloads from GitHub. If that download fails, the wizard writes those three empty and later commands exit 3 with Missing required env var; copy them from the mainnet section of the install page. The orchestration key is masked in any echoed or logged output. The wallet path creates a new OWS vault wallet and writes PEAQOS_OWS_WALLET=<name> instead of PEAQOS_PRIVATE_KEY. Writes .env with 0o600 permissions and auto-runs whoami to verify.

On peaq mainnet the MCR API URL prompt defaults to https://mcr.peaq.xyz and the wizard writes it to .env as PEAQOS_MCR_API_URL. With TOKENOMICS_DEPLOYMENT_ID set, qualify, show and monetize take the MCR host from the deployment record and do not read this value; peaqos whoami still prints it.

peaqos init
peaqos init --force            # overwrite existing .env without prompt
peaqos init --non-interactive  # read all values from env vars

On peaq mainnet the wizard (CLI 0.0.13 or newer) defaults EVENT_REGISTRY_ADDRESS to the Economics 2.0 registry 0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e. CLI 0.0.12 and older default to the Tokenomics 1.0 registry 0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA instead: upgrade with pip install -U peaq-os-cli, or export EVENT_REGISTRY_ADDRESS=0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e before peaqos init (an exported value takes precedence over the default) or edit .env afterwards. Both contracts share the submitEvent selector, so a 2.0 machine’s event sent to the 1.0 registry reverts with MachineNotFound and is not recorded.

On agung the wizard prefills only the deployment ID and the two precompile addresses. The Event Registry prompt has no default and --non-interactive exits 3 unless EVENT_REGISTRY_ADDRESS is set. Fill PEAQOS_RPC_URL and the IdentityRegistry, IdentityStaking and MachineNFT addresses in .env yourself, from the agung section of the install page.

peaqos whoami

Read-only command that prints the signing address, network, chain ID, RPC URL, the PEAQOS_MCR_API_URL value (or http://127.0.0.1:8000 when unset; with TOKENOMICS_DEPLOYMENT_ID set the MCR commands do not use it), the legacy contract addresses from .env, and a Tokenomics 2.0: block with the deployment ID, chain ID, and the five addresses the SDK record resolved (these come from the SDK, not from .env). Useful as a sanity check after init. When PEAQOS_SVM_NETWORK or PEAQOS_SVM_RPC_URL is set, it also prints the requested Solana cluster, the RPC origin with credentials, path and query stripped, and the SDK’s Solana deployment and packaged-IDL metadata. Those lines are local checks; whoami makes no Solana RPC call.

peaqos whoami

peaqos activate

Onboard a machine in one atomic transaction. MachineStateAndSync.activateMachine mints the ERC-721, stores the DID document, bonds the subscription tier, and registers the home chain in a single call. Mirrors the Activate flow. Requires TOKENOMICS_DEPLOYMENT_ID.

The transaction sender becomes the machine’s owner and bond payer. The bond is quoted in PEAQ per tier at the oracle rate; --payment chooses what settles it.

# Self-owned: your configured signer owns the machine and is its DID controller
peaqos activate \
  --machine-type Sensor \
  --credential-subject-hex 0xdeadbeef \
  --manufacturer 0x3333333333333333333333333333333333333333 \
  --tier entry \
  --did-document ./did.json

# Machine-owned, operator-controlled: the machine key signs and pays, you become DID controller
peaqos activate ... --for 0xMachine --machine-key ./machine.key

# Preview the bond, the voucher credit, and the net PEAQ. Submits nothing and skips Gas Station
# funding: a signer without the net PEAQ plus 0.05 PEAQ of gas gets INSUFFICIENT_PEAQ (exit 2).
peaqos activate ... --dry-run

# Scripted: --yes is the only non-interactive consent
peaqos activate ... --json --yes

# USDT settlement (--payment usdt --slippage-bps 50) is not configured on peaq mainnet; see "Paying in USDT"

Flags

Flag	Required	Meaning
--machine-type	yes	Identity domain. Half of what fixes the permanent machine ID.
--credential-subject-hex	yes	0x-prefixed identity-anchor bytes. The other half.
--manufacturer	yes	Manufacturer address. Recorded on-chain, never verified by the contract.
--tier	yes	entry, basic, or pro.
--did-document	yes	Path to a UTF-8 JSON DID document (schema below).
--for	no	Machine EOA address. Switches to machine-owned mode; requires --machine-key.
--machine-key	no	File holding the machine’s 0x-prefixed hex private key.
--payment	no	peaq (default) or usdt. Which asset settles the PEAQ-quoted bond. usdt is not configured on peaq mainnet and fails there.
--slippage-bps	conditional	Accepted conversion movement, 0 to 10000. Required for usdt, rejected for peaq.
--skip-funding	no	Skip the funding pre-check, 2FA, and Gas Station funding. The bond-plus-gas check before signing still runs (INSUFFICIENT_PEAQ).
--dry-run	no	Preview and stop.
--json	no	One JSON object on stdout. Never implies consent.
--yes / -y	no	Accept the displayed terms. The only non-interactive consent.

--machine-type and --credential-subject-hex alone determine the machine ID (uint256(keccak256(abi.encode(machineType, credentialSubject)))). Neither can change after activation, and the same pair can never be activated twice.

Private keys must come from a file. Inline key flags are intentionally unsupported: a file keeps the key out of shell history and ps output.

--doc-url, --data-api, and --visibility are not supported: 2.0 records the DID document atomically during activation. Passing any of them exits 1 with a plain error message (no error_code). Put documentation and API URLs into the serviceEndpoints array of --did-document.

DID document schema

Exactly three root fields, all required. Unknown fields, duplicate keys, and a root id or controller are rejected: id is computed on-chain and controller is set by the CLI from the mode.

{
  "verificationMethods": [
    {
      "id": "#key-1",
      "methodType": "Ed25519VerificationKey2020",
      "controller": "0x1111111111111111111111111111111111111111",
      "publicKeyMultibase": "z6MkiExamplePublicKey"
    }
  ],
  "authentication": [0],
  "serviceEndpoints": [
    {
      "id": "#telemetry",
      "serviceType": "TelemetryService",
      "serviceEndpoint": "https://machine.example/telemetry"
    }
  ]
}

Each authentication entry is an index into verificationMethods. The CLI bounds-checks them because the contract stores them unchecked at mint.

Ownership modes

Mode	Who signs and pays	Controller
Self-owned (no --for)	Your configured signer owns the machine and pays the bond	Same address
Machine-owned, operator-controlled (--for + --machine-key)	The machine signs, owns the NFT, and pays gas and the bond	Your operator address (PEAQOS_PRIVATE_KEY), which signs nothing in this mode

In machine-key mode the CLI prints the changed rights before asking: the machine wallet can transfer the NFT and rotate or clear the controller; the operator can run lifecycle, subscription, and DID actions but cannot transfer the NFT or change the controller. There is no operator-sponsored activation; registerFor has no 2.0 equivalent.

Paying in USDT

Not available on peaq mainnet: SubscriptionTokenProvisionPool has no USDT token configured, so USDT settlement fails. Pay in PEAQ. The rest of this section describes the flow on a deployment where the token is set.

The bond, the voucher credit, and the net amount stay in PEAQ; only settlement differs. The CLI shows the USDT token, the quote, the accepted slippage, and the resulting maximum USDT, then submits that exact maximum. The allowance goes to SubscriptionTokenProvisionPool, not to MachineSubscription. A bond covered entirely by voucher credit converts and transfers nothing.

Output, exit codes, and error_code

Progress, the preview, and prompts go to stderr; stdout carries only the final summary (or one JSON object with --json). Machine IDs and every unbounded chain integer are decimal strings in JSON, never numbers.

{
  "status": "activated",
  "mode": "self-owned",
  "deployment_id": "peaq-mainnet",
  "chain_id": "3338",
  "machine_id": "57896044618658097711785492504343953926634992332820282019728792003956564819975",
  "tier": "entry",
  "owner": "0xDC5b20847F43d67928F49Cd4f85D696b5A7617B5",
  "controller": "0xDC5b20847F43d67928F49Cd4f85D696b5A7617B5",
  "bond_amount": "909153310068100128",
  "voucher_credit": "0",
  "net_peaq_amount": "909153310068100128",
  "transaction_hash": "0xabab...",
  "is_homed_locally": true
}

The four CLI-wide exit codes apply. Once input validation has passed, every activate outcome is a JSON report (with --json) whose failures carry a stable error_code, bracketed in human output; success and preview reports have no error_code key and report a status instead: preview, activated, already_active, or pending. Before that point there is no report: the CLI’s own input validation exits 1 with a plain message, a value Click itself rejects (an unknown option, a --tier outside the choices) exits 2 with a usage message, and a missing or wrong Economics 2.0 configuration exits 3 with a plain message. The codes to know:

Exit	error_code examples
0	none; status is activated or already_active
1	INVALID_INPUT, CANCELLED_BEFORE_SUBMIT (interrupted before anything was submitted; declining the prompt exits 1 with a plain message and no report), SPONSORED_UNSUPPORTED, INVALID_TIER
2	ORACLE_UNPRICED (contracts reachable, no PEAQ price committed), INSUFFICIENT_PEAQ, QUOTE_MOVED, TX_REVERTED, EVENT_MISMATCH, PENDING, ALREADY_ACTIVATED_RACE
3	TOKENOMICS_NOT_CONFIGURED, DEPLOYMENT_UNKNOWN, CHAIN_MISMATCH, PEER_MISMATCH, PEER_UNSET (InfoDesk has no address for a role the call needs), ADDRESSES_UNSET (network supported, contracts not deployed there)

The Solana path adds its own codes; they are listed under Solana home.

Pending transactions and peaqos.log

A submitted transaction whose receipt does not arrive is reported as PENDING at exit 2 with its hash, not as a failure. It may still mine. Every submitted hash is appended to ./peaqos.log (mode 0600) before the receipt wait. Re-running the same command reconciles the recorded hash instead of resubmitting; a hash with no receipt blocks resubmission regardless of age. Never submit a second activation for the same machine, and never delete peaqos.log while a transaction is outstanding.

Solana home

--chain solana homes the machine on Solana instead of peaq. The identity, DID document and Machine NFT then live in Solana accounts that name a Solana key as owner. That key, the owner wallet, pays the bond on Solana, in PEAQ or USDC, through the subscription terminal; peaq then books the bond. Activation is seven stages on two chains instead of one transaction:

Stage	Signer	--phase
[1/7] Operator registration on peaq	operator wallet, once per owner wallet (gas only, about 0.01 PEAQ); reconciled, not sent, when already bound	registration
[2/7] Activation request on Solana	owner wallet: the escrow moves into the request, the bond is frozen	request
[3/7] Credit from peaq	peaq’s Trust Validator node (the node; a wait)	none
[4/7] Settlement on Solana	owner wallet: PEAQ to the vault, or the USDC swap; the point of no return	finalise
[5/7] Bond on peaq	the node and peaq (a wait)	none
[6/7] Native onboarding on Solana	owner wallet: mints the machine against the bonded request	native_onboarding
[7/7] Link push Solana → peaq	owner wallet, then the Trust Validator node’s delivery on peaq (a wait); no messaging fee	linkage

--phase cancel_request (owner wallet) ends an open request that will not settle and returns the escrow. It prints Cancel request on Solana: confirmed <signature> and landed after N sends, like the stages (since 0.0.17). With no request open, the CLI decides before it asks for consent or a passphrase: a cancel this journal recorded is already done; nothing was signed; a cancel the journal did not record (the node’s) is REQUEST_CLOSED; a request closed after the mint is REQUEST_NOT_CANCELLABLE. One command runs every stage and waits out the three waits; --phase runs one stage at a time. --dry-run without --phase previews the whole onboarding on one screen and needs no wallet. Step by step with costs and recovery: Onboard a machine on Solana.

peaqos activate "${ARGS[@]}" --dry-run                  # keyless; ends with "Run it with --max-in N"
ARGS+=(--max-in "$MAX_IN")                               # the suggested escrow, in base units of the pay-in token

# one command, both wallets, all seven stages; rerun the same command to resume
OWS_PASSPHRASE=... peaqos activate "${ARGS[@]}" \
  --operator-wallet svm-operator --owner-wallet svm-owner \
  --wait-minutes 60 --yes

# or one stage per invocation
peaqos activate "${ARGS[@]}" --phase registration      --operator-wallet svm-operator --yes
peaqos activate "${ARGS[@]}" --phase request           --owner-wallet svm-owner --yes
peaqos activate "${ARGS[@]}" --phase finalise          --owner-wallet svm-owner --yes
peaqos activate "${ARGS[@]}" --phase native_onboarding --owner-wallet svm-owner --yes
peaqos activate "${ARGS[@]}" --phase linkage           --owner-wallet svm-owner --yes

ARGS is the argument set from the guide. Production’s link push goes to the Trust Validator node with no messaging fee, so neither command takes a fee cap; --phase linkage --dry-run names the route.

Solana flag	Required	Meaning
--chain solana	yes	Selects the Solana home. Also needs PEAQOS_SVM_RPC_URL (or --svm-rpc-url).
--operator-wallet, --owner-wallet	for writes	OWS wallet names, both defaulting to PEAQOS_OWS_WALLET. The operator wallet signs registration on peaq, the owner wallet every Solana write.
--pay-in	no	PEAQ (default; the OFT on Solana) or USDC: the token the owner pays the bond in.
--max-in	for request	The escrow, integer base units of the pay-in token. On PEAQ at least the bond (ESCROW_BELOW_BOND); on USDC the swap’s simulated cost must fit. The dry run suggests it; what the bond does not use comes back at settlement.
--tier	for the run, request and a registration preview	entry, basic or pro, or a program tier 0–7. The quote refuses a tier the deployment does not price. The request freezes it; the later stages do not read it.
--slippage-bps	no	Default 100. The cushion on the suggested escrow: on USDC on the swap, on PEAQ on the price stamp.
--phase	single-stage writes	registration, request, finalise, native_onboarding, linkage or cancel_request. The waits are not phases: rerun without --phase and with --wait-minutes to wait them out.
--nonce	no	With cancel_request, the request to cancel when it is not the latest.
--wait-minutes	no	0 to 60, default 0. One budget for the run’s waits (the registration’s mirror on a first machine, credit, bond, the link’s delivery) and every receipt reconcile; reads only, signs nothing. The credit wait also stops after 3 minutes and the bond wait after 6, whatever is left of the budget. A wait that ran out: exit 2, PENDING, naming operator_binding, credit, bond or link_application; rerun to keep waiting. Ctrl-C: exit 1, CANCELLED. Refused with --dry-run.
--timeout-seconds	no	Time budget for each attempt of a write (checks, the send, the receipt wait), default 300.
--max-link-push-fee-lamports	no	Only on a deployment that routes the link push over LayerZero: the cap on its messaging fee, on the one-command run or --phase linkage. On such a route a push without it is refused before signing (INVALID_INPUT, with the dry run as guidance). The node’s route has no fee and ignores it. Refused with any other single stage.
--solana-owner	yes	Base58 public key of the Solana owner wallet.
--solana-controller	no	Optional native controller. Omitted means owner-only.
--evm-operator	no	Assertion: must equal the operator wallet’s peaq address, checked before [1/7] (EVM_OPERATOR_MISMATCH). Omitted, the machine inherits the registration’s operator.
--max-native-fee-lamports	yes	Network plus priority fee of each Solana write, excluding rent. The largest is the mint’s: at the default price it was 6,210 lamports on the proven run with the sized compute limit, and it is 11,000 lamports with --compute-unit-limit 600000.
--max-native-rent-lamports	yes	Rent of each Solana write: the request’s accounts, the machine’s records, the push account.
--compute-unit-limit	no	The mint’s compute budget. Omitted (since 0.0.17), the SDK sizes it from the mint’s simulation: the simulated units × 1.3, rounded up to the next 1,000, at least 50,000 (about 121,000 on production). The CLI previews the mint once at 600,000, then again at that size, so the consent quotes the fee the mint will pay. An explicit value is used as given. The link push on the Trust Validator route asks for 120,000.
--compute-unit-price-micro-lamports	no	Default 10000: the priority price of every Solana write, about 4,900 lamports across a PEAQ onboarding and about 7,900 on USDC. 0 sends without priority, which Solana’s public endpoint can drop under load.
--audit	with --dry-run	Re-reads the onboarding from peaqos.log in this directory: every transaction confirmed against the chain, spent, and the link push’s relay by the node with its outbox nonce. Signs nothing.

--manufacturer and the verification-method controllers in --did-document are base58 Solana keys here. --for and --machine-key are rejected. The removed reservation flow’s options are refused by name with OPTION_NOT_FOR_CHAIN (exit 1), naming the replacement: --payment (--pay-in), --max-net-peaq-amount and --max-usdt-amount (--max-in). --from-block is accepted and ignored. Every ceiling is validated before signing and 0 means zero, not unlimited. The CLI warns when an exported PEAQOS_* or TOKENOMICS_* variable differs from .env, and when a write goes to the public api.mainnet-beta.solana.com.

Human output starts with a plan block (both wallets, the expected bond and escrow, the rents, what the owner must hold before [2/7]), then each stage’s terms and its numbered outcome on stderr. After every confirmed write the CLI prints an indented landed after N sends line, and for the mint also · <used> of <limit> CU (since 0.0.17). A wait prints a “still waiting” line every two minutes and “landed in …” when it ends. [7/7] reads “Link push queued for the Trust Validator node (seq N, TV nonce M)” before its wait. Once the SDK reports complete, stdout carries the summary with every reference (the push as Link push (Trust Validator)), link seq N applied, the Spent (from receipts) block and the audit trail. With --json, stderr is JSON lines only (plan, consent, stage and wait events) and stdout one JSON result with phases: [{phase, status, reference, exit_code}]; each confirmed phase’s confirmation carries sends, resend_errors and, for the mint, the compute figures. Every write result also carries:

• resume_command: the command that continues; for the one-command run the run itself. --yes, --dry-run, --svm-rpc-url and --orch-api-key are never carried over; --svm-network is, and other options only when you gave them.
• spent: read from receipts, never from quotes: the escrow out and back, the rents out and back, the fees, the registration’s gas.
• audit_trail: every transaction with its slot or block and finality, and the link push’s delivery: the node’s relay with its outbox nonce, or on a LayerZero route the message with a LayerZero Scan link (a convenience, not evidence).
• record_file: onboarding-<machine-id>.json, written beside peaqos.log after every write: each invocation, the references, spent, the trail, and once complete the chain-read history.
• a provenance label on each evidence block: journal_claim is what the CLI recorded at submit time in peaqos.log, chain_verified what the SDK read back from the chains. --json adds provenance_legend.

Onboarding is done when next_step.phase is complete. The SDK derives that from peaq’s MachineBridgeAdapter.lastAppliedMirrorPushSeq for the machine reaching the link push’s sequence (reason link_applied, or later_push_pending when a later Solana push is still in flight). Exit 0 on --phase native_onboarding or --phase linkage means that stage’s Solana transaction confirmed, not that onboarding is complete. The Solana receipt of the push proves the send, not the delivery. The watermark is the only evidence of delivery.

Solana error_code	Exit	Meaning
PENDING	2	A receipt did not arrive in time, or a wait budget ran out. While the write’s blockhash is still valid (about 80 s), the SDK re-sends the same signed bytes every 2 s, so a send the network dropped usually lands in the same run (since 0.11.2); same bytes, same signature, so nothing is paid twice. After that window, rerun: the recorded transaction is reconciled, not signed again. A request, settlement or cancellation that failed, or expired without landing, is replaced by a fresh one. The one write a rerun signs again is a mint the SDK has proven dead (its blockhash expired, no signature in history, no Machine or MachineState account), minted again on the next run with the dead row printed as expired (since 0.0.16); since 0.0.17 the same applies to a mint that ran out of compute and created nothing (compute_budget_exceeded; the audit reads the row failed, no effect).
CANCELLED	1	Ctrl-C before anything was signed, between stages or during a wait.
WAIT_READ_FAILED	the read’s	A status read during a wait failed.
REQUEST_EXPIRED, COMMIT_EXPIRED	2	The node did not credit the request within its hour, or the commit expired before the settlement. Nothing was settled. The node cancels an expired request on its own once it is back and returns the escrow; or cancel it with --phase cancel_request. Then rerun: it opens a new request, even though the journal peaqos.log still holds the old one (since 0.0.17; before, the rerun could take the old row for a live request and stop at [3/7] with ActivationRequest absent).
REQUEST_CLOSED	2	A single --phase (finalise, cancel_request) was run on a request that had been cancelled or refunded. Nothing was signed. Rerun the same command without --phase: it opens a new request at the next nonce (since 0.0.17).
ACTIVATION_REFUNDED	2	peaq refused the bond after the settlement; the Trust Validator refunded it in PEAQ (the error names the reason and the amount). Rerun: it opens a new request.
ESCROW_BELOW_BOND, INSUFFICIENT_BALANCE	1, 2	--max-in is below the bond on PEAQ, or the owner’s pay-in token account holds less than it. Refused before signing.
FINALISE_TABLE_MISSING, FINALISE_TABLE_STALE	3	USDC: no usable lookup table for the swap on this deployment. Refused before signing; pay in PEAQ or wait for the table. A pool that moved past the cap fails the pre-signing simulation instead (sdk_code SLIPPAGE_EXCEEDED); rerun.
EVM_OPERATOR_MISMATCH	1	--evm-operator is not the operator wallet’s address. Refused before [1/7].
OPTION_NOT_FOR_CHAIN	1	An option of the removed reservation flow; the message names the replacement.
TECHNICALLY_PAUSED	2	The suite’s upgrade lock on Solana (or a technical pause on peaq) is set. Nothing was signed.
RPC_RATE_LIMITED	2	An endpoint kept answering 429 after the SDK’s read retries. Sends are never retried.
RPC_FAILED (sdk_code READ_FAILED)	2	A read failed. When its message names -32016, a Solana server behind the slot the read needed kept answering after the retries; rerun, or use a provider endpoint.
TV_OUTBOX_MISSING, TV_INBOUND_REFUSED	2	The node’s route is not set up: the adapter has no outbox for peaq, or peaq refuses the node’s deliveries. Refused before signing; a deployment problem, not yours.
FEE_LIMIT_EXCEEDED, RENT_LIMIT_EXCEEDED, INSUFFICIENT_SOL	2	Refused before signing: a fee over its cap (the network fee over --max-native-fee-lamports, or on a LayerZero route the messaging fee over --max-link-push-fee-lamports), rent over --max-native-rent-lamports, or the owner cannot pay a write and keep its own rent-exempt minimum (650,240 lamports for a plain wallet). The message names the quoted amount and the cap.
INVALID_INPUT at [7/7]	1	LayerZero route only: the push needs --max-link-push-fee-lamports. Refused before signing.
MACHINE_NOT_ONBOARDED, EVM_OPERATOR_UNSET, LINK_CONFIG_UNAVAILABLE, BRIDGING_DISABLED, LZ_SEND_LIBRARY_UNSUPPORTED	2	Link push refused before signing: no native machine yet, no peaq operator on the machine record (set-evm-operator sets one), or a deployment-side configuration the owner cannot change (the last three on a LayerZero route).
STATE_MISMATCH	2 (1 for a wrong wallet)	Chain state disagrees with the plan: another owner or operator, a changed input, or the wrong wallet for the stage (Select the accepted phase's wallet, nothing signed).
ADDRESSES_UNSET with sdk_code DEPLOYMENT_UNAVAILABLE	3	The installed SDK’s packaged deployment evidence does not match the chain (an outdated SDK, or the programs were upgraded after its release). Upgrade the CLI and SDK.
link_already_pushed	0	A reason, not an error: the last push already carries the machine’s values, nothing was sent.

Keep peaqos.log, the working directory and the exact inputs across runs. A rerun of a confirmed stage reconciles it and never resubmits it. The one write a rerun signs again is a mint the SDK has proven dead (since 0.0.16; the dead row stays in the journal, printed as expired). peaqos machine history <id> --chain solana lists every transaction of an onboarding from the chains alone, and peaqos machine status <id> --json --chain solana reads the machine afterwards without wallet or journal, including the top-level link block with peaq’s watermark (status not_pushed, pending_application, linked or unavailable).

peaqos machine

Everything after onboarding: lifecycle, subscription payments, ERC-721 ownership, DID updates, and relocation status. Requires TOKENOMICS_DEPLOYMENT_ID.

peaqos machine status MACHINE_ID
peaqos machine history MACHINE_ID --chain solana [--json]                # Solana-homed machines: every onboarding transaction, from the chains
peaqos machine suspend MACHINE_ID
peaqos machine resume MACHINE_ID

peaqos machine subscription activate MACHINE_ID --tier TIER --payment RAIL [--slippage-bps N]
peaqos machine subscription renew MACHINE_ID --payment RAIL [--slippage-bps N] [--tier TIER]

peaqos machine approve MACHINE_ID OPERATOR
peaqos machine approve-all OPERATOR --allow|--revoke
peaqos machine transfer MACHINE_ID TO [--unsafe] [--data-hex HEX]

peaqos machine did set-controller MACHINE_ID CONTROLLER
peaqos machine did clear-controller MACHINE_ID
peaqos machine did set-verification-methods MACHINE_ID --file PATH
peaqos machine did set-authentication MACHINE_ID [--index N]... | --clear
peaqos machine did set-services MACHINE_ID --file PATH

peaqos machine relocation status MACHINE_ID --destination-rpc-url URL --destination-deployment-id ID

peaqos machine set-evm-operator MACHINE_ID EVM_OPERATOR --chain solana   # Solana-homed machines only

Every write accepts --yes, --json and, except subscription activate and subscription renew, --dry-run (preview and reconcile, sign nothing); every read accepts --json. Machine IDs are full-width uint256: pass them as canonical unsigned decimal (no 0x, no leading zeros) and read them back as decimal strings.

Every write runs the same sequence: validate locally, reconcile the journal (a pending transaction for the same action and machine blocks rather than repeats), ask the SDK for a preview (chain, contract, method, current state, intended effect), show it and ask, then submit once and record the hash before waiting for the receipt. A rerun reconciles an unresolved (pending) hash instead of resubmitting; once that outcome is recorded as confirmed, the next rerun is a new write and asks for consent again, so check state with machine status rather than rerunning a write with --yes.

Details that matter:

• Who may sign. Suspend, resume, renew, and DID updates: owner or controller. set-controller and clear-controller: owner only. Transfers: standard ERC-721 authority. Points and credits from a renewal land on the owner even when the controller pays.
• suspend does not pause billing. It sets a flag on the machine, for example to mark it as under maintenance. The subscription period, grace, runoff and renewal date are unchanged. See Subscription lifecycle.
• approve-all is not scoped to one machine. It grants the operator every MachineRegistry machine the signer owns, including ones activated later.
• transfer is safe by default (safeTransferFrom). --unsafe selects transferFrom, which can strand the NFT in an incompatible contract. Transfer does not rotate the DID controller.
• DID setters replace whole arrays. The file or index list you pass is the complete new state. Authentication indices point into the verification-method array by position. --index and --clear are mutually exclusive and one is required.
• Renewal extends from the stored period end, not from now, and keeps the stored tier. The contracts allow a tier change once the period has ended (Grace or Runoff), but no published deployment record enables tier selection on renewal (peaq-mainnet and agung-2026-08-28 both set it off), so passing --tier, even the stored tier, reports RENEWAL_TIER_UNSUPPORTED (exit 3, before any RPC). Omit --tier; pick the tier at activation. --payment usdt requires --slippage-bps and is not configured on peaq mainnet.
• history reads an onboarding from the chains. machine history MACHINE_ID --chain solana needs no wallet, journal or original inputs: one line per transaction of the machine’s onboarding on both chains (step, who sent it, slot or block, cost to its payer), then totals per payer. The link push’s delivery by the Trust Validator node reads actor node, and -v links the push to the node’s outbox (tv_outbox). A Solana transaction the owner did not pay but that moved its balances, such as the node’s cancel of an expired request, adds the owner’s part to its row (owner +3,657,600 lamports, and the escrow back); the owner’s total is its net change. -v adds full references and explorer links; --json carries every amount as a decimal string, with owner_lamports_delta and owner_token_deltas on every Solana row. The owner wallet’s registration and binding are marked reused on a later machine of the same owner and kept out of its totals. A source that could not be read is named and the command exits 2; the rows shown are still exact, and a rerun reads it.
• Relocation is read-only. relocation status reports pending, arrived, completed, cancelled, or conflicting. Initiation and cancellation are not available, and relocation is disabled on chain.
• Solana-homed machines. Add --chain solana to route a management command through the native SDK path: machine status, transfer, suspend, resume, did set-controller and the other DID setters, plus machine set-evm-operator MACHINE_ID 0xOperator --chain solana, which maintains the peaq subscription link and exists only for Solana. The flag is a routing choice; the SDK still resolves the machine’s home from its ID and refuses the wrong chain. Needs pip install 'peaq-os-cli[solana,ows]' and PEAQOS_SVM_RPC_URL; without the endpoint a write stops with exit 3 before reading anything (CLI 0.0.18; earlier versions ended STATE_MISMATCH even with it set). The writes submit from CLI 0.0.19: 0.0.18 previews them, then fails after consent with TypeError: … unexpected keyword argument 'solana', before anything is signed. A live Solana write takes its cost ceilings explicitly, as activate --chain solana does: --max-native-fee-lamports (network plus priority fee) and --max-native-rent-lamports (rent top-up; 0 refuses any). --dry-run without them previews the write and prints the values a live run needs; a live write without both stops before consent and before the wallet is unlocked. --compute-unit-price-micro-lamports sets the priority price (default 10000, about 2,000 lamports per write). Four things differ from peaq and are refused rather than approximated: transfer needs --unsafe (there is no safe transfer, --data-hex is refused), approve and approve-all are refused, addresses are base58 and never converted, and operator synchronization is reported unavailable on a keyless read. Without --chain solana, machine status falls back to the Solana read when the peaq record is missing or homed elsewhere: status: "observed" plus a native_current_state with separate peaq and Solana observations (absent, reserved, pending_external, present, conflict, in_flight, unavailable). Status output also names the subscription account the deployed programs read (subscription_source, terminal on peaq mainnet) and shows the mirror and terminal evidence side by side, with unread values null. See Onboard a machine on Solana.

peaqos machine status 57896044618658097711785492504343953926634992332820282019728792003956564819975 --json
peaqos machine suspend <machine-id> --yes
peaqos machine subscription renew <machine-id> --payment peaq --yes
peaqos machine transfer <machine-id> 0xRecipient --yes

# Solana-homed machine: preview, which prints the ceilings a live run needs, then write
peaqos machine did set-services <machine-id> --file services.json --chain solana --dry-run
peaqos machine did set-services <machine-id> --file services.json --chain solana \
  --max-native-fee-lamports 7000 --max-native-rent-lamports 0 --yes

Exit codes and error_code values are the ones documented under peaqos activate: one taxonomy for both.

qualify mcr, show machine and show operator machines read from mcr.peaq.xyz. The CLI selects that host only with TOKENOMICS_DEPLOYMENT_ID set; without it the MCR commands do not read Economics 2.0 machines. A machine DID is did:peaq:<decimal machine id>; a did:peaq:0x<address> machine DID exits 1 with INVALID_INPUT (Machine DID requires a canonical decimal ID in 0..2^256-1.). show operator machines takes did:peaq:0x<address>, because an operator DID names an account, not a machine. All three are HTTP-only reads and need no signer. On agung-2026-08-28, which has no paired 2.0 MCR, all three exit 3 with CONFIG_ERROR (The SDK rejected the selected MCR deployment). A failed query exits 2 with the MCR error code (for example SERVICE_UNAVAILABLE while the 2.0 operator index is syncing) instead of a traceback.

peaqos qualify event

Submit a revenue or activity event to the EventRegistry. Wraps submit_event. See the Submit events guide for trust levels and cross-chain patterns.

# HK$1.23 (123 cents) revenue event
peaqos qualify event \
  --machine-id 42 \
  --type revenue \
  --value 123 \
  --currency HKD \
  --ts 2026-04-23T12:00:00Z \
  --trust self \
  --source-chain peaq

--value is an ISO 4217 minor-unit integer: cents for USD/HKD, whole units for JPY/KRW/VND. HK$1.23 → --value 123, ¥100 → --value 100. The CLI defaults --currency to USD for revenue events and to "" for activity events; pass --currency explicitly to override. The MCR API converts the value to USD using FX at the event timestamp.

Flag	Required	Meaning
--machine-id	yes	Canonical unsigned decimal, 0 to 2^256-1 in 2.0 mode; legacy mode requires a value greater than 0.
--resume <submission-id>	no	Solana-homed machines only: reconciles a journaled native submission read-only and takes no payload flags, --yes or --dry-run.
--type	yes	revenue or activity.
--value	yes	Non-negative integer in the currency’s minor unit.
--ts	yes	Unix seconds or ISO 8601 with timezone (Z or +hh:mm). Must be on or before block time.
--currency	no	ISO 4217 code, 3-10 uppercase alphanumerics (^[A-Z0-9]{3,10}$). Default: USD for revenue, "" for activity.
--trust	no	self (default), onchain, or hardware.
--source-chain	no	same (default), peaq, or base.
--source-tx	conditional	32-byte hex tx hash. Required when --trust onchain.
--raw-data	no	Path to a file; bytes are hashed and stored as the event data hash.
--metadata	no	Path to a file; bytes are attached as on-chain metadata. Absent = empty bytes.
--dry-run	no	Solana-homed machines only: preview and reconcile, then stop. Signs nothing. On a peaq machine it exits 1.
--yes	no	Solana-homed machines: confirm non-interactively, required when stdin is not a terminal. No effect on a peaq machine, where the event is submitted immediately with no preview or prompt.
--json	no	One JSON object on stdout (status, execution_chain, machine_id, type, value, trust, transaction_hash, data_hash). Never implies consent.

Human output on success:

Event submitted.
  Machine ID:  42
  Type:        revenue
  Value:       123
  Trust:       self-reported
  Tx:          0x3f4a8c1e2d9b7f05a6c3e8d1f4b2a7c9e0d5f3b1a8e2c6d9f7b4a1e3c5d8f2b4
  Data Hash:   0xa1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890

Solana-homed machines

From CLI 0.0.18, qualify event sends an event for a machine homed on Solana to the Solana EventRegistry program. Versions 0.0.16 and 0.0.17 never pass the Solana endpoint to the SDK and refuse with MACHINE_HOMED_ELSEWHERE (”… is unavailable, not resolved”), even with PEAQOS_SVM_RPC_URL set. What it needs:

• pip install 'peaq-os-cli[solana,ows]' and PEAQOS_SVM_RPC_URL: the same .env the machine was onboarded with.
• PEAQOS_OWS_WALLET naming the OWS wallet that holds the machine’s Solana owner or controller key. That wallet signs and pays.
• SOL in that wallet. The first event for a machine pays rent for its event-log account (2,946,400 lamports measured) plus the 5,000-lamport network fee, about 0.003 SOL. Every later event pays the fee only.

Before anything is signed, the preview checks that the signer is the machine’s current owner or controller, that its subscription is eligible, and that the event registry is not paused and the machine not relocating.

# Preview: price and eligibility. Signs nothing.
PEAQOS_OWS_WALLET=<owner wallet> peaqos qualify event --machine-id <machine-id> \
  --type activity --value 1 --ts "$(date +%s)" --dry-run

# Submit: shows the same preview, asks, then signs and waits for confirmation.
PEAQOS_OWS_WALLET=<owner wallet> peaqos qualify event --machine-id <machine-id> \
  --type activity --value 1 --ts "$(date +%s)"

The preview, then the result (an activity event on mainnet; this machine’s event log already existed, so no rent):

About to submit a machine event
  Machine ID              :  42581867695199888670555386101443910530672475932641965651512985654630415296741
  Submitter               :  GnGEGu32nvPp7EcQTnYJMn3yxMJaAoGQgA6HnB5MdGWJ
  Type                    :  activity
  Value                   :  1
  Currency                :  (none)
  Timestamp               :  2026-10-09T03:38:08Z
  Trust                   :  self-reported
  Source Chain            :  same
  Data Hash               :  0x0000000000000000000000000000000000000000000000000000000000000000
  Log State               :  initialized
  Rent (lamports)         :  0
  Network Fee (lamports)  :  5000
  Compute Units           :  39490
  Transaction Size (bytes):  630

This signs and broadcasts a transaction. It cannot be undone.

Submit this event? [y/N]: y
Event submitted.
  Execution Chain:  solana
  Submission ID  :  247303243568646217976204659601125903134
  Signature      :  4kLbofKm8Wwo2XYNCKtJ1hyC8Em1Vk9oY2akagjHN3fUioygR9pfNyWi5Cq9BPiHcJ5yPCq2tEhyaSZqCrnQyfCT
  Slot           :  454751920
  Confirmation   :  confirmed
  Machine ID     :  42581867695199888670555386101443910530672475932641965651512985654630415296741
  Data Hash      :  0x0000000000000000000000000000000000000000000000000000000000000000
  Event Index    :  2
  Event Log      :  EmAGCLWJ6WWgUhmogfPimGCVtwHC5pUzicibriGuzP12
  Compute Units  :  39490

Log State is initializable for a machine’s first event, which is the one that pays rent. Event Index counts the machine’s events from 0. The signature can be looked up on any Solana explorer.

With --json, every integer is a decimal string:

• --dry-run --json prints status: "preview" with execution_chain, submission_id, machine_id, data_hash, log_state, rent_lamports, network_fee_lamports, compute_units, transaction_size_bytes and last_valid_block_height.
• A submission prints status: "confirmed" with execution_chain, submission_id, signature, slot, confirmation, machine_id, data_hash, event_index, event_log and compute_units. --json never confirms a write, so a live --json run needs --yes.

If the wait ends without a confirmation (exit 2, PENDING_TRANSACTION), the event may still land. Every submission is written to ./peaqos.log when it is broadcast, before the wait. From the same directory, run:

peaqos qualify event --resume <submission-id>

It only reads the chain and reports one of three outcomes:

• confirmed: the event landed.
• expired_unlanded: nothing landed, and sending the event again is safe.
• unresolved: run it again later.

While an attempt is unresolved, sending the same payload for that machine again is refused, and the error names the --resume command. Events without --raw-data all have the same (zero) payload hash, so this applies to any two of a machine’s events.

Checking the event. peaqos qualify mcr did:peaq:<machine-id> counts it within minutes (Events: Total, Activity). At the time of writing, peaqos show machine and machines.peaq.xyz do not list Solana events yet: the profile reads event_count: 0 with rating_unavailable: event_history_not_indexed.

peaqos qualify mcr

Fetch a machine’s credit rating from the MCR API. Wraps query_mcr.

peaqos qualify mcr did:peaq:95421033441768219866308236142098740813601779873019666949118591311634701061369
peaqos qualify mcr did:peaq:95421033441768219866308236142098740813601779873019666949118591311634701061369 --json

The DID is did:peaq:<canonical decimal machine ID>; an address DID exits 1. --json emits the raw SDK response on stdout with no banner or prose: useful for jq and scripting.

Human output:

MCR for did:peaq:95421033441768219866308236142098740813601779873019666949118591311634701061369

  Rating:          A
  Score:           82 / 100
  Bond Status:     bonded

  Events:
    Total:         150
    Revenue:       120
    Activity:      30

  30-Day Revenue:  up
  Last Updated:    2025-04-20T12:30:00Z
  FX Degraded:     no
  Avg Revenue:     12851

revenue_trend is one of up, stable, down, insufficient (not enough revenue history to compute a trend), or null (no trend could be measured, for example while the machine’s history is not indexed); the CLI prints null as unavailable. FX Degraded: reflects the top-level mcr_degraded field: yes when one or more scored events used a stale or unavailable FX snapshot, no otherwise. average_revenue_per_event is always present and can be null; Avg Revenue: then prints unavailable.

--json output (raw SDK MCRResponse):

{
  "did": "did:peaq:95421033441768219866308236142098740813601779873019666949118591311634701061369",
  "machine_id": "95421033441768219866308236142098740813601779873019666949118591311634701061369",
  "mcr_score": 82,
  "mcr": "A",
  "mcr_degraded": false,
  "bond_status": "bonded",
  "negative_flag": false,
  "event_count": 150,
  "revenue_event_count": 120,
  "activity_event_count": 30,
  "revenue_trend": "up",
  "total_revenue": 1542075,
  "average_revenue_per_event": 12851,
  "last_updated": 1745152200
}

peaqos show machine

Fetch a full machine profile: Machine ID, operator, MCR rating and score, bond status, event count and service endpoints. Wraps query_machine. The profile’s MCR snapshot can name a different rating_unavailable reason than qualify mcr for the same machine (a new Solana machine reads event_history_not_indexed here and no_events_yet there); qualify mcr is the rating.

peaqos show machine did:peaq:95421033441768219866308236142098740813601779873019666949118591311634701061369
peaqos show machine did:peaq:95421033441768219866308236142098740813601779873019666949118591311634701061369 --json

peaqos show operator machines

List the machines registered under a proxy operator, with MCR per machine. Wraps query_operator_machines.

peaqos show operator machines did:peaq:0xProxyAddress
peaqos show operator machines did:peaq:0xProxyAddress --json

peaqos wallet

Manage OWS-format wallets in the local encrypted vault at ~/.ows/wallets/. Requires the [ows] extra: pip install 'peaq-os-cli[ows]' (quote the bracketed extra so zsh does not glob it). The vault passphrase is read from OWS_PASSPHRASE when set, otherwise prompted interactively. Subcommands wrap the SDK static helpers documented on Wallets (OWS).

Subcommand	Purpose
peaqos wallet create <name> [--words 12|24] [--json]	Generate a new BIP-39 mnemonic and derive accounts for every supported chain. The mnemonic is not displayed; back up via wallet export.
peaqos wallet import <name> --mnemonic [--index N] [--json]	Import from an existing BIP-39 mnemonic (hidden prompt). --index selects the derivation index (default 0).
peaqos wallet import <name> --private-key-file <path> [--json]	Import a raw EVM private key from file. OWS derives an account for every chain family from it; the peaq account is the one peaqOS signs with.
peaqos wallet list [--json]	Compact table of all wallets: Name, ID, peaq Address, Key Type, Created.
peaqos wallet show <name-or-id> [--json]	Wallet metadata plus the full multi-chain address table.
peaqos wallet export <name-or-id>	Reveal the recovery phrase / private key. Requires interactive confirmation. Secret prints to stdout; warning prints to stderr.
peaqos wallet delete <name-or-id>	Securely delete a wallet (file overwritten with random bytes before unlink). Requires confirmation.
peaqos wallet use <name-or-id>	Set the active wallet. Writes PEAQOS_OWS_WALLET=<name> into .env in the current directory. Subsequent commands that call load_client() will sign with this wallet.

When PEAQOS_OWS_WALLET is set, load_client() resolves the wallet from the vault using OWS_PASSPHRASE and skips PEAQOS_PRIVATE_KEY entirely. If both are set, the wallet wins.

peaqos stream

The data-stream command group. The crypto core is offline: publish turns a source file into signed, encrypted chunks on disk; grant re-wraps the chunk keys for a buyer; consume decrypts and reassembles the original data on the buyer’s side. Around it sits the paid flow: distribute waits for a buyer’s payment confirmation and delivers access files to S3, pay transfers tokens to the seller on peaq, Base, or Solana, and payproof submits proof for a transfer completed elsewhere. Purchases and delivery are the SDK-level distribution flow; the P2P delivery channel is not exposed as a CLI flag.

peaqos stream publish

Chunk, encrypt, and sign a data file into a local output directory. Each chunk gets a fresh key wrapped (X25519) for three recipients (owner, operator, machine), and the chain is signed Ed25519. Writes chunk-{i}.json (envelope) + chunk-{i}.bin (ciphertext) per chunk, plus a manifest.json (peaq.stream.chunks.v1).

peaqos stream publish \
  --input ./telemetry.bin \
  --output-dir ./out \
  --owner-public-key 0x<64hex> \
  --operator-public-key 0x<64hex> \
  --machine-public-key 0x<64hex> \
  --signing-key-file ./machine-ed25519.key \
  --machine-did did:peaq:0xMACHINE \
  --machine-key-id did:peaq:0xMACHINE#keys-1

Required: --input (file path or http(s) URL), --output-dir (created if missing), --owner-public-key / --operator-public-key / --machine-public-key (X25519, 64 hex), --signing-key-file (Ed25519 private key file), --machine-did, --machine-key-id.

Optional: --chunk-size (bytes, default 262144), --json (emit the manifest to stdout), and S3 upload: --s3 s3://bucket/prefix/, --s3-region, --s3-endpoint (for MinIO / R2 / S3-compatible stores). S3 needs the extra (pip install "peaq-os-cli[s3]") and credentials via PEAQOS_S3_ACCESS_KEY_ID + PEAQOS_S3_SECRET_ACCESS_KEY (or the standard boto3 chain); each chunk’s storageRef is rewritten to its s3:// URI.

The human summary goes to stderr; the manifest path prints to stdout for piping. Exit codes: 0 success, 1 validation (bad key hex, wrong length, missing input file, StreamValidationError/StreamSigningError), 2 URL download or S3 upload failure.

peaqos stream grant

Grant a buyer decryption access to a published chunk chain, fully offline. Reads the chunk envelopes, unwraps each chunk key with the owner’s X25519 private key, re-wraps for the buyer, and writes peaq.stream.buyer-access.v1 files (sharded by size). This is a local re-key, not an on-chain access grant.

peaqos stream grant \
  --chunk-dir ./out \
  --buyer-public-key 0x<64hex> \
  --buyer-id did:peaq:0xBUYER \
  --owner-private-key-file ./owner-x25519.key \
  --output-dir ./buyer-access

Required: --chunk-dir (published envelopes), --buyer-public-key (X25519), --buyer-id, --owner-private-key-file, --output-dir.

Optional: --max-file-size (bytes per access file, default 512000), --json (summary with per-file listing).

Exit codes: 0 success, 1 validation (invalid keys, no chunk files, malformed chunk, --max-file-size <= 0), 2 key-commitment mismatch, meaning the wrong owner key.

peaqos stream consume

Buyer-side: decrypt a purchased chunk chain and reassemble the original data. Reads the chunk envelopes, the encrypted .bin blobs, and the buyer access files (filtered to --buyer-id), verifies the chain (unless --skip-verify), decrypts each chunk with the buyer’s X25519 private key, and writes the result to --output. Two input modes:

• Local (offline): --chunk-dir, --access-dir, and --data-dir point at directories already on disk.
• Remote: --download-url points at an HTTP/HTTPS self-contained release package bundling the envelopes, .bin blobs, and access files, exposed as a manifest.json file listing or a ZIP archive. The package is downloaded into a work directory (--work-dir, or a temp dir cleaned up after success unless --keep-files; preserved on any error for debugging), then the same verify → decrypt → reassemble pipeline runs. --download-url is mutually exclusive with the three directory flags.

--download-url does not consume the pre-signed URL from peaqos stream distribute: that URL delivers only the first buyer-access file, while the chunk envelopes and ciphertext stay behind each chunk’s storageRef. A full distribute to consume roundtrip needs a self-hosted bundle as described above.

# Local mode: directories already on disk
peaqos stream consume \
  --chunk-dir ./out \
  --access-dir ./buyer-access \
  --data-dir ./out \
  --buyer-private-key-file ./buyer-x25519.key \
  --buyer-id did:peaq:0xBUYER \
  --output ./recovered.bin

# Remote mode: fetch a self-contained release bundle
peaqos stream consume \
  --download-url "https://bundles.example.com/releases/ord-001/" \
  --buyer-private-key-file ./buyer-x25519.key \
  --buyer-id did:peaq:0xBUYER \
  --output ./recovered.bin

Required: --buyer-private-key-file (buyer X25519 private key), --buyer-id (must match the recipientId in the access files), --output (reassembled plaintext path), and, in local mode, --chunk-dir (envelopes), --access-dir (buyer access files), --data-dir (encrypted .bin blobs).

Optional: --download-url (remote release package; a query token on the URL is preserved when fetching each file), --work-dir / --keep-files (remote mode only), --skip-verify (skip chain verification; debugging only), --json (summary to stdout: output, totalBytes, chunkCount, sourceHash, buyerId, verified).

Exit codes: 0 success, 1 validation (empty --buyer-id, unreadable key, missing input files or dirs, --download-url combined with a directory flag or with a non-http(s) scheme), 2 decryption, integrity, or download failure (HTTP error, timeout, invalid ZIP). The buyer-side messages are specific: a wrong or ungranted key gives Decryption failed for chunk <index> with “access not granted for this buyer private key”; a mismatched --buyer-id gives No buyer access for chunk <index> (<chunk-id>); a tampered chunk gives Data integrity check failed for chunk <index> with “plaintext hash mismatch”.

peaqos stream distribute

Seller-side. Listen for a buyer’s payment confirmation, then automatically generate buyer access files (same re-key as stream grant) and deliver them to S3 under {prefix}{buyer_id}/, returning a pre-signed download URL. Polls --confirmation-url every --poll-interval seconds (default 30) until the endpoint reports a confirmed payment or --timeout seconds (default 3600) elapse. The confirmation endpoint must return JSON with status: "confirmed", an order_id matching --order-id, and non-empty strings for buyer_id, buyer_public_key_hex, and tx_hash; confirmed_at is optional.

peaqos stream distribute \
  --chunk-dir ./out \
  --owner-private-key-file ./owner-x25519.key \
  --confirmation-url https://api.example.com/orders/ord-001/status \
  --order-id ord-001 \
  --delivery s3 \
  --s3 s3://my-bucket/distributes/

Required: --chunk-dir (published envelopes from stream publish), --owner-private-key-file (the X25519 key used at publish time, one line of 64 hex with an optional 0x prefix), --confirmation-url, --order-id, --delivery (currently only s3), and --s3 (bucket path).

Optional: --poll-interval, --timeout, --s3-region, --s3-endpoint (MinIO / R2 / S3-compatible), --presign-expiry (seconds, default 3600), --max-file-size (bytes per access file, default 512000), --json. S3 needs the extra (pip install "peaq-os-cli[s3]") and credentials via PEAQOS_S3_ACCESS_KEY_ID + PEAQOS_S3_SECRET_ACCESS_KEY or the standard boto3 chain.

Exit codes: 0 success, 1 validation (no chunk files, unreadable key, non-positive interval/timeout, --delivery s3 without --s3), 2 confirmation timeout or S3 upload failure, 3 boto3 missing. In the SDK, the same loop is PollingConfirmationProvider + distributeData, where a P2P delivery channel can replace S3.

peaqos stream pay

Buyer-side. Transfer tokens on-chain to a seller, native or ERC-20/SPL on peaq, base, or solana, and optionally submit the transaction hash as payment proof in the same run. With --confirmation-url, proof is submitted right after the transfer; without it, only the transfer executes and the CLI prints the matching peaqos stream payproof command. In human output the tx hash is written to stdout before the proof step, so it survives a failed proof submission. With --json the one JSON object prints after the proof step; when proof submission fails it still carries the tx hash, with proof set to null.

# Base USDC transfer with proof submission
peaqos stream pay \
  --seller-address 0xSeller... \
  --amount 1.0 \
  --chain base \
  --order-id order-002 \
  --rpc-url https://mainnet.base.org \
  --token-address 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --confirmation-url https://api.example.com/payments/proof

Required: --seller-address (EVM 0x... or Solana base58), --amount (human-readable, e.g. "10.5"), --chain, --order-id.

Optional: --confirmation-url, --token-address (ERC-20 contract or SPL mint; omit for the native token), --token-decimals (override for tokens outside the well-known registry), --rpc-url (required for base and solana), --private-key-file (falls back to PEAQOS_PRIVATE_KEY; EVM chains only), --json (proof is null when no confirmation URL was given). --chain solana signs with the OWS wallet’s Solana account instead: it needs PEAQOS_OWS_WALLET (and OWS_PASSPHRASE when non-interactive), the raw key is ignored for the Solana transfer (the OWS wallet’s Solana account signs).

Exit codes: 0 success, 1 validation or signing failure (messages never contain key material; Solana support needs pip install "peaq-os-sdk[solana]"), 2 insufficient balance, revert, or proof HTTP failure, 3 missing config.

peaqos stream payproof

Buyer-side. Submit payment proof for a transfer completed outside peaqos stream pay, or retry a proof step that failed.

peaqos stream payproof \
  --tx-hash 0xabc123... \
  --order-id order-001 \
  --confirmation-url https://api.example.com/payments/proof \
  --chain peaq \
  --payer-address 0xPayer... \
  --payee-address 0xSeller... \
  --amount 10.5

Required: --tx-hash (EVM hash or Solana signature), --order-id, --confirmation-url, --chain, --payer-address, --payee-address, --amount (must match the original transfer). Optional: --token, --token-address, --json. Exit codes: 0 success, 1 validation, 2 proof HTTP failure, 3 missing config.

Solana payments

There is no peaqos solana command group. Solana is selected per command: peaqos activate --chain solana homes a machine there (Solana home), and peaqos stream pay --chain solana sends native or SPL transfers itself (requires --rpc-url and, for SPL, the mint via --token-address; install with pip install "peaq-os-sdk[solana]"). Solana-quoted Machine Market orders are paid externally: complete the SPL transfer with your own Solana wallet, then pass --payment-tx-hash to peaqos scale order so the orchestrator records it as the payment proof. Solana proofs are recorded, not verified on chain.

peaqos monetize

Manage a machine’s Economics 2.0 monetization decision in the MCR: status is a public read; opt-in and opt-out are signed, off-chain decisions. Thin wrappers over the SDK’s opt-in client: the SDK runs the compatibility check, EIP-191 signing, retries, HTTP, and response validation; the CLI adds parsing, prompts, and output.

The MCR at https://mcr.peaq.xyz serves the mirrored 2.0 machines and publishes the /.well-known/peaq-monetization signal. peaqos monetize status <decimal id> returns PENDING for a machine that has never opted in. agung-2026-08-28 has no paired MCR and exits 3 with CONFIG_ERROR.

peaqos monetize status  KEY [--timeout-seconds 30.0] [--max-unavailable-retries 2] [--unavailable-retry-delay-seconds 1.0] [--json]
peaqos monetize opt-in  KEY [same options] [--yes] [--json]
peaqos monetize opt-out KEY [same options] [--yes] [--json]

KEY is a canonical decimal machine ID or did:peaq:<decimal machine id>. Address DIDs (did:peaq:0x…), leading zeros, signs, hex, and exponents are rejected locally: there is no translation from a 1.0 address DID to a 2.0 machine ID.

Every command requires TOKENOMICS_DEPLOYMENT_ID. The SDK resolves the MCR URL, chain ID, MachineRegistry, and API version from that deployment and the server’s live compatibility signal (GET /.well-known/peaq-monetization). PEAQOS_MCR_API_URL, IDENTITY_REGISTRY_ADDRESS, and PEAQOS_RPC_URL are not read, and the retired --api-url flag is accepted only to be rejected: it exits 3 with migration guidance. status needs no signer; writes sign with the selected OWS wallet or, without one, PEAQOS_PRIVATE_KEY, and the signing address must be the machine’s current owner or DID controller (a machine-wallet-only key or a 1.0 operator key is not authorized).

Before a write the CLI reads the current state; an already-satisfied state returns without a prompt, signature, or PUT. Only 503 MACHINE_UNAVAILABLE is retried. A timeout during a PUT is ambiguous (the MCR may have applied it): rerun the same command, which reads first and sends no second PUT if the state is already there.

# Replace the example ID with your own machine ID
peaqos monetize opt-in did:peaq:57896044618658097711785492504343953926634992332820282019728792003956564819975
peaqos monetize status 57896044618658097711785492504343953926634992332820282019728792003956564819975 --json

{ "machine_id": "57896044618658097711785492504343953926634992332820282019728792003956564819975", "status": "OPTED_IN", "signer": "0x7099...79C8", "updated_at": 1783944004 }

2.0 state starts at PENDING; Tokenomics 1.0 decisions and signatures are not imported.

Situation	Exit
Invalid or non-canonical KEY or option value; declined prompt; non-TTY write without --yes	1
Signer not owner or controller (UNAUTHORIZED_SIGNER); ineligible opt-in (MACHINE_NOT_BONDED, MACHINE_DEACTIVATED); network, timeout, or API rejection	2
Missing or unknown TOKENOMICS_DEPLOYMENT_ID; incompatible or unreachable MCR (MONETIZATION_API_INCOMPATIBLE)	3

peaqos monetize provision

Provision an opted-in machine as a compute provider node from a schema-driven manifest, entirely from the terminal. Thin wrappers over the SDK’s manifest runner: every command, secret redaction, and verification probe runs inside the SDK; the CLI adds prompts, terminal rendering, and the resume state file.

peaqos monetize provision run       <provider> --machine <key> [--mode manual|auto] [--grant-sudo]
peaqos monetize provision preflight <provider> [--inputs <file>]
peaqos monetize provision verify    <provider> [--state-file <path>] [--json]

• <provider> is the manifest provider key (for example akash). Requires PEAQOS_MANIFEST_REPO_URL or --manifest-repo; --manifest-version pins a manifest version (default: latest).
• run walks the full flow: monetization pre-check (anything but OPTED_IN stops before the manifest is even fetched), manifest fetch pinned by sha256, input collection (--inputs file plus hidden prompts for secrets), blocking pre-flight, provisioning with a state checkpoint after each step, and verification probes that alone decide success.
• --mode manual (default) confirms each command; --mode auto runs unattended and requires --grant-sudo, scoped to the manifest’s allowedCommands. Owner-action handoffs (funding, DNS, signing) always pause, even with --yes.
• --machine takes a decimal machine ID or did:peaq:<decimal id> (address DIDs are rejected), so the machine wallet address for the manifest’s commission context must come from PEAQOS_MACHINE_WALLET_ADDRESS. Unset it before provisioning a different machine. The monetization pre-check goes through the 2.0 SDK read against the deployment’s MCR (mcr.peaq.xyz).
• --resume continues an interrupted run from the state file (default ./peaqos-provision-state.json, written atomically with 0600). Non-secret inputs are restored; secrets are re-prompted, never persisted.

# Full manual run
PEAQOS_MACHINE_WALLET_ADDRESS=0x9a5F...37C5 peaqos monetize provision run akash \
  --machine 57896044618658097711785492504343953926634992332820282019728792003956564819975 --inputs ./akash-inputs.yaml

# Re-check a provisioned node against the pinned manifest
peaqos monetize provision verify akash --json | jq '.[] | select(.passed == false)'

peaqos verify

Read a machine’s Verify record and build local chip preflight artifacts. Experimental: the command names are stable for v1 beta, the output may still change. Reads need only a Verify API origin: no wallet, private key, RPC or TOKENOMICS_DEPLOYMENT_ID. Available from peaq-os-cli 0.0.14 (pip install --upgrade peaq-os-cli).

export PEAQOS_VERIFY_API_URL=https://mcr.peaq.xyz   # or the root flag --verify-api-url

peaqos verify status 123          # 123 is a placeholder (prints "Machine not found in the Verify service."); put in your own machine ID
peaqos verify status 123 --json

The root option --verify-api-url <origin> (before the command name) takes precedence over PEAQOS_VERIFY_API_URL, which the CLI also reads from .env. The value must be an HTTPS origin; there is no default and no fallback to the MCR host, so a missing value exits 3 with Set PEAQOS_VERIFY_API_URL to a valid HTTPS origin.

peaqos verify status

One GET /v1/verify/machines/{machineId} through the SDK read client (API reference): one attempt, five-second deadline, no retry, no redirect, no cache. MACHINE_ID is the decimal machine ID (1 to 2^256-1, no leading zeros); a DID or an address exits 1.

Human output prints the machine DID, the home chain (peaq (EVM), Agung testnet (EVM), Solana, or EVM chain <id> for an unnamed chain), the DID controller, the operator, the KYB and chip statuses, and Source: Verify API. --json prints the API record unchanged: machineId, machineDid, homeChain, didController, operator, verification.kyb.status, verification.chip.status. The root option --quiet (peaqos --quiet verify status ...) keeps the data output.

Each status is unverified, verified, expired or revoked. An existing machine with both unverified is a successful read.

Exit	When
0	Record printed (including unverified)
1	MACHINE_ID is not a canonical decimal in range
2	Machine not found, rate limited, service unavailable, timeout, connection failure, an invalid response, or canceled with Ctrl+C
3	No or invalid PEAQOS_VERIFY_API_URL, or an installed peaq-os-sdk without peaq_os_sdk.verify

An unknown machine prints Machine not found in the Verify service. and a rate limit prints Verify API rate limit reached; retry later. A 503 prints Verify state is temporarily unavailable; retry later. A Solana-homed machine always gets this message, and retrying does not help. A canceled read prints Verify status request was canceled; retry when ready. An invalid response says do not treat it as verification state.

peaqos verify chip

Three stages that turn a challenge, the chip’s leaf certificate and two signatures into the canonical peaq.verify.chip-evidence/1 document peaq’s onboarding service submits. Every option is a file path, so no nonce, signature or certificate lands in argv or shell history. The commands never talk to the chip, a wallet or the Verify API, and hold no key: the chip signature comes from the secure element, the controller signature from the DID controller’s wallet. Each stage rebuilds the earlier ones from the same files, so nothing is cached or resumed. Chip preflight is EVM-only in v1. The full flow, including the challenge and the submission the onboarding service runs, is in Verify a chip, end to end.

# 1. context.json holds six fields of the onboarding service's challenge; leaf.der is the certificate read from the chip's 0xE0E0 object
peaqos verify chip prepare \
  --context context.json --certificate leaf.der --out prehash.bin

# 2. Have the chip's 0xE0F0 key sign prehash.bin (ECDSA without hashing, it is already the digest) -> chip-signature.bin
peaqos verify chip controller-request \
  --context context.json --certificate leaf.der \
  --chip-signature chip-signature.bin --out controller-message.bin

# 3. Have the current DID controller sign controller-message.bin once as an EIP-191 personal message -> controller-signature.bin
peaqos verify chip finalize \
  --context context.json --certificate leaf.der \
  --chip-signature chip-signature.bin \
  --controller-signature controller-signature.bin --out evidence.json

Flag	File	Limit
--context	The challenge the onboarding service issued	Strict JSON with exactly chainId, didController, expiresAt, machineDid, machineId and nonce, all strings, at most 4096 bytes. The challenge response also has profile, protocol and verifier; remove them first (jq '{chainId, didController, expiresAt, machineDid, machineId, nonce}')
--certificate	Leaf certificate from 0xE0E0	At most 1300 DER bytes
--chip-signature	Chip signature in the chip’s native form: r and s as two DER integers with no SEQUENCE header	At most 80 bytes
--controller-signature	DID controller signature as raw binary (r, s, v with v 27 or 28), not hex	Exactly 65 bytes
--out	The artifact to write	Must not exist yet. Created 0600 and never overwritten, so there is no --force

Every stage prints Authority: local preflight only; finalize also prints the fixed identifiers:

• Protocol: peaq.verify.chip-proof/1
• Profile: infineon-optiga-trust-m-express-ca306/1
• Evidence Schema: peaq.verify.chip-evidence/1
• Trust Bundle: infineon-optiga-trust-m-express-ca306-roots/1
• Revocation Status: not_evaluated

--json on any stage prints one metadata object (stage, artifact, byteLength, authority, plus the five identifiers on finalize) and never the artifact bytes, a path, a DID or an address.

Hand evidence.json unchanged to the onboarding service that issued the challenge; it submits the file with POST /v1/verify/chip/evidence. Delete the artifacts afterwards. A successful finalize is not a verified machine. Read the state with peaqos verify status.

The challenge is valid for at most five minutes and every stage rechecks it against the local clock. Failures print one line naming the input and the constraint, for example Chip prepare failed because the challenge is outside its freshness window. Request a new challenge and retry.

Exit	When
0	Artifact written
1	Invalid input file, rejected chip or controller signature, expired challenge, or --out cannot be created
2	Unexpected internal failure, or canceled with Ctrl+C (Chip <stage> was canceled; retry when ready.)
3	Installed peaq-os-sdk without the preflight functions

peaqos scale

Machine Market orchestration commands. Pair an AI agent to an activated machine, search the curated catalogue, and drive the full purchase loop.

The peaqos scale surface: agent pair, machine onboard (plus machine status [MACHINE_ID] and machine list, both with --json; list exits 0/2/3, status 0/1/2/3), search, and the scale order family: place (dispatched from a service UUID), status, list with cursor pagination, received, dispute. Order placement also supports the x402 payment rail.

Setup

Two env vars, both optional in load_client(). Override at any point with the root-level flags --orchestration-url / --orch-api-key.

Env var	CLI override	Purpose
PEAQOS_ORCHESTRATION_URL	--orchestration-url <url>	Machine Markets API base URL
PEAQOS_ORCH_API_KEY	--orch-api-key <key>	Platform API key (x-api-key header)

Scale is paused. Registering a machine with the Machine Markets API fails for Tokenomics 1.0 and Economics 2.0 machines (see Scale). With TOKENOMICS_DEPLOYMENT_ID set, the SDK refuses every orchestration call that binds a machine identity (scale machine onboard | list | status, scale agent pair, scale search) with TokenomicsIntegrationUnavailableError (see the SDK gate table). Without it, the orchestrator cannot resolve a Tokenomics 1.0 machine’s identity and machine-bound calls return PEAQOS_IDENTITY_UNAVAILABLE.

peaqos init prompts for both during the wizard and writes them as active .env lines (not commented placeholders). The API key is entered at a hidden prompt (not echoed to the terminal), then written to .env in plaintext, so treat the file as a secret:

# Machine Market orchestration
PEAQOS_ORCHESTRATION_URL=https://orchestration.peaq.xyz
PEAQOS_ORCH_API_KEY=<your-orch-api-key>

peaqos init --non-interactive reads both from existing env vars.

The pairing token returned by agent pair is the credential for agent-side commands. Save it once to a single-line file with chmod 600 and reference it via --pairing-token-file.

peaqos scale machine onboard

Operator-facing. Walks a machine through the four-step orchestration onboard: request an identity challenge, sign with the DID controller key, register the machine with proof attached, then activate (unless --skip-activate). Hits POST /api/v1/machine-identity/challenges and POST /api/v1/machines.

peaqos scale machine onboard \
  --identity-ref did:peaq:0xMachineWallet \
  --display-name "rover-014" \
  --owner-id op_xyz \
  --machine-type qvac \
  --runtime-profile machine-runtime-agent

Required: --identity-ref, --display-name, --owner-id, --machine-type, --runtime-profile.

Optional: --capabilities (CSV), --skill-keys (CSV), --labels (KEY=VALUE,...), --identity-signature-file, --identity-key-file, --skip-activate, --yes, --json.

Signing inputs: --identity-signature-file (a one-line hex signature you produced externally) or --identity-key-file (the CLI signs in-process with the DID controller’s private key); supplying both is rejected. With neither, the CLI signs with the selected OWS wallet, or prompts for a signature interactively.

Exit codes: 0 happy path, 1 input error, 2 server / proof error (MACHINE_IDENTITY_EXISTS, MACHINE_IDENTITY_PROOF_INVALID, PEAQOS_IDENTITY_UNAVAILABLE), 3 missing PEAQOS_ORCHESTRATION_URL.

peaqos scale agent pair

Operator-facing. Pairs an AI agent to a machine via a three-step challenge-sign flow. Returns a one-time signed-JWT pairingToken.

Internally the command:

1. Calls client.orchestration.create_agent_pairing_challenge(machine_id, params) for a server-issued challenge keyed to agentAddress, agentProvider, agentRole, and optional agentDid.
2. The Machine Agent signs the returned challenge message (EIP-191) with the wallet key behind agentAddress. Supply the signature via --agent-signature-file <path>.
3. Calls client.orchestration.create_agent_pairing(machine_id, params_with_proof) to persist the pairing and issue the session JWT.

peaqos scale agent pair \
  --machine-id mach_61f043950cf1 \
  --agent-address 0xagent...0101 \
  --agent-did did:pkh:eip155:1:0xagent...0101 \
  --agent-provider teneo \
  --agent-role machine-market-buyer \
  --agent-signature-file ~/.peaqos/agent-challenge.sig \
  --per-tx-limit 5 --daily-limit 20 --currency USD \
  --allowed-skills agentic-market-claude-inference,pay-sh-gemini \
  --allowed-service-ids svc_abc \
  --denied-service-ids svc_xyz

Required: --machine-id, --agent-address, --agent-provider, --agent-role.

Optional: --agent-did, --agent-signature-file (path to pre-signed EIP-191 challenge signature; required with --json, otherwise the CLI prompts interactively), --description, --per-tx-limit, --daily-limit, --currency, --allowed-skills (CSV), --denied-skills (CSV), --allowed-service-ids (CSV), --denied-service-ids (CSV), -y/--yes to skip the confirmation prompt, --json for raw JSON (implies --yes).

Preconditions: PEAQOS_ORCH_API_KEY set. Machine already active in peaqOS or the server returns MACHINE_NOT_ACTIVATED and the CLI exits 2.

The pairing summary includes Agent DID, Session ID, Session Expires, and Verification lines. The token prints exactly once on stdout, never written to peaqos.log or --verbose output. Pipe to a file:

peaqos scale agent pair ... --json | jq -r .pairing_token > ~/.peaqos/agent.token
chmod 600 ~/.peaqos/agent.token

Session tokens expire (default 1 hour). Rotate directly via client.orchestration.create_agent_pairing_session(...) (Python) or createAgentPairingSession(...) (JS) from your own tooling, signing a fresh challenge.

peaqos scale search

Agent-facing. Posts a market search and returns ranked service quotes. Hits POST /api/v1/market/search and renders the search record that request returns.

peaqos scale search \
  --machine-id mach_1 \
  --service-type oracle.price-feed \
  --pairing-token-file ~/.peaqos/agent.token \
  --budget-amount 1 --budget-currency USD \
  --native-only

Required: --machine-id, --service-type, --pairing-token-file.

Optional: --agent-pairing-id, --operation, --capabilities (CSV), --region, --max-results, --budget-amount, --budget-max, --budget-currency, --native-only, --allow-handoff, --provider-credentials (path to JSON), --json.

Preconditions: machine active with verified identityRef, active agent pairing, pairing token in the token file. Provider credential file contents never appear on stdout, stderr, or in log output.

Output:

• Human mode: ranked quote table with columns Service ID, Quote ID, Operation, Provider, Score, Execution, Integration. Footer prints Search ID: msearch_... plus a concrete next-step hint: peaqos scale order <service-id> --search-id <search-id> --quote-id <quote-id>.
• Empty results print No matching services found. with the same aligned Search ID: line and broaden-your-search guidance.
• --json emits the full MarketSearch envelope. The raw MarketSearchRequest is constructed from typed SDK data classes, not raw dicts.

The order group is dynamic-dispatch. Any first token that is not status, list, received, or dispute is interpreted as a service UUID and routed to the placement flow. peaqos scale order foo-bar reads as “place an order for service foo-bar.”

peaqos scale order <service-uuid>

Agent-facing. End-to-end purchase. Hits the POST /market/orders + payment intent + execute flow. Four payment paths chosen from the MarketPayment returned at order create:

• No payment: create → execute (2 steps).
• Wallet payment: create → intent → transfer → proof → execute (5 steps). If PEAQOS_OWS_WALLET is set the CLI auto-signs the ERC-20 transfer via OWS; otherwise it prompts for a pasted tx hash (or use --payment-tx-hash).
• Escrow / handoff: same five steps with the escrow rail.
• x402: create → intent → sign → proof → execute → confirm (6 steps), for paid-HTTP Agentic Market providers (e.g. Wolfram Alpha over USDC on Base). The CLI signs the provider’s payment challenge locally with the active wallet (client.account, the OWS wallet when PEAQOS_OWS_WALLET is set, otherwise the local key) and hands the signed PAYMENT-SIGNATURE header to peaqOS, which pays the provider during execute. No separate on-chain transfer, no tx-hash prompt; delivery is confirmed automatically in step 6. If execution fails after proof is recorded, the error reports the current payment status so you can check whether the authorization is held.

Set PEAQOS_ORDER_STEP_DELAY_SEC to a non-negative number of seconds to pause between placement steps (demos, eventually-consistent order state); unset means no delay.

Required: --machine-id, --agent-pairing-id, --pairing-token-file.

Optional: --search-id, --quote-id, --operation, --budget-amount, --budget-currency, --input <path> (JSON object file; there is no @file shorthand), --provider-credentials <path> (JSON file with provider creds; never logged), --payment-tx-hash, --payment-chain (CAIP-2 alias: base, peaq, agung, ethereum/eth, polygon, arbitrum, optimism, bsc, solana), --payment-token (both required with --payment-tx-hash), --skip-payment (requires --payment-tx-hash), -y/--yes, --json.

PEAQOS_RPC_URL supplies the payment RPC for peaq; the other chains have built-in endpoints. Without it a peaq payment exits with a configuration error pointing at --payment-tx-hash.

Error codes: QUOTE_EXPIRED, EXECUTION_UNSUPPORTED, PAYMENT_REQUIRED, PAYMENT_RPC_ERROR, PAYMENT_TX_FAILED, PAYMENT_TRANSFER_NOT_FOUND, ORDER_CLOSED, ORDER_NOT_DELIVERED, NOT_FOUND.

--json suppresses placement progress and prints the JSON envelope to stdout. Global --quiet suppresses progress in human mode and sets logging to ERROR; errors still print to stderr.

peaqos scale order status <order-id>

Returns current state of the purchase. Read-only platform auth. Hits GET /market/orders/:orderId plus the payment lookup.

Optional: --json for the { order, payment } envelope.

Missing payment record (NOT_FOUND) is not an error: payment is null in the JSON envelope. Missing order ID exits 1.

peaqos scale order list --machine-id <id>

Lists orders for a machine. Hits GET /market/orders?machineId=....

Required: --machine-id.

Optional: --limit <int> (1-500, server default 100; outside range exits 1), --cursor <opaque> (from a prior next_cursor; never logged), --json.

Output behaviour:

• Human mode: one page, N order(s) shown. footer. When next_cursor is set, the CLI prints a copy-paste hint: Next page: peaqos scale order list --machine-id <id> [--limit N] --cursor <verbatim>.
• --json without --limit: auto-paginates all pages and emits a flat root-level JSON array.
• --json with --limit: emits a single-page envelope { "items": [...], "next_cursor": ... }.

The CLI surfaces next_cursor (snake_case) on stdout; the wire field is nextCursor.

peaqos scale order received <order-id>

Confirms delivery and marks the payment for release. It does not move funds. Requires --pairing-token-file. Hits POST /market/orders/:orderId/confirm.

Optional: --json.

Status moves to confirmed, payment to release_pending. Error codes: ORDER_NOT_DELIVERED, ORDER_CLOSED, AGENT_AUTH_INVALID. Missing order ID or token file exits 1.

peaqos scale order dispute <order-id>

Raises a dispute. Requires --reason and --pairing-token-file. Hits POST /market/orders/:orderId/dispute.

Optional: --evidence <path> (JSON object file), -y/--yes to skip the Raise dispute? [y/N] prompt, --json (also skips the prompt).

Status moves to disputed, payment to frozen. Error codes: ORDER_CLOSED, AGENT_AUTH_INVALID. Missing order ID, reason, or token file exits 1.

Exit codes

Every subcommand funnels SDK and network exceptions through a single error handler that raises with a stable exit code.

Exit code	Meaning
0	Success
1	User / validation error (invalid DID, a cap or rate-limit value the CLI rejects before any RPC, declined prompt). A quoted cost above a cap and an RPC that rate-limits reads are chain-side and exit 2. An unknown flag or a value Click rejects exits 2 with a usage message
2	Network, RPC, or on-chain error (connection failure, HTTP, revert)
3	Configuration error (missing env var, invalid private key file, unknown or missing TOKENOMICS_DEPLOYMENT_ID, incompatible MCR, Solana selected without PEAQOS_SVM_RPC_URL or without the [solana] extra, an SDK whose deployment record lacks a feature: RENEWAL_TIER_UNSUPPORTED, LINK_PUSH_UNSUPPORTED, PEER_UNSET)

peaqos verify uses 1, 2 and 3 with the meanings in its own tables (verify status, verify chip): verify status exits 2 for an unknown machine, and verify chip exits 1 for a rejected signature or an expired challenge and 2 only for an unexpected failure or a cancellation. A missing PEAQOS_VERIFY_API_URL is a configuration error (3). peaqos activate adds a stable error_code to every failure after input validation (see peaqos activate). peaqos machine status --json and peaqos monetize status --json print exactly one JSON object on failure, with status: "error", error_code (for example CONFIG_ERROR), message, guidance, plus sdk_code on machine reads and context on the MCR and monetize commands; the exit code is unchanged. Every peaqos machine write prints the same structured object for a failure inside its runner (plus the retained transaction context); input validation and configuration errors before the runner starts print a plain message. The other peaqos monetize subcommands print the message only under --json.

See also

peaqOS AI

The peaqOS agent skill that drives these CLI flows from any AI agent.

SDK reference

The TypeScript / Python API the CLI wraps.

API reference

The MCR API that qualify mcr, show machine, and show operator machines hit.