Owner equals operator. One keypair, one machine, one identity. This guide covers the full flow from environment setup through on-chain registration.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.
Prerequisites
- Node.js ≥ 22 or Python 3.10+
- A funded EVM wallet (the owner address) with at least 1.1 PEAQ (1 PEAQ bond + gas)
- Environment variables configured per the install guide
Environment setup
Set these environment variables before running any SDK call. Both SDKs read the same variable names..env
JS examples load the file via
import "dotenv/config". Python’s from_env() reads from the shell, so export the file first with set -a && source .env && set +a.Full flow
Initialize the client from environment
fromEnv reads all required variables and returns a configured client. Throws ValidationError if any variable is missing.Generate a keypair (optional)
If the machine does not already have a wallet, generate one. This is a local operation with no chain interaction.If the machine already has a funded wallet, skip to step 5 and construct the client with that key directly. Steps 3-5 will fund the generated keypair.
Set up 2FA on the owner wallet
The Gas Station requires 2FA before it funds any address. Call
setupFaucet2FA to start enrollment.Fund the machine wallet
Request initial gas from the Gas Station. The faucet either funds the wallet or skips if the balance is already sufficient.
Register the machine
Call
registerMachine to register the machine on the IdentityRegistry. The call sends 1 PEAQ as a bond with the transaction.registerMachine mints the Identity NFT (tokenId == machineId) and stakes the bond. It does not mint the Machine NFT or write DID attributes; those are two separate calls in the next step.Mint the Machine NFT and link the DID
Call The Machine NFT gets an independent
mintNft to create the machine’s financial NFT, then writeMachineDIDAttributes to bind machineId and the new nftTokenId to the machine’s DID.tokenId separate from machineId. See Machine NFT ownership for the full rationale.After all three calls, the machine has a peaqID, an Identity NFT, a Machine NFT, and a 1 PEAQ bond. It starts as Provisioned: on-chain, but not yet rated. It will graduate onto the rated MCR scale once it accumulates enough revenue and activity events.Error handling
| Error | Cause | Resolution |
|---|---|---|
ValidationError: PEAQOS_PRIVATE_KEY is required | Missing environment variable | Check your .env file and shell export |
AlreadyRegistered (both SDKs) | The address is already registered | Query the MCR API with the address to find the existing machine ID |
RuntimeError: Invalid 2FA code / ApiError: Invalid 2FA code | TOTP code expired or mistyped | Wait for a fresh code from your authenticator and retry |
RuntimeError: 2FA locked / ApiError: 2FA locked | Too many invalid 2FA attempts | Wait before retrying |
RuntimeError: Faucet rate limit exceeded / ApiError: Faucet rate limit exceeded | Too many funding requests | Wait and retry after a short interval |
RuntimeError: Owner daily funding cap exceeded / ApiError: Owner daily funding cap exceeded | Daily funding cap reached for this owner | Fund manually or wait until the cap resets |
| Insufficient balance for gas + bond | Wallet does not hold 1 PEAQ + gas | Top up the machine wallet and retry |
What the machine receives
After completing the full flow (register + mint NFT + write DID attributes):- peaqID (W3C DID) anchoring the machine’s identity
- Identity NFT minted automatically at registration (
tokenId == machineId) - Machine NFT (LayerZero V2 ONFT) minted via
mintNft, with an independenttokenId - 1 PEAQ bond deposited into the IdentityStaking contract
- Gas Station funding (if requested)

