peaq-os-sdk

Python SDK for the peaqOS protocol. Provides a typed wrapper around the peaq on-chain capabilities so integrators can activate and manage machines, submit events, and query credit ratings without writing raw web3.py boilerplate.

Machine activation

On peaq, one transaction mints the machine NFT, stores its DID document, activates its subscription, and registers its home chain.

Every client selects a deployment by ID from the SDK's approved snapshot: peaq-mainnet unless deployment names another. Contract addresses are never passed by callers.

from peaq_os_sdk import PeaqosClient, DeploymentConfig

client = PeaqosClient(
    rpc_url="https://peaq-agung.api.onfinality.io/public",
    private_key=os.environ["PRIVATE_KEY"],
    deployment=DeploymentConfig(deployment_id="agung-2026-08-28"),
)

preview = client.preview_machine_activation(params)   # no signing, no writes
result = client.activate_machine(params)              # one atomic transaction
print(result.machine_id, result.net_peaq_amount)

See docs/18_ACTIVATION.md for configuration, the preview/activate flow, the bond and voucher arithmetic, the full error taxonomy, reconciling an unconfirmed transaction, operator-run machines (the machine signs, the operator is controller), and how to add a network.

Machine management

After onboarding, the same deployment-selected client exposes aggregate state and availability reads, suspend/resume, PEAQ and USDT subscriptions, ERC-721 ownership, DID updates, side-effect-free action previews, and read-only reconciliation for a known transaction hash. Owner, controller, and payer authority remain distinct, and every write correlates contract-scoped events before reconciling post-state.

See docs/19_MACHINE_MANAGEMENT.md for the authority matrix, bounded payment flows, release notes, and relocation-read semantics.

Solana onboarding and reads

The existing activation APIs onboard a Solana machine terminal-first (CORE-801): the wallet is registered on peaq, the activation is requested, credited, finalised and bonded on Solana, the machine is minted against that bonded request and then linked to peaq. Keyless previews and status, staged submission, a durable journal and recovery cover every phase. Existing EVM activation behavior is unchanged.

The link push travels one of two ways, chosen by the deployment, not the caller. Both mainnet sets run a CORE-781 adapter (adapter_generation="core_781"; peaq-mainnet since 2026-10-06): the SDK reads info_desk's route and, as production is configured, queues the push for peaq's Trust Validator node, which delivered it to peaq in 44 to 91 seconds on the production runs: no LayerZero fee, max_link_push_fee_lamports not needed. A missing TvOutbox (TV_OUTBOX_MISSING) or peaq refusing node deliveries (TV_INBOUND_REFUSED) is refused before signing. LayerZero is the fallback a deployment may select on the route; only then is the fee cap required.

scripts/onboard_solana.py is the end-to-end example: it ran the production onboardings of 2026-10-06 in PEAQ and in USDC from one command each (TICKET-ADD-SVM-023). See the Solana onboarding guide for configuration, signer selection, examples, status and recovery. See Solana reads for home resolution and native account observations.

peaq RPC: retries, rate limits and call counts

PeaqosClient talks to peaq through PeaqHTTPProvider (TICKET-TKNA-007):

• Chain id. It is asked once per client.
• Retries, reads only. Rate limits (HTTP 429, -32029) back off from 0.5 s, at most five attempts, honouring Retry-After. A transient failure is retried once after 1 s. Submissions are sent exactly once.
• Time budget. Solana onboarding operations bound every retry pause by their timeout_seconds.
• One block per read. A read operation pins one finalized peaq block.
• Log windows. History reads split eth_getLogs into windows of at most 5,000 blocks, so an endpoint that caps the range (QuickNode: 10,000) keeps working as machines age.
• Errors. A failed read names the request: ActivationError.rpc_method and .rpc_host (host only, never the path or query where an API key lives). An exhausted rate limit is RPC_RATE_LIMITED.

To see how many calls an operation makes, enable DEBUG on the peaq_os_sdk.rpc logger (one rpc calls for <operation>: total=N … line per operation), or run the counting proxy:

python scripts/count_rpc_calls.py --upstream-env PEAQOS_RPC_URL --port 18545 --log rpc-calls.log

Point the client at http://127.0.0.1:18545, run the operation, then press Ctrl-C for per-method totals. The proxy never prints the upstream URL.

