Machine Markets API overview

The Machine Markets API is the HTTP/JSON interface for Scale. It handles machine identity proofs, machine records, Machine Agent pairings, the skill registry, the service catalogue, and machine-aware market search.

Base path

All endpoints sit under /api/v1 on the orchestrator host:

export PEAQOS_API_URL=https://your-orchestrator-host
# All paths below are relative to ${PEAQOS_API_URL}/api/v1

GET /health is an exception: it lives at host root, not under /api/v1, and is exempt from API-key auth. Treat the base host as deployment-specific. The orchestrator is self-hostable via Docker Compose.

Access model

The API is public unless the deployment enables API-key auth (PEAQOS_REQUIRE_API_AUTH=true).
Machine registration accepts identityRef as either a peaq DID (did:peaq:0x...) or a peaqOS machine public ID (peaqos:machine:<id>).
When PEAQOS_MACHINE_IDENTITY_VERIFICATION=required (production default), every machine registration and machine-bound write verifies identityRef against peaqOS MCR data and requires a signed DID-controller challenge.
Machine Agent pairing is challenge-based. The agent signs a server-issued challenge with the wallet key behind agentAddress (EIP-191). The orchestrator verifies the signature, persists the pairing, and issues a signed session JWT as pairingToken.
Market search requires (a) an active, bonded peaqOS machine, (b) a verified identityRef with ownership proof, and (c) an active Machine Agent pairing.
When PEAQOS_REQUIRE_AGENT_PAIRING_AUTH=true (production default), market search must include the x-agent-pairing-token header. The token is a signed HS256 JWT with claims for machineId, pairingId, sessionId, agentAddress, agentDid, delegationPolicyHash, and expiry. Rotate it via the pairing sessions endpoint before exp.
The pairing token proves delegated permission. It does not prove machine activation.
Pass provider credentials per request under providerCredentials. They feed runtime discovery and are redacted before persistence.

Payment model

peaqOS does not collect marketplace payments. The payment-intent and payment-proof endpoints record provider/service payment state only when the selected adapter requires direct provider payment (x402, escrow, wallet rails). Operators or machines pay the selected provider directly through that provider’s supported rail. pay.sh and Agentic Market services use request-scoped payment proofs: the API returns the provider’s payment challenge from payment-intent, the operator agent signs or pays locally, and the resulting proof or header is sent to payment-proof and execute. Raw payment headers are never stored.

Common envelopes

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

type ListQuery = {
  limit?: number;             // 1..500, default 100
  cursor?: string;            // opaque base64url, do not parse
};

type PaymentHeaders = {
  xPayment?: string;
  paymentSignature?: string;
  authorization?: string;
  signInWithX?: string;
};

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

type ErrorResponse = {
  error: {
    code: string;
    message: string;
    details?: unknown;
  };
};

Error codes

type CommonErrorCode =
  // Auth
  | "AUTH_REQUIRED"
  | "AUTH_INVALID"
  | "AGENT_AUTH_REQUIRED"
  | "AGENT_AUTH_INVALID"
  | "AGENT_AUTH_EXPIRED"
  // Generic
  | "VALIDATION_ERROR"
  | "NOT_FOUND"
  // Machine
  | "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"
  // Pairing
  | "AGENT_PAIRING_PROOF_REQUIRED"
  | "AGENT_PAIRING_PROOF_INVALID"
  | "AGENT_PAIRING_PROOF_EXPIRED"
  | "AGENT_PAIRING_UNAVAILABLE"
  | "AGENT_PAIRING_REQUIRED"
  | "AGENT_PAIRING_INACTIVE"
  | "AGENT_POLICY_DENIED"
  | "AGENT_SPEND_LIMIT_EXCEEDED"
  | "AGENT_DAILY_LIMIT_EXCEEDED"
  // Market orders
  | "OPEN_MARKET_ORDERS"
  | "QUOTE_EXPIRED"
  | "ROUTE_REQUIRED"
  | "ORDER_CLOSED"
  | "ORDER_NOT_DELIVERED"
  // Payments
  | "PAYMENT_REQUIRED"
  | "PAYMENT_RPC_REQUIRED"
  | "PAYMENT_RPC_ERROR"
  | "PAYMENT_NOT_MINED"
  | "PAYMENT_TX_FAILED"
  | "PAYMENT_TRANSFER_NOT_FOUND";

Common types

type ExecutionMode = "native" | "external-handoff";

