Skip to main content
The Python exposes the Machine Markets API on the existing PeaqosClient via client.orchestration. Flat methods, sync, snake_case, frozen-slotted dataclasses. Scale is paused. Machine Markets is not open to new partners yet. The orchestrator accepts active, bonded machines homed on peaq or on Solana; the machine’s DID controller signs the identity proof (an EVM address on peaq, a Solana public key on Solana), and an agent pairs with an EVM or a Solana wallet. Any other machine is refused with 403 MACHINE_NOT_ACTIVATED. Pairing also needs an active, bonded machine; see Scale.

Setup

Functional form, handy for testing:
Accessing client.orchestration without orchestration_url raises OrchestrationConfigError.

Configuration

Constructor kwargs

Env vars (via PeaqosClient.from_env())

Transport constants:
User-Agent: peaqos-sdk-py/<version>. Per-method timeout overrides are not exposed on public methods.

Envelopes

204 No Content returns None. validate_list_limit rejects limit < 1 or limit > 500 with OrchestrationValidationError.

Machines

Machine shape:

Machine agents

enroll_machine_agent returns ItemResponse[MachineAgent]. The server sends the one-time token as agentToken, and the Python SDK maps item.provisioning_token from a provisioning_token key that the server does not send, so it comes back None. To capture the token, call POST /machines/:machineId/agents/enrollment directly (see the orchestration API) and read item.agentToken. machine_agent_heartbeat uses no auth header: agent_token rides in the JSON body.

Machine identity challenges

create_machine_identity_challenge requests a server-issued challenge tied to a did:peaq:<decimal machine id> or peaqos:machine:<decimal machine id> identity reference; an address DID is refused. create_machine requires both identity_ref and identity_proof. The server builds item.message and picks the scheme from the controller it resolves through the MCR, never from a client flag: an EVM controller (a peaq-homed machine) gets verification_method "eip191", a base58 Solana controller (a Solana-homed machine) gets "ed25519", and controller_addresses names that key. sign_machine_identity_challenge(result.item, ...) signs the unwrapped challenge item with exactly one signer and returns the MachineIdentityProofInput the create call takes: eip191_signer= for an EVM controller (personal_sign over the text, 0x + 130 hex on the wire), ed25519_signer= for a Solana controller (pure Ed25519 over the UTF-8 bytes of message, the 64 signature bytes as base58 on the wire). The branch is chosen from verification_method alone, never from the key format or the signer type. prove_machine_identity requests the challenge and signs its item in one call, with exactly one HTTP request. The SDK signs message exactly as returned; it never builds, parses, re-joins or normalizes it.

Signers

Any object with sign_message(str) -> str is an Eip191Signer; any object with address: str and sign_message(bytes) -> bytes is a SolanaMessageSigner (both protocols live in peaq_os_sdk.monetization). The SDK ships four:

Local pre-checks

Every row below raises OrchestrationValidationError(message, field, constraint) before any signature is made and before any HTTP call. No message contains the challenge text, a signature or a key. Server codes. For an ed25519 challenge the server answers PROOF_METHOD_MISMATCH (400, signature scheme does not match the challenge), PROOF_SIGNATURE_INVALID (400), PROOF_SIGNER_MISMATCH (400, key is not the controller / agent sealed in the challenge) or PROOF_EXPIRED (401); EIP-191 challenges keep the 403 MACHINE_IDENTITY_PROOF_* / AGENT_PAIRING_PROOF_* codes. All of them surface unchanged as OrchestrationApiError with that code and status_code, after one request: the SDK does not map, retry or re-sign. The API reference has the message layouts and the codes: Signing a challenge.

Solana-homed machine

A Solana-homed machine’s controller is a Solana public key (the machine’s MCR controller, or its owner when no controller is set), so its identity challenge is ed25519 and controller_addresses holds base58 keys. The activation PATCH needs no proof when the machine was created with one: the server reuses the stored record and re-checks it against a fresh MCR resolution. identity_proof= on update_machine is for a machine created without one.

EVM controller, two steps

An EVM controller (a peaq-homed machine) signs the same way with eip191_signer=. The two-step form and the one-call form give the same proof:

Agent pairings

Pairing is challenge-based end to end:
  1. create_agent_pairing_challenge returns a server-issued challenge keyed to agent_address, agent_provider, agent_role, and optional agent_did. Its verification_method is "eip191" for an EVM agent_address and "ed25519" for a base58 Solana public key; the server picks it from the address.
  2. The item.message with the key behind agent_address: sign_agent_pairing_challenge(item, eip191_signer=...) or (..., ed25519_signer=...) (see Signers and Local pre-checks), or prove_agent_pairing(machine_id, params, ...) for steps 1 and 2 in one call.
  3. create_agent_pairing accepts the proof in params.agent_proof and returns the pairing with a signed HS256 session JWT in pairing_token. The token is returned once at create.
  4. create_agent_pairing_session rotates the session token before expiry with a fresh proof. Required after any update_agent_pairing to the , since policy changes invalidate the current token’s delegation_policy_hash.
Both create methods set pairing_token exactly once each. AgentPairing.__repr__ redacts the token to keep it out of logs. CreateAgentPairingRequest requires agent_proof: AgentProofInput and accepts an optional agent_did. delegation_policy carries service-level allow/deny lists (allowed_service_ids, denied_service_ids) next to the skill-level ones. agent_address itself is only checked for non-emptiness: an EVM address and a base58 Solana public key both pass unchanged, and the server answers 400 VALIDATION_ERROR for a form it rejects. Agent DID forms (agent_did on the challenge and pairing requests):
  • EVM agent: did:pkh:eip155:<chainId>:<address>. Omitted, the server derives did:pkh:eip155:1:<checksummed address>.
  • Solana agent: did:pkh:solana:<reference>:<base58 key>, where <reference> is the CAIP-2 chain id after solana: (5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp for mainnet, EtWTRABZaYq6iMfeYKouRu166VU2xqa1 for devnet). solana_agent_did(address, chain_id=SOLANA_MAINNET_CHAIN_ID) builds it and raises OrchestrationValidationError for a key that is not 32 bytes (field address) or a chain id outside SOLANA_CHAIN_IDS (field chain_id). Omitted, the server derives the mainnet form, so a devnet agent supplies its DID. Pass the same agent_did to the challenge request and the pairing request.

Solana agent

A Solana wallet pairs the same way. The server sees the base58 agent_address, issues an ed25519 challenge, and the Solana signer signs it. An OwsSolanaSigner carries its chain_id, so the DID follows from the signer; a signer from ed25519_signer_from_secret has none, so that variant names the cluster explicitly (SOLANA_MAINNET_CHAIN_ID is the default, SOLANA_DEVNET_CHAIN_ID for devnet). Omitting agent_did makes the server derive the mainnet DID.

Session refresh

To refresh an expired pairing token, request a new challenge with the pairing’s stored agent_address, agent_provider, agent_role and, when the pairing was created with a supplied agent_did, that same agent_did; sign it; then create a session. The server verifies the refresh proof against the stored pairing.
A pairing record’s verification has exactly method, signer_address, verified_at and challenge_expires_at; a machine record’s identity_proof.challenge_id is the challenge nonce (mid_<32 hex>), not the mic_… id the proof was submitted with.

Runtime endpoints

upsert_runtime_endpoint validates that endpoint_base_url parses as http/https with a non-empty host. auth_token is treated as a secret in error redaction.

Skills

Market services

search_market uses x-agent-pairing-token auth: the token rides as the second argument and is sent per call. get_market_search uses platform auth.

Market orders

list_market_orders and get_market_order use platform auth; the four mutating calls require the agent’s pairing_token. execute_market_order returns execution.run and execution.outcome for a native run (execution.status_code == 200). When the order resolves to an external handoff the server answers 202, the order moves to handoff, and the call returns a HandoffExecutionResponse: execution.status_code == 202 and execution.handoff carries label, url and notes. For x402-rail services, sign_x402_payment signs the provider challenge from create_payment_intent locally, submit_x402_payment_proof records the signature, and the same signature goes on ExecuteMarketOrderRequest.payment (X402ExecutePayment).

