PeaqosClient. Same client, additive surface. Each documented method maps to one HTTP route; the few routes without a method are listed under HTTP-only operations.
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 orchestrationUrl configured throws OrchestrationConfigError. The namespace lazy-initialises and caches per client.
Configuration
Constructor form when not using env:
API_BASE_PATH = "/api/v1", prepended to every path.- Timeouts: 30 s GET, 60 s POST/PATCH/PUT/DELETE.
- A
peaq-os-sdk-js/…User-Agentheader.
Common envelopes
204 No Content resolves to void. validateListQuery rejects limit < 1 or limit > 500 with OrchestrationValidationError before the HTTP call.
Machines
Machine shape:
Machine identity challenges
createMachineIdentityChallenge 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. 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 verificationMethod: "eip191", a base58 Solana controller (a Solana-homed machine) gets "ed25519", and controllerAddresses names that key. The DID controller signs item.message exactly as returned and submits { challengeId, signature } as identityProof when creating the machine record.
signMachineIdentityChallenge(response.item, signer) does the signing: for eip191 it is EIP-191 personal_sign of message (0x + 130 hex on the wire), for ed25519 the raw UTF-8 bytes of message under pure Ed25519 (base58 of the 64 signature bytes on the wire). proveMachineIdentity requests the challenge and signs it in one call, with exactly one request. The SDK never rebuilds, parses or normalizes message.
Signers
A signer is tagged with the scheme it signs in (OrchestrationProofSigner); the tag is compared with the challenge’s verificationMethod before anything is signed.
The OWS EVM account behind
PeaqosClient.fromWallet cannot sign messages, so it is not a proof signer. An OwsSolanaSigner carries chainId; a secret-key signer does not, so pass the chain id to solanaAgentDid yourself for that one. The secret-key signer holds the key in a closure and redacts itself in JSON.stringify, util.inspect and console.log; it needs no optional peer (@solana/web3.js is not imported), where the two OWS sources need the wallet peers.
Local pre-checks
Each row throwsOrchestrationValidationError with that field and constraint before anything is signed and before any HTTP call; no message contains the challenge text, a signature or a key.
Server codes. For an
ed25519 challenge the orchestrator answers PROOF_METHOD_MISMATCH (400, the signature scheme does not match the challenge), PROOF_SIGNATURE_INVALID (400), PROOF_SIGNER_MISMATCH (400, the key is not the controller or agent sealed in the challenge) or PROOF_EXPIRED (401); eip191 challenges keep the MACHINE_IDENTITY_PROOF_* and AGENT_PAIRING_PROOF_* codes. All of them surface unchanged as OrchestrationApiError with that .code and .statusCode, 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
The controller of a Solana-homed machine is a Solana public key, so the server issues aned25519 challenge naming it in controllerAddresses. Sign it with a Solana signer; the activation PATCH needs no proof, because the server reuses the stored one and re-checks it against a fresh MCR resolution.
EVM controller, two steps
An EVM controller (a peaq-homed machine) signs the same way with aneip191 signer. For a caller that holds the challenge, the two steps are separate:
identityProof.challengeId is the challenge nonce (mid_<32 hex>), not the mic_… id you submitted. The record is also exported by name as MachineIdentityProofRecord.
Agent pairings
createAgentPairingChallengereturns a server-issued challenge keyed toagentAddress,agentProvider,agentRole, and optionalagentDid. ItsverificationMethodis"eip191"for an EVMagentAddressand"ed25519"for a base58 Solana public key; the server picks it from the address.- The
item.messagewith the key behindagentAddress:signAgentPairingChallenge(item, signer)with aneip191or aned25519signer (see Signers and Local pre-checks), orproveAgentPairing(machineId, { ...request, signer })for steps 1 and 2 in one call. createAgentPairingaccepts the proof inparams.agentProofand returns the pairing with a signed HS256 session JWT inpairingToken. The token is returned once at create.createAgentPairingSessionrotates the session token before expiry with a fresh proof. Required after anyupdateAgentPairingto the , since policy changes invalidate the current token’sdelegationPolicyHash.
did:pkh:eip155:<chainId>:<address> for an EVM agent and did:pkh:solana:<reference>:<base58 key> for a Solana agent (mainnet reference 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, devnet EtWTRABZaYq6iMfeYKouRu166VU2xqa1). When agentDid is omitted the server derives it: eip155:1 for an EVM agent, the mainnet Solana reference for a Solana agent. A devnet Solana agent supplies its DID. solanaAgentDid builds the Solana form and throws OrchestrationValidationError for a key that is not 32 bytes or a chain id outside SOLANA_CHAIN_IDS.
Solana agent
AnOwsSolanaSigner from solanaSignerFromWallet is an ed25519 proof signer with no adapter. Its address must be the agentAddress of the challenge, and its chainId gives the DID’s reference.
Session refresh
To refresh an expired pairing token, request a fresh challenge with the pairing’s storedagentAddress, agentProvider, agentRole and, when the pairing was created with a supplied agentDid, that same agentDid; the server verifies the refresh proof against the stored pairing, not the request. Then create a session:
verification has exactly method, signerAddress, verifiedAt and challengeExpiresAt; it is also exported by name as AgentPairingVerificationRecord.
createAgentPairing and createAgentPairingSession return the pairingToken exactly once each. toJSON redacts the token to "[REDACTED]" so it does not leak through JSON.stringify.
CreateAgentPairingRequest requires agentProof: { challengeId, signature } and accepts optional agentDid. delegationPolicy carries allowedServiceIds and deniedServiceIds next to the skill-level allow and deny lists.
Machine agents
enrollMachineAgent POSTs /machines/:machineId/agents/enrollment and returns the agent record with a one-time token. The declared type names it provisioningToken, but the server sends it as agentToken and the SDK passes the response through unchanged, so item.provisioningToken is undefined at runtime. Read it as (item as unknown as { agentToken: string }).agentToken until the SDK type is fixed. machineAgentHeartbeat sends no auth header: the agentToken rides in the request body.
Runtime endpoints
PUT. endpointBaseUrl is parsed with new URL(...) client-side; invalid URLs throw OrchestrationValidationError(field: "endpointBaseUrl", constraint: "valid URL").
Skills
Market services
Market search
searchMarket uses x-agent-pairing-token auth: the token rides in the second argument and is sent per call. getMarketSearch uses platform auth.
Market orders
listMarketOrders and getMarketOrder use platform auth; the four mutating calls require the agent’s pairingToken.
executeMarketOrder returns execution.run and execution.outcome for a native run (execution.statusCode === 200). When the order resolves to an external handoff the server answers 202, the order moves to handoff, and the call returns execution.statusCode === 202 with execution.handoff (label, url, notes). Branch on the presence of execution.handoff: the {} overload’s return type also admits the oneM2M execution shape, whose statusCode is number, so a === 202 comparison does not narrow:
ExecuteMarketOrderRequest carries only input, so it has no field for the payment headers x402-rail services take (x-payment, payment-signature, authorization, sign-in-with-x). Execute x402-rail orders with a direct POST /market/orders/:orderId/execute request carrying operatorCredentials.providers[providerKey] in the body, as described in the orders API reference.
Payment settlement
submitPaymentProof accepts EVM (transactionHash) and Solana (transactionSignature) shapes with verificationMode: "recorded" | "rpc". RPC verification cross-checks the ERC-20 Transfer log against expected token, payerAddress, payeeAddress, and amount.
Pagination
Six auto-paginated iterators:*All accepts Omit<XxxOptions, "cursor">. The cursor is managed internally; filters and limit pass through on every page.
For manual pagination, the underlying list* methods accept cursor and limit:
Policies
Cross-cutting policy records above and beyond a pairing’s delegation policy. Platform auth.getPolicy method. Read a single policy out of listPolicies.
Observability
checkHealth 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. listAuditEvents sends machineId, but the server ignores it and filters only on type, resourceType and resourceId; filter the returned events by machine yourself.
HTTP-only operations
These operations exist on the HTTP API (see Machine Markets API: Orchestration) and have no SDK method. Call them over HTTP.- Tasks:
createTask,discoverTask,resolveTask,executeTask,getTask,listTasks - Graph:
getMachineGraph,createGraphNode,updateGraphNode,deleteGraphNode,createGraphEdge,updateGraphEdge,deleteGraphEdge - Policies:
getPolicy - Runs:
listRuns,getRun
CancelMarketOrderRequest and RetryMarketOrderRequest types, but the API has no cancel or retry route for market orders.
Errors
Five exported classes, all extendPeaqosError:
instanceof OrchestrationApiError then on err.code. Never parse err.message.
Server code values exported as constants from @peaqos/peaq-os-sdk: ERROR_CODE_AUTH_REQUIRED, ERROR_CODE_AUTH_INVALID, ERROR_CODE_AGENT_AUTH_REQUIRED, ERROR_CODE_AGENT_AUTH_INVALID, ERROR_CODE_AGENT_AUTH_EXPIRED, ERROR_CODE_VALIDATION_ERROR, ERROR_CODE_NOT_FOUND, ERROR_CODE_MACHINE_NOT_ACTIVE, ERROR_CODE_MACHINE_NOT_ACTIVATED, ERROR_CODE_MACHINE_IDENTITY_EXISTS, ERROR_CODE_MACHINE_IDENTITY_IMMUTABLE, ERROR_CODE_MACHINE_IDENTITY_PROOF_REQUIRED, ERROR_CODE_MACHINE_IDENTITY_PROOF_INVALID, ERROR_CODE_MACHINE_IDENTITY_PROOF_EXPIRED, ERROR_CODE_PEAQOS_IDENTITY_UNAVAILABLE, ERROR_CODE_AGENT_PAIRING_PROOF_REQUIRED, ERROR_CODE_AGENT_PAIRING_PROOF_INVALID, ERROR_CODE_AGENT_PAIRING_PROOF_EXPIRED, ERROR_CODE_PROOF_METHOD_MISMATCH, ERROR_CODE_PROOF_SIGNATURE_INVALID, ERROR_CODE_PROOF_SIGNER_MISMATCH, ERROR_CODE_PROOF_EXPIRED, ERROR_CODE_AGENT_PAIRING_UNAVAILABLE, ERROR_CODE_AGENT_PAIRING_REQUIRED, ERROR_CODE_AGENT_PAIRING_INACTIVE, ERROR_CODE_AGENT_POLICY_DENIED, ERROR_CODE_AGENT_SPEND_LIMIT_EXCEEDED, ERROR_CODE_AGENT_DAILY_LIMIT_EXCEEDED, ERROR_CODE_QUOTE_EXPIRED, ERROR_CODE_ORDER_CLOSED, ERROR_CODE_ORDER_NOT_DELIVERED, ERROR_CODE_PAYMENT_REQUIRED, ERROR_CODE_PAYMENT_RPC_REQUIRED, ERROR_CODE_PAYMENT_RPC_ERROR, ERROR_CODE_PAYMENT_TX_FAILED, ERROR_CODE_PAYMENT_NOT_MINED, ERROR_CODE_PAYMENT_TRANSFER_NOT_FOUND, ERROR_CODE_EXECUTION_UNSUPPORTED, ERROR_CODE_ENDPOINT_UNREACHABLE.
Proof and credential types:
MarketPaymentRailType is "not-required" | "wallet" | "xvv42" | "x402" | "vault-stripe" | "escrow" | "offchain-record" | "external" | "onchain-escrow" | "wdk-usdt-transfer".
The transport synthesises BAD_RESPONSE (non-JSON error body) and INVALID_RESPONSE_SHAPE (envelope mismatch) inside OrchestrationApiError when the server response is malformed.
Credential handling
Three auth modes per call:- Platform (
x-api-key): set once on the client viaapiKey, sent on every call by default. - Agent pairing (
x-agent-pairing-token): passed per call as an explicit argument to market search, the order mutations, and the payment settlement calls. The SDK does not store or rotate it. - None: used only by
machineAgentHeartbeat(token rides in the body).
sanitizeBody() redacts any body field whose name contains token, key, secret, password, credential, or auth (case-insensitive) before attaching the body to an error. Redaction is recursive into nested objects.

