Skip to main content
One owner, many machines. The pattern lets a single register and control a fleet of machines. Each machine gets its own on registration; the is in a follow-up mintNft call. The proxy operator holds the ownership of every identity.

When to use proxy registration

Use registerFor when:
  • You operate physical hardware that cannot hold its own keys (offline sensors, embedded devices)
  • You manage a fleet and want centralized identity control
  • You need batch onboarding of many machines from a single script. The IdentityRegistry contract puts no cap on machines per operator, but the operator’s machines is capped at 100 entries (newer registrations push older ones out of the index), and the MCR API operator endpoint paginates with limit ≤ 20 per request — iterate via offset against pagination.total to walk the full set, or enumerate against the contract directly for fleets that need more than the indexed 100.
Use self-managed onboarding when the machine holds its own key and registers itself.

Prerequisites

  • Node.js ≥ 22 or Python 3.10+
  • A funded proxy operator wallet with at least (N * 1.1) (1 PEAQ + per machine)
  • The proxy operator must be self-registered first: registerMachine from the proxy’s own key, exactly as in self-managed onboarding. The proxy’s machineId is required to publish the fleet under its DID.
  • Environment variables configured per the install guide
  • 2FA set up and confirmed on the operator wallet (see self-managed onboarding steps 3 and 4)
JS examples load .env via import "dotenv/config". Python’s from_env() reads from the shell, so export the file first with set -a && source .env && set +a.

Single machine registration

1

Create the proxy client

The proxy operator’s all on behalf of the fleet.
2

Generate a keypair for the machine

Each machine needs its own . Generate one per device.
3

Register the machine via proxy

registerFor registers the machine address on the IdentityRegistry. The proxy’s signing address (msg.sender) becomes the on-chain owner. The call sends 1 PEAQ as the bond.
4

Mint the Machine NFT (proxy)

Registration only mints the . The proxy mints the Machine NFT to the machine’s address.
5

Fund the machine wallet

The machine signs its own DID writes, so its wallet needs a small amount of PEAQ for gas. Use the Gas Station from the proxy (2FA-gated), or top it up directly from any PEAQ-holding address.
6

Machine writes its own DID attributes

writeMachineDIDAttributes always writes to the caller’s DID. The proxy can’t write to the machine’s DID for it. Spin up a separate client backed by the machine’s key and have the machine sign its own attribute writes. Skip this step and the machine is unreachable through the : GET /machine/{did} and GET /mcr/{did} will 404 because no machineId attribute is bound to the machine’s address.
7

Proxy publishes the fleet on its DID

writeProxyDIDAttributes writes the proxy’s machineId and the list of machine IDs it controls onto the proxy’s DID. This is what the GET /operator/{did}/machines endpoint reads from.
See Machine NFT ownership for the full rationale.

Batch registration (10 machines)

Register multiple machines sequentially. Each iteration runs the full activate path (register, mint NFT, fund the machine, machine writes its own DID); then the proxy publishes the full fleet on its DID at the end.
The CLI does this whole flow in one command: peaqos activate --for 0xMachineAddress --machine-key ./machine.key. See CLI reference.

Per-machine key vs shared key

Two approaches for managing machine keys in a proxy fleet: Recommendation: Use per-machine keys when the device can store secrets (HSM, TEE, encrypted filesystem). Use a shared proxy key for offline or passive hardware (sensors, meters) that never needs to sign.
On the roadmap. Proxy key management for offline devices is evolving. The current SDK supports both patterns above. Watch the roadmap for additional device-key options as they land.

Fleet queries

After registration, query the MCR API to list all machines under a proxy operator.
curl
Response shape:
See GET /operator/{did}/machines for full details.

Error handling