Skip to main content
The JS/TS exposes the Machine Markets API as a typed namespace on the existing 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

Touching client.orchestration without orchestrationUrl configured throws OrchestrationConfigError. The namespace lazy-initialises and caches per client.

Configuration

Constructor form when not using env:
Transport constants:
  • 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-Agent header.
No retry, no exponential backoff. See Pagination for the auto-paginated iterators.

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 throws OrchestrationValidationError 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 an ed25519 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 an eip191 signer. For a caller that holds the challenge, the two steps are separate:
A machine record’s 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

Pairing is challenge-based end to end:
  1. createAgentPairingChallenge returns a server-issued challenge keyed to agentAddress, agentProvider, agentRole, and optional agentDid. Its verificationMethod is "eip191" for an EVM agentAddress and "ed25519" for a base58 Solana public key; the server picks it from the address.
  2. The item.message with the key behind agentAddress: signAgentPairingChallenge(item, signer) with an eip191 or an ed25519 signer (see Signers and Local pre-checks), or proveAgentPairing(machineId, { ...request, signer }) for steps 1 and 2 in one call.
  3. createAgentPairing accepts the proof in params.agentProof and returns the pairing with a signed HS256 session JWT in pairingToken. The token is returned once at create.
  4. createAgentPairingSession rotates the session token before expiry with a fresh proof. Required after any updateAgentPairing to the , since policy changes invalidate the current token’s delegationPolicyHash.
The agent’s DID takes one of two forms: 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

An OwsSolanaSigner 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 stored agentAddress, 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:
A pairing record’s 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

Upsert uses HTTP PUT. endpointBaseUrl is parsed with new URL(...) client-side; invalid URLs throw OrchestrationValidationError(field: "endpointBaseUrl", constraint: "valid URL").

Skills

Market services

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:
Each *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.
There is no 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
The SDK also exports CancelMarketOrderRequest and RetryMarketOrderRequest types, but the API has no cancel or retry route for market orders.

Errors

Five exported classes, all extend PeaqosError:
Switch on 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 via apiKey, 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.