403 MACHINE_NOT_ACTIVATED. See Scale.
The Machine Markets API is the HTTP/JSON interface for Scale. It handles machine identity proofs, machine records, , the skill registry, the service catalogue, and machine-aware market search.
Base path
All endpoints sit under/api/v1 on the orchestrator host. The canonical peaq-managed endpoint is https://orchestration.peaq.xyz:
PEAQOS_ORCHESTRATION_URL at it.
Access model
- The API is public unless the deployment enables API-key auth (
PEAQOS_REQUIRE_API_AUTH=true). - Machine registration accepts
identityRefas a peaqdid:peaq:<decimal machine id>orpeaqos:machine:<decimal machine id>; both resolve against the MCR (seePEAQOS_MCR_API_URLbelow). An address DID (did:peaq:0x...) is refused with400 VALIDATION_ERROR. - When
PEAQOS_MACHINE_IDENTITY_VERIFICATION=required(production default), every machine registration and machine-bound write verifiesidentityRefagainst peaqOS 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( for an EVM address, for a base58 Solana public key; the orchestrator picks the scheme from the address). The orchestrator verifies the signature, persists the pairing, and issues a signed session JWT aspairingToken. - Market search requires (a) a machine whose orchestrator record has status
activeand whose MCR machine profile (GET /machine/did:peaq:<id>) is homed on peaq or Solana, notactive: false, and hasbond_status: "bonded", (b) a verifiedidentityRefwith ownership proof, and (c) an active Machine Agent pairing. The orchestrator checks the profile at registration and on every machine-bound write; an unbonded machine is refused with403 MACHINE_NOT_ACTIVATED. - When
PEAQOS_REQUIRE_AGENT_PAIRING_AUTH=true(set on peaq’s deployment), market search must include thex-agent-pairing-tokenheader. The token is a signed HS256 JWT with claims formachineId,pairingId,sessionId,agentAddress,agentDid,delegationPolicyHash, and expiry. Rotate it via the pairing sessions endpoint beforeexp. - 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, , wallet rails). Operators or machines pay the selected provider directly through that provider’s supported . pay.sh and Agentic Market services use request-scoped payment proofs: the API returns the provider’s payment challenge frompayment-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
Error codes
Common types
Pagination
Every list endpoint acceptsListQuery.
- First page omits
cursor. nextCursoris omitted when there is no next page. It is nevernull.- Pass
nextCursorback unchanged on the next request. - Invalid
limit(out of range or non-integer) or malformedcursorreturns400 VALIDATION_ERROR.
Health
Endpoint groups
Machines & identity
Identity challenges, machine CRUD, controller proofs (EIP-191 or ed25519).
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. These are the server’s built-in defaults; a deployment’s.env can override them.