Payment settlement

submit_payment_proof accepts both EVM and Solana proof shapes; verification_mode is "recorded" | "rpc". RPC verification cross-checks the ERC-20 Transfer log against expected token, payer_address, payee_address, and amount.

Pagination

Six sync auto-paginated iterators:
Each *_all accepts the same filter kwargs as its non-iterator counterpart, minus cursor. limit controls page size; cursor is managed internally. For manual pagination, the underlying list_* methods accept cursor and limit as keyword-only args:
MarketSearch:

Policies

Cross-cutting policy records above and beyond a pairing’s delegation policy. Platform auth.
There is no get_policy method. Fetch policies with list_policies.

Observability

check_health requests /api/v1/health, which returns 404 on the hosted orchestrator: the health route is GET /health at the host root, so call it over HTTP. list_audit_events sends machine_id, but the server ignores it and filters only on type, resourceType and resourceId; filter the returned events by machine yourself.

HTTP-only endpoints

These endpoints exist on the HTTP API (see Machine Markets API: Orchestration) and have no SDK method. Call them over HTTP:
  • Tasks: create, list, get, discover, resolve, execute
  • Graph: read a machine graph, create/update/delete nodes and edges
  • Policies: get a single policy
  • Runs: list runs, get a run

Errors

All extend peaq_os_sdk.exceptions.base.PeaqosError:
CommonErrorCode literal: AUTH_REQUIRED, AUTH_INVALID, AGENT_AUTH_REQUIRED, AGENT_AUTH_INVALID, AGENT_AUTH_EXPIRED, VALIDATION_ERROR, NOT_FOUND, MACHINE_NOT_ACTIVE, MACHINE_NOT_ACTIVATED, MACHINE_IDENTITY_EXISTS, MACHINE_IDENTITY_IMMUTABLE, MACHINE_IDENTITY_PROOF_REQUIRED, MACHINE_IDENTITY_PROOF_INVALID, MACHINE_IDENTITY_PROOF_EXPIRED, PEAQOS_IDENTITY_UNAVAILABLE, AGENT_PAIRING_PROOF_REQUIRED, AGENT_PAIRING_PROOF_INVALID, AGENT_PAIRING_PROOF_EXPIRED, PROOF_METHOD_MISMATCH, PROOF_SIGNATURE_INVALID, PROOF_SIGNER_MISMATCH, PROOF_EXPIRED (the four PROOF_* literals are the ed25519 outcomes: 400, 400, 400 and 401), AGENT_PAIRING_UNAVAILABLE, AGENT_PAIRING_REQUIRED, AGENT_PAIRING_INACTIVE, AGENT_POLICY_DENIED, AGENT_SPEND_LIMIT_EXCEEDED, AGENT_DAILY_LIMIT_EXCEEDED, QUOTE_EXPIRED, ORDER_CLOSED, ORDER_NOT_DELIVERED, EXECUTION_UNSUPPORTED, PAYMENT_REQUIRED, PAYMENT_RPC_REQUIRED, PAYMENT_RPC_ERROR, PAYMENT_NOT_MINED, PAYMENT_TX_FAILED, PAYMENT_TRANSFER_NOT_FOUND. Proof and credential types:
MarketPaymentRailType literal: "not-required", "wallet", "xvv42", "x402", "vault-stripe", "escrow", "offchain-record", "external", "onchain-escrow", "wdk-usdt-transfer". The transport synthesises BAD_RESPONSE (non-JSON body) and INVALID_RESPONSE_SHAPE (envelope mismatch) when the server response is malformed.

Sync vs async

Sync only. Every public function is plain def over requests.Session. The transport reuses client.session, so you can wrap retries externally.

Credential handling

  • Platform (x-api-key): set once on the client via api_key, sent on every call by default.
  • Agent pairing (x-agent-pairing-token): passed per call as the last argument to search_market, the order mutations, and the payment mutations. The SDK does not store or rotate it.
  • None: used only by machine_agent_heartbeat (token rides in the body).
_sanitize_body redacts any field whose name contains token, key, secret, password, credential, or auth (case-insensitive) before attaching the body to an error.