Orchestration (JavaScript)

The JS/TS exposes the Machine Markets API as a typed namespace on the existing PeaqosClient. Same client, additive surface. Each method maps to one HTTP route; the few routes without a method are listed under HTTP-only operations.

client.orchestration works only on a client constructed without tokenomics20. On a Tokenomics 2.0 client (tokenomics20 passed to the constructor, or TOKENOMICS_DEPLOYMENT_ID set in the environment that fromEnv() reads, which peaqos init writes), the machine, machine identity, agent pairing, machine agent, runtime endpoint, market search, market order, payment settlement, and purchase calls throw TokenomicsIntegrationUnavailableError before any request is sent. Skills, market services, policies, health, readiness, and audit-event calls still work. Pairing also needs an active, bonded Tokenomics 1.0 machine; see Scale.

Setup

Leave TOKENOMICS_DEPLOYMENT_ID unset in the .env this client reads:

import 'dotenv/config';
import { PeaqosClient } from "@peaqos/peaq-os-sdk";

const client = PeaqosClient.fromEnv();
const { items } = await client.orchestration.listMachines({ limit: 20 });

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

Configuration

Field	Env var (via `fromEnv()`)	Notes
`orchestrationUrl`	`PEAQOS_ORCHESTRATION_URL`	Required to use the namespace. Must parse as `http:` or `https:`. With `verbose: true`, a non-loopback `http://` URL logs a warning.
`apiKey`	`PEAQOS_API_KEY`	Sent as `x-api-key` on platform-auth calls. Required only when the orchestrator enforces platform auth.

Constructor form when not using env:

new PeaqosClient({
  rpcUrl,
  privateKey,
  contracts,
  orchestrationUrl: "https://orchestration.peaq.xyz",
  apiKey: "...",
});

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

type ListResponse<T> = {
  readonly items: readonly T[];
  readonly nextCursor?: string;          // omitted when there is no next page
};

type ItemResponse<T> = {
  readonly item: Readonly<T>;
};

type ListQuery = {
  readonly limit?: number;               // 1..500, default 100
  readonly cursor?: string;              // opaque, omit on first page
};

204 No Content resolves to void. validateListQuery rejects limit < 1 or limit > 500 with OrchestrationValidationError before the HTTP call.

Machines

client.orchestration.listMachines(options?: {
  cursor?: string;
  limit?: number;
}): Promise<ListResponse<Machine>>

client.orchestration.createMachine(params: CreateMachineRequest)
  : Promise<ItemResponse<Machine>>

client.orchestration.getMachine(machineId: string)
  : Promise<ItemResponse<Machine>>

client.orchestration.updateMachine(machineId: string, params: UpdateMachineRequest)
  : Promise<ItemResponse<Machine>>

Machine shape:

type Machine = {
  readonly id: string;
  readonly displayName: string;
  readonly status: "draft" | "active" | "degraded" | "blocked" | "archived";
  readonly ownerId: string;
  readonly identityRef?: string | null;
  readonly identityProof?: {
    readonly method: "eip191";
    readonly identityRef: string;
    readonly signerAddress: string;
    readonly challengeId: string;
    readonly verifiedAt: string;
    readonly challengeExpiresAt: string;
    readonly controllerAddresses: readonly string[];
    readonly resolutionSource: "peaqos-mcr";
  } | null;
  readonly machineType: string;
  readonly runtimeProfile: string;
  readonly capabilities: readonly string[];
  readonly labels: Readonly<Record<string, string>>;
  readonly policyIds: readonly string[];
  readonly skillKeys: readonly string[];
  readonly createdAt: string;
  readonly updatedAt: string;
};

Machine identity challenges

client.orchestration.createMachineIdentityChallenge(
  params: CreateMachineIdentityChallengeRequest,
): Promise<ItemResponse<MachineIdentityChallengeResponse>>

Requests a server-issued challenge tied to a did:peaq:0x... or peaqos:machine:<id> identity reference. The DID controller signs item.message with EIP-191 personal_sign and submits the resulting { challengeId, signature } as identityProof when creating or updating the machine record.

Agent pairings

client.orchestration.listAgentPairings(machineId: string, options?: ListAgentPairingsOptions)
  : Promise<ListResponse<AgentPairing>>

client.orchestration.createAgentPairingChallenge(
  machineId: string,
  params: CreateAgentPairingChallengeRequest,
): Promise<ItemResponse<AgentPairingChallengeResponse>>

client.orchestration.createAgentPairing(
  machineId: string,
  params: CreateAgentPairingRequest,
): Promise<ItemResponse<AgentPairing & { pairingToken: string }>>

client.orchestration.createAgentPairingSession(
  machineId: string,
  pairingId: string,
  params: CreateAgentPairingSessionRequest,
): Promise<ItemResponse<AgentPairing & { pairingToken: string }>>