type IntegrationStatus =
  | "native"
  | "credentials-required"
  | "partner-required"
  | "local-config-required"
  | "setup-required"
  | "docs-only";

type ServiceType =
  | "oracle.price-feed"
  | "compute.marketplace"
  | "storage.object"
  | "data.location"
  | "network.partner-console"
  | "identity.proof-of-person"
  | "device.control"
  | "machine.commerce";

type ProviderCredentials = {
  // Per-adapter credentials. Shape is provider-specific and
  // documented per-adapter on robotic.sh. Always redacted
  // before request bodies are persisted.
  [providerKey: string]: Record<string, string | undefined>;
};

Pagination

Every list endpoint accepts ListQuery. Cursors are opaque — do not parse them.

// First page
GET /api/v1/market/services?limit=100

// Next page: pass the previous response's nextCursor exactly as returned
GET /api/v1/market/services?limit=100&cursor=eyJ2IjoxLCJvZmZzZXQiOjEwMH0

Rules:

First page omits cursor.
nextCursor is omitted when there is no next page. It is never null.
Pass nextCursor back unchanged on the next request.
Invalid limit (out of range or non-integer) or malformed cursor returns 400 VALIDATION_ERROR.

Health

Endpoint	Path	Description
`GET /health`	host root (not `/api/v1`)	Process health. Returns `{ ok: true }`. Exempt from API-key auth.
`GET /readiness`	`/api/v1/readiness`	Store, catalog, auth, runtime, and skill checks. Returns `{ status, checks[] }`.

Endpoint groups

Machines & identity

Identity challenges, machine CRUD, EIP-191 controller proofs.

Machine Agent pairings

Challenge-based pairings, session JWT rotation, delegation policy.

Skills & services

Browse the skill registry, the partner service catalogue, and the adapter setup catalogue; run market search.

Market orders & payments

Order lifecycle, payment intent, escrow, execute, confirm, dispute.

Orchestration

Runtime endpoints, machine-side agents, graph, tasks, routes, outcomes, runs, policies, audit events.

Server configuration

When self-hosting the orchestrator, these toggles change the contract callers see. Defaults match the .env.example ships.

Variable	Default	Purpose
`PEAQOS_REQUIRE_API_AUTH`	`false`	Gate every `/api/v1/*` request with a deployment API key (`PEAQOS_API_KEY`/`PEAQOS_API_KEYS`).
`PEAQOS_REQUIRE_AGENT_PAIRING_AUTH`	`true`	Require `x-agent-pairing-token` on market writes.
`PEAQOS_MACHINE_IDENTITY_VERIFICATION`	`required`	Enforce DID-controller proof on machine writes.
`PEAQOS_AGENT_PAIRING_VERIFICATION`	`required`	Enforce EIP-191 challenge proof on pairings.
`PEAQOS_AGENT_PAIRING_SESSION_SECRET`	required in prod	HS256 secret for session JWTs and challenge HMAC.
`PEAQOS_AGENT_PAIRING_CHALLENGE_TTL_MS`	`600000`	Pairing challenge TTL (10 min).
`PEAQOS_AGENT_PAIRING_SESSION_TTL_MS`	`3600000`	Session token TTL (1 hour).
`PEAQOS_REQUIRE_MARKET_QUOTES`	`false`	Reject `POST /market/orders` without `searchId` and `quoteId`.
`PEAQOS_ENFORCE_SERVICE_PAYMENT_RAILS`	`false`	Reject `payment-intent` rails not in the service’s `supportedRails`.
`PEAQOS_REQUIRE_PAYMENT_BEFORE_EXECUTE`	`false`	Block `execute` unless payment is `held` / `release_pending` / `released` / `not_required`.
`PEAQOS_REQUIRE_PAYMENT_RPC_VERIFICATION`	`false`	Force `verificationMode=rpc` on `payment-proof`.
`PEAQOS_PAYMENT_RPC_URL`	falls back to `PEAQ_EVM_RPC_URL`, `PEAQOS_EVM_RPC_URL`	Primary RPC for proof verification.
`PEAQOS_USDT_CONTRACT` / `PEAQOS_USDT_DECIMALS`	none / `6`	Default USDT contract and decimals for payment proof.
`PEAQOS_MCR_API_URL`	`https://mcr.peaq.xyz`	peaqOS MCR endpoint for identity resolution.

API Reference

Documentation Index

​Base path

​Access model

​Payment model

​Common envelopes

​Error codes

​Common types

​Pagination

​Health

​Endpoint groups