Solana machine management

Writes for Solana-homed machines go through the same entry points as their peaq equivalents — transfer_machine, set_machine_controller, the three DID setters, and suspend_machine/resume_machine take an optional solana=SolanaMachineWriteParams(...). A caller who passes none sees exactly the shipped EVM behaviour; no machine-keyed method gained a chain argument. set_machine_evm_operator is the one addition with no peaq sibling, because on peaq the owner already is the EVM address.

For read-only management, PeaqosClient.preview_machine_action(SolanaMachineActionParams(...)) returns SolanaMachineActionPreview, while reconcile_machine_management_transaction(native_attempt, native_context) takes NativeManagementTransaction and SolanaManagementReconciliationContext and returns SolanaManagementReconciliation. Both client methods preserve the corresponding EVM overloads and precise return types; reconciliation requires the attempt and context to belong to the same variant. Native previews accept a public signer identity and require no signing account.

The signer is an argument rather than client configuration: Solana's key space and the EVM account's are unrelated, and the action is authorized as that signer's public key. Three ERC-721 operations — approve_machine, set_machine_approval_for_all, safe_transfer_machine — are refused by name with SOLANA_OPERATION_UNSUPPORTED before any RPC or signature, rather than rejected as unknown.

A transaction that landed and then disagreed comes back as a result carrying its conflicts, not as an exception, because a caller told only "mismatch" cannot tell that their own action succeeded. Confirmation requires the transaction, the action's own event from the expected program for this machine, and the complete expected post-state including the fields the action was not supposed to change. pending means "not yet known", never "failed".

Confirming locally never implies peaq has applied anything: set_machine_evm_operator returns the two in two fields, and synchronization is established only by peaq's own lastAppliedMirrorPushSeq watermark keyed by Solana's protocol chain ID (5) — not its LayerZero endpoint ID and not peaq's EVM chain ID. Matching operators, NothingToPush, a skipped send and a source sequence are each true of a push that was dropped in transit, so none of them counts. The SDK sends no cross-chain message and changes no bridge configuration.

See docs/21_SOLANA_MACHINE_MANAGEMENT.md for the authority table, the explicit clearing rules, DID rent direction, and how expired is the only reconciliation state that licenses a fresh attempt.

Two subscription accounts, selected by deployment record

Two generations of the Solana programs are live. Before CORE-778 they read a machine's subscription from the adapter-owned SubscriptionMirror; since CORE-778 they read the terminal-owned SubscriptionTerminal, which carries a status as well as a tier. The deployment record says which, through subscription_reader ("mirror" or "terminal") and machine_subscription_terminal. Only that field decides — not the packaged IDL's account name, not metadata.version (0.1.0 in both), and not whether either account exists. A "terminal" record with no terminal program ID fails at resolution with DEPLOYMENT_UNAVAILABLE, before any RPC, rather than falling back to an account the deployed programs no longer read.

The eligibility rules differ with it, and neither reads the tier: onboard_machine needs last_seq != 0 and a status of Active, Grace or Runoff (can_renew, since CORE-801); submit_event needs Active or Grace alone. Tier 0 is Entry, a real purchasable tier — never read it as "no subscription". An absent terminal account is ineligible for both, not tier zero.

Status reads report both accounts and name the authoritative one in subscription_source; nothing merges them into a single tier. subscription_terminal is None means the account was not read, never that it is absent. The two last_seq values count different streams — the adapter's tier push and peaq's status signal — and are never comparable.

The shipped peaq-mainnet record reads "terminal" and names the deployed terminal program 4EFBHr9AyazPA6cxZRYYU5eK6uguogG5YhPQX6cs6A9d: the official Solana set has run the CORE-778 readers since the production upgrade of 2026-09-16. The mirror generation stays implemented for a record whose programs still run pre-CORE-778 builds; none is shipped. See docs/20_SOLANA_READS.md for the full field list, the readiness table and what the shipped record uses.

Solana event submission

submit_event and batch_submit_events resolve each machine and write to the chain it is homed on. Callers never name a chain, and an EVM-only caller sees no change. The native path needs pip install peaq-os-sdk[solana].

from peaq_os_sdk.types.events import SubmitEventParams