client.orchestration.updateAgentPairing(
  machineId: string,
  pairingId: string,
  params: UpdateAgentPairingRequest,
): Promise<ItemResponse<AgentPairing>>

client.orchestration.revokeAgentPairing(machineId: string, pairingId: string)
  : Promise<void>

Pairing is challenge-based end to end:

createAgentPairingChallenge returns a server-issued challenge keyed to agentAddress, agentProvider, agentRole, and optional agentDid.
The item.message (EIP-191) with the key behind agentAddress.
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.
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.

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

client.orchestration.enrollMachineAgent(
  machineId: string,
  params?: EnrollMachineAgentRequest,
): Promise<ItemResponse<MachineAgent & { provisioningToken: string }>>

client.orchestration.machineAgentHeartbeat(
  params: MachineAgentHeartbeatRequest,
): Promise<MachineAgentHeartbeatResponse>

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

client.orchestration.listRuntimeEndpoints(machineId: string, options?: ListRuntimeEndpointsOptions)
  : Promise<ListResponse<RuntimeEndpoint>>

client.orchestration.getRuntimeEndpoint(machineId: string, providerKey: string)
  : Promise<ItemResponse<RuntimeEndpoint>>

client.orchestration.upsertRuntimeEndpoint(
  machineId: string,
  providerKey: string,
  params: UpsertRuntimeEndpointRequest,
): Promise<ItemResponse<RuntimeEndpoint>>

client.orchestration.deleteRuntimeEndpoint(machineId: string, providerKey: string)
  : Promise<void>

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

Skills

client.orchestration.listSkills(options?: {
  scope?: SkillScope;
  direction?: SkillDirection;
  source?: SkillSource;
}): Promise<ListResponse<SkillSummary>>

client.orchestration.getSkill(skillKey: string)
  : Promise<ItemResponse<SkillSummary>>

client.orchestration.getSkillManifest(skillKey: string)
  : Promise<ItemResponse<SkillManifest>>

Market services

client.orchestration.listMarketServices(options?: {
  machineId?: string;
  serviceType?: ServiceType;
  executionMode?: ExecutionMode;
  providerKey?: string;
}): Promise<ListResponse<MarketService>>

client.orchestration.getMarketService(
  serviceId: string,
  options?: { machineId?: string },
): Promise<ItemResponse<MarketService>>

Market search

client.orchestration.searchMarket(
  params: MarketSearchRequest,
  pairingToken: string,
): Promise<ItemResponse<MarketSearch>>

client.orchestration.getMarketSearch(searchId: string)
  : Promise<ItemResponse<MarketSearch>>

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

client.orchestration.listMarketOrders(
  options: ListMarketOrdersOptions,        // { machineId, cursor?, limit? }
): Promise<ListResponse<MarketOrder>>

client.orchestration.createMarketOrder(
  params: CreateMarketOrderRequest,        // { machineId, agentPairingId, serviceId, searchId?, quoteId?, operation?, input?, budget?, providerCredentials? }
  pairingToken: string,
): Promise<ItemResponse<MarketOrder>>

client.orchestration.getMarketOrder(
  orderId: string,
): Promise<ItemResponse<MarketOrder>>

client.orchestration.executeMarketOrder(
  orderId: string,
  params: ExecuteMarketOrderRequest,       // { input? }
  pairingToken: string,
): Promise<ExecuteMarketOrderResponse>     // discriminated union

client.orchestration.confirmMarketOrder(
  orderId: string,
  pairingToken: string,
): Promise<ConfirmMarketOrderResponse>     // { order, payment: MarketPayment | null }

client.orchestration.disputeMarketOrder(
  orderId: string,
  params: DisputeMarketOrderRequest,       // { reason, evidence? }
  pairingToken: string,
): Promise<DisputeMarketOrderResponse>     // { order, payment, dispute }; payment → "frozen"

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 throws OrchestrationApiError with code INVALID_RESPONSE_SHAPE. Catch it and read the handoff from the order:

import 'dotenv/config';
import { OrchestrationApiError, PeaqosClient } from "@peaqos/peaq-os-sdk";

const client = PeaqosClient.fromEnv();
const orderId = process.env.MARKET_ORDER_ID!;           // item.id from createMarketOrder
const pairingToken = process.env.AGENT_PAIRING_TOKEN!;  // pairingToken from createAgentPairing

try {
  const result = await client.orchestration.executeMarketOrder(orderId, {}, pairingToken);
  if (result.execution.statusCode === 200) {
    // Native execution
    const { run, outcome } = result.execution;
  }
} catch (err) {
  if (!(err instanceof OrchestrationApiError) || err.code !== "INVALID_RESPONSE_SHAPE") throw err;
  const { item: order } = await client.orchestration.getMarketOrder(orderId);
  if (order.status !== "handoff") throw err;
  const { handoff } = order;   // { label, url, notes }
}

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

