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
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 withsign_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 raisesOrchestrationValidationError(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 MCRcontroller, 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 witheip191_signer=. The two-step form and the one-call form give the same proof:
Agent pairings
create_agent_pairing_challengereturns a server-issued challenge keyed toagent_address,agent_provider,agent_role, and optionalagent_did. Itsverification_methodis"eip191"for an EVMagent_addressand"ed25519"for a base58 Solana public key; the server picks it from the address.- The
item.messagewith the key behindagent_address:sign_agent_pairing_challenge(item, eip191_signer=...)or(..., ed25519_signer=...)(see Signers and Local pre-checks), orprove_agent_pairing(machine_id, params, ...)for steps 1 and 2 in one call. create_agent_pairingaccepts the proof inparams.agent_proofand returns the pairing with a signed HS256 session JWT inpairing_token. The token is returned once at create.create_agent_pairing_sessionrotates the session token before expiry with a fresh proof. Required after anyupdate_agent_pairingto the , since policy changes invalidate the current token’sdelegation_policy_hash.
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 derivesdid:pkh:eip155:1:<checksummed address>. - Solana agent:
did:pkh:solana:<reference>:<base58 key>, where<reference>is the CAIP-2 chain id aftersolana:(5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpfor mainnet,EtWTRABZaYq6iMfeYKouRu166VU2xqa1for devnet).solana_agent_did(address, chain_id=SOLANA_MAINNET_CHAIN_ID)builds it and raisesOrchestrationValidationErrorfor a key that is not 32 bytes (fieldaddress) or a chain id outsideSOLANA_CHAIN_IDS(fieldchain_id). Omitted, the server derives the mainnet form, so a devnet agent supplies its DID. Pass the sameagent_didto the challenge request and the pairing request.
Solana agent
A Solana wallet pairs the same way. The server sees the base58agent_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 storedagent_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.
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
Market search
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:*_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.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 extendpeaq_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 plaindef 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 viaapi_key, sent on every call by default. - Agent pairing (
x-agent-pairing-token): passed per call as the last argument tosearch_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.