# A Solana-homed machine: the same call, routed natively.
signature, data_hash = client.submit_event(
    machine_id=machine_id,          # full uint256, never narrowed
    event_type=0,                   # 0 revenue, 1 activity
    value=1_23,                     # subunit integer: US$1.23
    currency="USD",                 # omit for the same default
    timestamp=observed_at,          # checked against the cluster clock
    raw_data=payload,               # keccak256(payload); None means 32 zero bytes
    trust_level=0,
    source_chain_id=3338,           # provenance, not routing
    source_tx_hash=None,
    metadata=b"",                   # at most 256 bytes, refused not truncated
)

A batch is one transaction, which is what makes it atomic:

signatures = client.batch_submit_events([
    {**event_for(machine_a), "currency": "USD"},
    {**event_for(machine_a), "currency": "USD"},   # same log, consecutive indices
    {**event_for(machine_b), "currency": ""},      # activity event
])

Mixing peaq-homed and Solana-homed machines in one batch is refused before either chain is written. An oversized batch is refused rather than split, because a split batch would no longer be atomic.

The first event for a machine creates its log and the submitter pays the rent shortfall, once per machine however many events target it. Each intentional submission carries a random 128-bit ID in one SPL Memo instruction, which is what keeps two identical calls against one blockhash from collapsing into a single transaction. Retries reuse that ID and rebroadcast the same signed bytes; a timeout means unresolved, not failed.

Local confirmation proves the event was recorded on Solana. It does not prove that any downstream rating service has ingested it, that a score changed, or that peaq has synchronized. On chain the log keeps only its count and the most recent event, so there is no event enumeration and this SDK adds no history API.

See docs/03_EVENTS.md for the full gate list, the field differences from EVM, and what completion does and does not establish.

Install

pip install peaq-os-sdk

Dependencies installed automatically: web3, eth-account, requests, posthog.

For OWS wallet management (optional):

pip install peaq-os-sdk[ows]

For Solana transaction signing via OWS (optional):

pip install peaq-os-sdk[ows,solana]

For Stream buyer SPL token payments (optional):

pip install peaq-os-sdk[solana]

The solana extra installs solders (native SOL transfers and signing) and solana (provides spl.token for SPL transfers such as USDC).

For P2P stream delivery (optional):

pip install peaq-os-sdk[p2p]

The p2p extra enables machine-to-machine P2P delivery via the peaqos-p2p transport (P2PDeliveryChannel seller, P2PDeliveryReceiver buyer).

Solana signing from an OWS wallet

When open-wallet-standard and solders are installed, construct a standalone Solana signer from a vault wallet that has a Solana account:

from solders.hash import Hash
from solders.keypair import Keypair
from solders.message import Message
from solders.pubkey import Pubkey
from solders.system_program import TransferParams, transfer
from solders.transaction import Transaction

from peaq_os_sdk import PeaqosClient, SOLANA_MAINNET_CHAIN_ID

signer = PeaqosClient.solana_signer_from_wallet("my-wallet", "s3cret")
print(signer.address, signer.chain_id)  # chain_id == SOLANA_MAINNET_CHAIN_ID

from_pubkey = Pubkey.from_string(signer.address)
instruction = transfer(
    TransferParams(
        from_pubkey=from_pubkey,
        to_pubkey=Keypair().pubkey(),
        lamports=1_000,
    ),
)
message = Message.new_with_blockhash([instruction], from_pubkey, Hash.default())
tx = Transaction.new_unsigned(message)

signed = signer.sign_transaction(tx)
# broadcast with your Solana RPC client using signed.serialize()

By default (ows_signing=True), the ed25519 key is decrypted only per sign via OWS. Pass ows_signing=False to decrypt at construction and sign locally with solders. See docs/06_WALLET.md for details.

Requirements

• Python >= 3.10
• A peaq RPC endpoint
• A funded wallet for the proxy operator (or for the machine itself, in self-managed mode)

Quick start

from peaq_os_sdk import PeaqosClient

client = PeaqosClient(
    rpc_url="https://peaq.api.onfinality.io/public",
    private_key="0xYOUR_PRIVATE_KEY",
)

print("signer address:", client.address)
print("deployment:", client.deployment.deployment_id)  # "peaq-mainnet"