client.orchestration.createPaymentIntent(
  orderId: string,
  params: CreatePaymentIntentRequest,      // { rail?, amount?, currency? }
  pairingToken: string,
): Promise<ItemResponse<MarketPayment>>

client.orchestration.getMarketPayment(
  orderId: string,
): Promise<ItemResponse<MarketPayment | null>>  // platform auth; the server answers 404 NOT_FOUND when the order has no payment, so expect OrchestrationApiError rather than a null item

client.orchestration.submitPaymentProof(
  orderId: string,
  params: SubmitPaymentProofRequest,       // EVM: transactionHash | Solana: transactionSignature + verificationMode + chain, token, payerAddress, payeeAddress, amount
  pairingToken: string,
): Promise<ItemResponse<MarketPayment>>

client.orchestration.lockEscrowPayment(
  orderId: string,
  params: LockEscrowPaymentRequest,        // { transactionHash, chain, escrowAddress } all required
  pairingToken: string,
): Promise<ItemResponse<MarketPayment>>

client.orchestration.releasePayment(
  orderId: string,
  params: ReleasePaymentRequest | undefined,  // { transactionHash?, notes? }
  pairingToken: string,
): Promise<ItemResponse<MarketPayment>>

client.orchestration.refundPayment(
  orderId: string,
  params: RefundPaymentRequest | undefined,   // { transactionHash?, reason? }
  pairingToken: string,
): Promise<ItemResponse<MarketPayment>>

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:

for await (const m of client.orchestration.listMachinesAll()) { /* … */ }
for await (const s of client.orchestration.listSkillsAll()) { /* … */ }
for await (const svc of client.orchestration.listMarketServicesAll()) { /* … */ }
for await (const o of client.orchestration.listMarketOrdersAll({ machineId: "m-1" })) { /* … */ }
for await (const p of client.orchestration.listAgentPairingsAll("m-1")) { /* … */ }
for await (const e of client.orchestration.listRuntimeEndpointsAll("m-1")) { /* … */ }

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:

let cursor: string | undefined;
do {
  const page = await client.orchestration.listMarketOrders({ machineId: "m-1", limit: 50, cursor });
  for (const order of page.items) handle(order);
  cursor = page.nextCursor;             // undefined when terminal
} while (cursor);

Policies

Cross-cutting policy records above and beyond a pairing’s delegation policy. Platform auth.

client.orchestration.listPolicies()
  : Promise<ListResponse<Policy>>

client.orchestration.createPolicy(params: CreatePolicyRequest)
  : Promise<ItemResponse<Policy>>

client.orchestration.updatePolicy(policyId: string, params: Partial<CreatePolicyRequest>)
  : Promise<ItemResponse<Policy>>

There is no getPolicy method. Read a single policy out of listPolicies.

Observability

client.orchestration.checkHealth(): Promise<HealthResponse>        // GET /api/v1/health

client.orchestration.getReadiness(): Promise<ReadinessResponse>    // GET /api/v1/readiness

client.orchestration.listAuditEvents(options?: {
  machineId?: string;
  resourceType?: string;
  limit?: number;
}): Promise<ListResponse<AuditEvent>>

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:

class OrchestrationError extends PeaqosError {}

class OrchestrationApiError extends OrchestrationError {
  readonly code: string;        // server-provided, e.g. "NOT_FOUND"
  readonly statusCode: number;  // HTTP 4xx/5xx
  readonly details: unknown;    // server-provided detail blob
}

class OrchestrationNetworkError extends OrchestrationError {
  // .cause carries the original transport error
}

class OrchestrationConfigError extends OrchestrationError {}

class OrchestrationValidationError extends OrchestrationError {
  readonly field: string;
  readonly constraint: string;
}

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_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:

type MachineIdentityProofInput = { challengeId: string; signature: string };

type AgentPairingChallengeResponse = {
  challengeId: string;
  agentAddress: string;
  message: string;
  expiresAt: string;
  verificationMethod: "eip191";
};

// Per-adapter credentials, accepted on market search and order creation.
type ProviderCredentials = {
  walrus?: { publisherUrl?: string; aggregatorUrl?: string; publisherToken?: string };
  akash?: { consoleApiKey?: string; consoleBaseUrl?: string; restEndpoints?: string };
  worldId?: { rpId?: string; appId?: string; verifyBaseUrl?: string };
  geodnet?: { appId?: string; appKey?: string; baseUrl?: string };
  aethir?: { ak?: string; sk?: string; baseUrl?: string };
};

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.

​Setup

​Configuration

​Common envelopes

​Machines

​Machine identity challenges

​Agent pairings

​Machine agents

​Runtime endpoints

​Skills

​Market services

​Market search

​Market orders

​Payment settlement

​Pagination

​Policies

​Observability

​HTTP-only operations

​Errors

​Credential handling

​Related