> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Machine Markets: Machines & identity

> Identity challenges and machine CRUD for the peaqOS Machine Markets API.

These endpoints register and update machine records in the orchestration service. When `PEAQOS_MACHINE_IDENTITY_VERIFICATION=required` is on (production default), the caller must include a signed <Tooltip tip={G.eip191.def}>EIP-191</Tooltip> controller proof obtained from a <Tooltip tip={G.challenge.def}>challenge</Tooltip> before the orchestrator will persist any machine-bound write.

See the [Machine Markets overview](/peaqos/api-reference/machine-markets-overview) for base path, auth model, common envelopes, and error codes.

## `Machine` type

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
type Machine = {
  id: string;
  displayName: string;
  status: "draft" | "active" | "degraded" | "blocked" | "archived";
  ownerId: string;
  identityRef: string;          // did:peaq:0x... or peaqos:machine:<id>
  identityProof?: {
    method: "eip191";
    identityRef: string;
    signerAddress: string;
    challengeId: string;
    verifiedAt: string;
    challengeExpiresAt: string;
    controllerAddresses: string[];
    resolutionSource: "peaqos-mcr";
  } | null;
  machineType: string;
  runtimeProfile: string;
  capabilities: string[];
  labels: Record<string, string>;
  policyIds: string[];
  skillKeys: string[];
  createdAt: string;
  updatedAt: string;
};
```

## Machine identity

### `POST /machine-identity/challenges`

Creates a short-lived challenge for a peaqOS machine identity. The caller signs `message` with the DID-controller private key and submits `{ challengeId, signature }` as `identityProof` when creating or updating the machine.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
type CreateMachineIdentityChallengeRequest = {
  identityRef: string; // did:peaq:0x... or peaqos:machine:<id>
};

type CreateMachineIdentityChallengeResponse = ItemResponse<{
  challengeId: string;
  identityRef: string;
  message: string;
  expiresAt: string;
  verificationMethod: "eip191";
  controllerAddresses: string[];
}>;

type MachineIdentityProofInput = {
  challengeId: string;
  signature: string;     // EIP-191 personal_sign
};
```

Challenges expire. If a proof is submitted past `expiresAt` the orchestrator returns `MACHINE_IDENTITY_PROOF_EXPIRED` and the caller must re-challenge.

## Machines

### `GET /machines`

Only returns machines whose `identityRef` resolves and whose stored `identityProof` matches <Tooltip tip={G.mcr.def}>MCR</Tooltip> controller data. Draft machines without a verified proof are filtered out.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
type ListMachinesResponse = ListResponse<Machine>;
```

### `POST /machines`

Creates a machine record. Requires `identityProof` when identity verification is enabled.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
type CreateMachineRequest = {
  displayName: string;
  ownerId: string;
  machineType: string;
  runtimeProfile: string;
  identityRef: string;
  identityProof?: MachineIdentityProofInput;
  capabilities?: string[];
  labels?: Record<string, string>;
  policyIds?: string[];
  skillKeys?: string[];
};

type CreateMachineResponse = ItemResponse<Machine>;
```

Errors: `MACHINE_IDENTITY_PROOF_REQUIRED`, `MACHINE_IDENTITY_PROOF_INVALID`, `MACHINE_IDENTITY_PROOF_EXPIRED`, `MACHINE_IDENTITY_EXISTS`, `PEAQOS_IDENTITY_UNAVAILABLE`, `VALIDATION_ERROR`.

### `GET /machines/:machineId`

The orchestrator re-verifies the persisted identity proof against peaqOS MCR data on every read. Returns `MACHINE_NOT_ACTIVATED` if the machine no longer resolves through MCR.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
type GetMachineResponse = ItemResponse<Machine>;
```

### `PATCH /machines/:machineId`

Partial update. `identityRef` is immutable once set; attempting to change it returns `MACHINE_IDENTITY_IMMUTABLE`. Identity proofs are re-verified on every update. Activating an unverified machine returns `MACHINE_NOT_ACTIVATED`. Submitting a proof that does not recover to an MCR controller returns `MACHINE_IDENTITY_PROOF_INVALID`. MCR resolution failures return `PEAQOS_IDENTITY_UNAVAILABLE`.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
type UpdateMachineRequest = Partial<CreateMachineRequest> & {
  status?: Machine["status"];
};

type UpdateMachineResponse = ItemResponse<Machine>;
```

## Related

* [Machine Markets overview](/peaqos/api-reference/machine-markets-overview)
* [Machine Markets: Pairings](/peaqos/api-reference/machine-markets-pairings)
* [Machine Markets: Skills, services, search](/peaqos/api-reference/machine-markets-discovery)
* [Machine Markets concept](/peaqos/concepts/machine-markets)