PeaqosClient is the only class consumers instantiate. All feature methods hang off it. The constructor performs synchronous validation and wires up the underlying Web3 provider + signing account — no network I/O is issued at construction time.

Read More here >>

MCR queries

Use PeaqosQueryClient() (peaq-mainnet unless deployment_id names another) for HTTP-only MCR reads without RPC, contracts, keys or wallet configuration. The SDK selects the paired endpoint; machine DIDs are did:peaq:<decimal>. All three methods reuse the same typed validation, response correlation and pooled HTTP transport as the full PeaqosClient. See the query client guide for examples and DID formats.

MCRResponse:

{
    "did": str,
    "machine_id": int,
    "mcr_score": int | None,    # 0–100, None if Provisioned
    "mcr": str,                 # "AAA" | "AA" | "A" | "BBB" | "BB" | "B" | "NR" | "Provisioned"
    "bond_status": str,         # "bonded" | "unbonded"
    "negative_flag": bool,      # active negative event flag
    "event_count": int,
    "revenue_event_count": int,
    "activity_event_count": int,
    "revenue_trend": str,       # "up" | "stable" | "down" | "insufficient"
    "total_revenue": float,
    "average_revenue_per_event": float,
    "last_updated": int | None,
}

OperatorMachinesResponse carries operator_did, a machines list of {did, machine_id, mcr_score, mcr, negative_flag} entries, and a pagination object. MachineProfileResponse returns structured NFT metadata with a validated peaqos sub-object. Every failure path is an ApiError with a stable .code (NOT_FOUND, SERVICE_UNAVAILABLE, SERVER_ERROR, HTTP_ERROR, BAD_RESPONSE, TIMEOUT, NETWORK_ERROR). See docs/03_QUERIES.md for the full endpoint and error reference.

Provider-node provisioning

The peaq_os_sdk.provisioning namespace is a generic, provider-agnostic runner that turns a schema-driven ProviderProvisioningManifest (node-provider.peaq.network/v1alpha1) into an ordered, auditable install. All provider-specific complexity lives in the manifest — the runner understands only the schema. It runs entirely on the machine and calls no external API.

from peaq_os_sdk import provisioning

manifest = provisioning.fetch_manifest("akash", "latest", repo_base_url="https://manifests.example")
inputs = provisioning.resolve_inputs(manifest, {"providerDomain": "node.example.com", ...})
executor = provisioning.LocalShellExecutor()

preflight = provisioning.run_preflight(manifest, executor)
preflight.raise_if_blocked()                       # gate: no phase starts while blocked

result = provisioning.provision(
    manifest, inputs, mode="manual", executor=executor,
    context={"machine_wallet_address": "0x..."},   # never the operator's
    on_owner_action=lambda e: input(e.instructions) or "confirmed",
)

verification = provisioning.verify_provisioning(
    manifest, executor, inputs=inputs.values, captures=result.captures
)
verification.raise_if_failed()                     # live only when all probes pass

• Manual vs auto modes are declared per step (manual / auto / both). Eligibility is asymmetric: a manual-only step still runs (confirmed) in an auto run, while an auto-only step is skipped in a manual run and left un-recorded for a later auto pass — so completed means this selected-mode pass finished. Auto mode requires a SudoGrant scoped to the manifest's allowedCommands; a sudo: required command outside the grant fails closed, and unmarked commands are never elevated.
• Owner-action handoffs (funding, DNS, SSH, signing) are real pause points — on_owner_action must return the step's expectedConfirmation; they are never auto-confirmed.
• Secrets never leak — and are never persisted. Secret inputs and secret captures are redacted before any output is emitted; a secret capture with no pattern withholds its step's raw stream entirely. Errors and resume state carry no secret material, and secret captures are never written to a resume state (not even encrypted).
• Idempotency & durable resume. A step's idempotency check short-circuits already-provisioned work. Every run emits a typed, JSON-serializable ResumeState (with a schema_version, completed phase/step ids, and resolved non-secret inputs) at each step boundary via on_state_change — and as ProvisionResult.resume_state / StepExecutionError.resume_state — which you pass back as resume_state= to skip completed steps and restore non-secret captures. A resumed step needing a non-persisted secret re-runs its producer when rerun: safe, else the caller can re-provide it via resume_secrets (manifest-declared secret keys only), else ResumeNotPossibleError.
• Deterministic manifest pinning. fetch_manifest(..., include_source=True) returns a FetchedManifest exposing the raw source bytes, so a caller can pin a stable sha256:<hex> digest.
• Verification, not exit codes, defines success — verify_provisioning succeeds only when every success.all_of probe passes (the caller passes inputs=inputs.values and a redaction registry seeded from inputs.secret_values()).

The runner is standalone; a CLI (or any other consumer) calls these functions. CLI-surface decisions (headless vs prompts) and provider manifest content (commission/API-key fields) are the consumer's and the manifest's concern, not the runner's. Remote execution is out of scope — only the default local-shell executor and a swappable local agent/session executor are supported.

Telemetry

The SDK collects anonymous, aggregate usage telemetry via PostHog to measure install counts, onboarding success rates, and MCR query volume. No PII is collected — GeoIP is disabled, IP addresses are nulled, and all UUIDs are randomly generated.

Telemetry is enabled by default and can be disabled via environment variables:

DO_NOT_TRACK=1 always takes precedence. When telemetry is disabled, no PostHog client is created and no events are sent.

Analytics events are captured automatically from existing SDK methods — no additional API calls are needed:

client = PeaqosClient(...)                         # peaqos_sdk_initialize (first install only)
addr, key = PeaqosClient.generate_keypair()        # peaqos_sdk_generate_keypair (via active instance)
mcr = client.query_mcr("did:peaq:42")             # peaqos_sdk_mcr_request
client.close()                                     # flush queued events

All analytics calls are fire-and-forget — they never block or raise. See docs/10_ANALYTICS.md for the full event reference and privacy details.

Documentation

Per-feature deep-dives live under docs/:

• Quick Start — client initialization, configuration, environment variables, types, exception classes, validation, utilities, and constants.
• Gas station — faucet 2FA enrollment and gas-station funding of a machine wallet, with the full faucet error reference.
• MCR queries — query_mcr, query_machine, query_operator_machines, response shapes, rating tiers, and the full HTTP error-code table.
• Provider-node provisioning — the generic, manifest-driven peaq_os_sdk.provisioning runner: fetch/validate a ProviderProvisioningManifest, resolve inputs, gate on pre-flight, execute phases/steps in manual/auto modes with scoped sudo and owner-action handoffs, redact secrets before emission, thread captures, verify success by probes, and resume interrupted runs. Covers the CommandExecutor protocol, machine-wallet context, idempotency, the error hierarchy, and the consumer/runner boundary.
• Monetisation opt-in — the signed on/off toggle and public state read: deployment-selected MCR configuration, full uint256 IDs and decimal DIDs, owner/controller authorization, live compatibility checks, bounded retries, one end-to-end deadline, strict response correlation, and typed failures.
• Machine activation — atomic PEAQ activation: deployment selection, preview_machine_activation / activate_machine, the bond/voucher arithmetic and why only the net amount is approved, receipt event correlation and post-state reconciliation, reconcile_activation_transaction for a submitted-but-unconfirmed hash, the typed error taxonomy, operator-run machines, and the record diff for adding a network.
• Machine management — post-onboarding reads and previews, lifecycle, bounded PEAQ/USDT subscriptions, ERC-721 ownership, DID updates, relocation evidence, authority rules, and known-hash reconciliation.
• Solana machine management — native writes through the existing entry points: the authority table, why the signer is an argument, results that report conflicts instead of raising, keeping local confirmation apart from peaq application, explicit clearing, DID rent direction, and reconciling after a crash.
• Solana onboarding and recovery — the terminal-first phases (registration, request, credit, finalise, bond, mint, link), keyless previews/status, signer selection, the journal and recovery.
• Solana reads — home resolution, native identity and subscription observations, which of the two subscription accounts a deployment reads and the two eligibility rules, cluster verification and packaged bindings.
• MCR API compatibility — the current contract set and Solana-homed machines: the three breaking type changes, the additive home_chain / rating_unavailable / owner / controller fields, the distinct 400 / 401 / 409 / 503 codes on ApiError, and the planned owner-signed Solana monetization path (implemented, gated off until a compatible server release is recorded).
• Event submission — single and batch event submission to the deployment's EventRegistry, revert codes, pipeline details, limits, hashing, metadata mode, and rate-limiting behavior.
• OWS wallet lifecycle — create, import, list, get, export, and delete encrypted wallets via the Open Wallet Standard. Multi-chain accounts, passphrase management, vault storage, OWS-native EVM signing via from_wallet(), and Solana signing via solana_signer_from_wallet().
• Orchestration service (experimental) — client.orchestration, policies, observability, market lifecycle, pagination, challenge-sign workflows, oneM2M subscription management and context-managed IoT event streams. The IoT interfaces follow the draft contract; live server validation remains pending.
• Stream data signing & encryption (experimental) — local field-level privacy rules, EIP-191 data package signing, and verification (Phase 2 Step 2; no network/distribution).
• Stream data chunking (experimental) — per-chunk XChaCha20-Poly1305 encryption, inline Ed25519 signatures, owner/operator/machine key wrapping, and separate buyer access docs; build_chunk_chain / verify_chunk_chain / decrypt_chunk / create_buyer_access_entry / build_buyer_access_files.
• Analytics & telemetry — anonymous usage telemetry, event inventory, opt-out, privacy guarantees, and onboarding flow integration.
• Stream distribution (experimental) — seller-side payment confirmation and delivery (distribute_data, PollingConfirmationProvider, S3DeliveryChannel) plus buyer-side token payment (transfer_token, submit_payment_proof, pay_and_submit_proof) on peaq, Base, and Solana.
• P2P delivery (experimental) — machine-to-machine delivery via the peaqos-p2p transport: P2PDeliveryChannel (seller) and P2PDeliveryReceiver (buyer) with verify-before-decrypt chunk reception, session routing, and replay protection.
• Stream delivery setup (in development) — pre-purchase payment rails discovery, delivery transports discovery, delivery capability registration, and stream listing purchase field updates.
• Stream purchases (in development) — full purchase lifecycle: creation with buyer identity, payment intent, payment proof, delivery retrieval, and purchase events.
• Verify reads and chip preflight (experimental) — peaq_os_sdk.verify provides READ_PREFLIGHT_ONLY + API_ONLY. VerifyReadClient.get_machine_verification_across_chains(machine_id) is the sole read method for EVM and Solana homes over one HTTPS route, with distinct home/controller/operator roles and independent KYB/chip states. Solana genesis hashes and role keys must be nonzero. The API is authoritative. SDK-owned and caller-owned sessions have explicit cleanup. EVM-only CA306 preflight produces non-authoritative evidence using an exact decimal machine ID/DID pair. The eight-stage application flow separates platform chip access, wallet signing, application-owned evidence handoff, backend processing, and the later read. The undeployed EVM-only reader is absent; there is no stable root-client integration, RPC, SDK hardware access, evidence upload, or persistence.

Development

git clone https://github.com/peaqnetwork/peaq-os-sdk-py.git
cd peaq-os-sdk-py
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Activate .env for Testing

set -a
source .env
set +a

Quality gates

ruff check src tests       # lint — zero warnings
black --check src tests    # formatting
mypy src                   # strict type check, zero errors
mypy src tests/unit/verify # also type-checks the Verify type fixtures
pytest tests/unit tests/conformance -q  # all green; never a bare `pytest` (see below)

The Verify guide covers API-only reads, independent lifecycle examples, controlled errors, cancellation, and beta compatibility. Its conformance sections describe the pinned backend and SDK-local read corpora, the real CA306 capture, and pending acceptance checks. Run the unit and offline corpus checks from a repository checkout:

pytest tests/unit/verify tests/conformance/verify -q
mypy --strict tests/unit/verify tests/conformance/verify

The Verify read/chip fixtures and public test-account recipe are excluded from release packages. The backend read bytes and revision are pinned. The corpus documentation records the SDK error-message expectation and the difference between injected headers and Fetch normalization.

The unit tests are hermetic — they mock Web3 and requests.Session with handwritten stubs and never touch the network.

The activation surface additionally carries a branch-coverage floor:

pytest -q -m "not integration" \
  --cov=src/peaq_os_sdk/onboarding --cov=src/peaq_os_sdk/machine \
  --cov=src/peaq_os_sdk/deployments --cov-branch --cov-fail-under=90

Coverage is measured from the hermetic suite alone, so the floor is meaningful without spending PEAQ.

Optional integration tests

The repo ships an opt-in suite that talks to real chains. Each suite is skipped unless its environment variables are supplied, and a local .env can supply them, so a bare pytest may send real transactions. Use pytest tests/unit tests/conformance for a hermetic pass.

Query & event suites (tests/integration/onchain/) — MCR-20 coverage for the three enabled queries (lossless int machine IDs, identifier correlation, per-entry DID/ID agreement) and for event submission. Requires PEAQOS_RPC_URL and PEAQOS_PRIVATE_KEY plus:

PEAQOS_TEST_MACHINE_ID=9007199254740992   # canonical decimal, registered on MachineRegistry
PEAQOS_TEST_OPERATOR_DID=did:peaq:0x...   # queries only
PEAQOS_EVENT_WRITES=1                     # events only — submits real transactions, spends gas

pytest -m integration tests/integration/onchain/

The query suite also asserts that queries resolve the deployment's paired MCR (MCR-20) and that the client offers no caller-configured endpoint. agung is explicitly skipped with a reason — it has no approved paired MCR to test against.

OWS wallet integration suite (tests/integration/wallet/test_wallet_integration.py) — six end-to-end tests for wallet lifecycle (create, list, get, delete), create-export-reimport round-trip, private key import, empty vault, and error paths. Gated behind PEAQOS_INTEGRATION=1 and requires the open-wallet-standard package:

pip install peaq-os-sdk[ows]
PEAQOS_INTEGRATION=1 pytest -m integration tests/integration/wallet/

See docs/06_WALLET.md for the full wallet API reference.

Orchestration live API suite (tests/integration/orchestration/test_orchestration_integration.py) — health, readiness, machine lifecycle, market lifecycle, policy CRUD, and audit-event listing against a real orchestration deployment. Gated behind PEAQOS_ORCHESTRATION_INTEGRATION=1:

PEAQOS_ORCHESTRATION_INTEGRATION=1
PEAQOS_ORCHESTRATION_URL=https://markets.peaq.xyz
PEAQOS_API_KEY=your-platform-api-key
pytest -m integration tests/integration/orchestration/test_orchestration_integration.py

Optional overrides: PEAQOS_ORCHESTRATION_PROVIDER_KEY, PEAQOS_ORCHESTRATION_ENDPOINT_URL, PEAQOS_ORCHESTRATION_MARKET_SERVICE_TYPE, PEAQOS_ORCHESTRATION_MARKET_OPERATION, PEAQOS_ORCHESTRATION_MARKET_ORDER_INPUT (JSON object), PEAQOS_ORCHESTRATION_MARKET_PAYMENT_RAIL. See docs/07_ORCHESTRATION.md → Integration tests.

A separate mocked market lifecycle test lives in tests/integration/orchestration/test_market_lifecycle_integration.py and runs without orchestration env vars.

Activation integration suite (tests/integration/onchain/test_activation_integration.py) — live Agung coverage for snapshot and InfoDesk.peer drift, pricing, deterministic IDs, genuine revert decoding, write-free previews, activation guards, atomic activations, management reads, reversible suspend/resume, submission reporting, and known-hash reconciliation.

This suite spends real PEAQ and cannot be undone. Activation mints a permanent machine identity and bonds tokens against it — there is no deactivate and no refund. A full run costs roughly 0.8 PEAQ of bond plus activation and management gas at the tier-0 price stamped on Agung. It is gated behind a dedicated variable on top of the integration marker.

PEAQOS_ACTIVATION_INTEGRATION=1 \
PEAQOS_RPC_URL=https://peaq-agung.api.onfinality.io/public \
PEAQOS_PRIVATE_KEY=0xYOUR_FUNDED_KEY \
pytest -m integration tests/integration/onchain/

Contract addresses are deliberately not environment variables — resolving them from the SDK's approved snapshot is the behaviour under test. See the activation and management guides for the API reference and live-suite limitations.

PEAQOS_PRIVATE_KEY must match ^0x[0-9a-fA-F]{64}$. Never commit a real key. Never run the suite against mainnet.

Build

python -m build

Produces dist/peaq_os_sdk-<version>-py3-none-any.whl and dist/peaq_os_sdk-<version>.tar.gz for downstream testing.

License

See LICENSE for details.