---
name: Peaq
description: Use when building DePIN applications, registering machines on-chain, querying machine credit ratings, managing machine fleets, submitting revenue/activity events, or integrating robots with blockchain identity and financial infrastructure. Agents should reach for this skill when working with peaqOS (machine identity and credit) or peaqChain (protocol layer).
metadata:
    mintlify-proj: peaq
    version: "1.0"
---

# peaq Skill

## Product summary

peaq is a blockchain platform for the machine economy. **peaqOS** is the operating system layer that gives robots and machines on-chain identity (peaqID), credit ratings (MCR), and financial infrastructure. **peaqChain** is the L1 blockchain where peaqOS contracts live. Most teams use peaqOS SDK (JavaScript, Python, or ROS 2) to register machines, submit revenue/activity events, and query credit ratings via the MCR API. Key files: `.env` (RPC URL, private key, contract addresses), peaqOS SDK packages (`@peaqos/peaq-os-sdk` for JS, `peaq-os-sdk` for Python), CLI (`peaq-os-cli`). Primary docs: https://docs.peaq.xyz

## When to use

Reach for this skill when:
- Registering a machine or fleet on peaq (self-managed or proxy operator pattern)
- Submitting revenue or activity events to build a machine's credit rating
- Querying a machine's MCR score, profile, or operator fleet via API
- Building a DePIN application that needs machine identity and financial data
- Integrating ROS 2 robots with blockchain identity and storage
- Troubleshooting machine onboarding, event submission, or API queries
- Configuring environment variables, RPC endpoints, or contract addresses

Do not use this skill for: account creation, wallet setup, staking/delegation (use peaqChain docs), or Solidity smart contract development (use peaqChain Build tab).

## Quick reference

### Installation paths

| Use case | Command |
| :-- | :-- |
| **Agent skill** | `pip install peaq-os-cli && npx @peaqos/skills add peaqos` |
| **CLI** | `pip install peaq-os-cli` |
| **JavaScript** | `npm install @peaqos/peaq-os-sdk viem dotenv` |
| **Python** | `pip install peaq-os-sdk python-dotenv` |
| **ROS 2** | `git clone https://github.com/peaqnetwork/peaq-robotics-ros2.git && colcon build` |

### Essential environment variables

```bash
PEAQOS_RPC_URL=https://peaq.api.onfinality.io/public  # or agung testnet
PEAQOS_PRIVATE_KEY=0x...                               # owner/operator wallet
PEAQOS_MCR_API_URL=https://mcr.peaq.xyz               # MCR API (optional, defaults to localhost)
IDENTITY_REGISTRY_ADDRESS=0xb53Af985765031936311273599389b5B68aC9956
IDENTITY_STAKING_ADDRESS=0x11c05A650704136786253e8685f56879A202b1C7
EVENT_REGISTRY_ADDRESS=0x43c6c12eecAf4fB3F164375A9c44f8a6Efc139b9
MACHINE_NFT_ADDRESS=0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9
DID_REGISTRY_ADDRESS=0x0000000000000000000000000000000000000800
BATCH_PRECOMPILE_ADDRESS=0x0000000000000000000000000000000000000805
```

For agung testnet, use different contract addresses (see install guide). `PeaqosClient.fromEnv()` auto-populates mainnet addresses; override only for custom deploys.

### CLI commands

| Command | Purpose |
| :-- | :-- |
| `peaqos init` | Interactive setup wizard for `.env` |
| `peaqos activate --doc-url URL --data-api URL` | Register machine end-to-end (self-managed) |
| `peaqos activate --for 0xMachine --machine-key file.key --doc-url URL --data-api URL` | Register machine via proxy operator |
| `peaqos qualify event --machine-id 42 --type revenue --value 500 --ts 2026-04-23T12:00:00Z` | Submit revenue event (500 cents = $5.00) |
| `peaqos qualify mcr did:peaq:0xAddress` | Query machine credit rating |
| `peaqos show machine did:peaq:0xAddress` | Fetch full machine profile |
| `peaqos show operator machines did:peaq:0xOperator` | List operator's fleet with MCR scores |
| `peaqos wallet create name` | Generate new OWS wallet |

### SDK quick patterns

**JavaScript:**
```typescript
import { PeaqosClient } from "@peaqos/peaq-os-sdk";
const client = PeaqosClient.fromEnv();
const machineId = await client.registerMachine();
```

**Python:**
```python
from peaq_os_sdk import PeaqosClient
client = PeaqosClient.from_env()
machine_id = client.register_machine()
```

### Event submission (revenue)

| Field | Type | Example |
| :-- | :-- | :-- |
| `machineId` | integer | `42` |
| `eventType` | `0` (revenue) or `1` (activity) | `0` |
| `value` | ISO 4217 minor units | `500` (= $5.00 USD) |
| `currency` | ISO 4217 code | `"USD"`, `"HKD"`, `"JPY"` |
| `timestamp` | Unix seconds | `Math.floor(Date.now() / 1000)` |
| `trustLevel` | `0` (self), `1` (on-chain), `2` (hardware) | `0` |
| `sourceChainId` | `3338` (peaq) or `8453` (Base) | `3338` |
| `sourceTxHash` | 0x-prefixed 32-byte hex (required if trustLevel=1) | `"0xabc123..."` |

## Decision guidance

### When to use self-managed vs proxy operator registration

| Scenario | Use |
| :-- | :-- |
| Single machine with its own key | Self-managed (`registerMachine`) |
| Fleet of machines, one operator | Proxy operator (`registerFor`) |
| Machine cannot hold keys (sensor, embedded) | Proxy operator |
| Centralized identity control needed | Proxy operator |
| Machine signs its own transactions | Self-managed |

### When to use trust levels for events

| Trust level | When to use | Requires |
| :-- | :-- | :-- |
| `0` (self-reported) | Machine self-reports revenue/activity | Nothing |
| `1` (on-chain verifiable) | Revenue from another chain (Base) | `sourceTxHash` (32-byte hex) |
| `2` (hardware-signed) | Tamper-resistant hardware attestation | Hardware signature |

### When to query MCR API vs SDK

| Task | Use |
| :-- | :-- |
| Get machine's credit score | `GET /mcr/{did}` (API) or `query_mcr()` (SDK) |
| Get full machine profile | `GET /machine/{did}` (API) or `query_machine()` (SDK) |
| List operator's fleet | `GET /operator/{did}/machines` (API) or `query_operator_machines()` (SDK) |
| Submit event | SDK only (`submitEvent` / `submit_event`) |
| Register machine | SDK only (`registerMachine` / `register_machine`) |

## Workflow

### Register a single machine (self-managed)

1. **Set up environment.** Create `.env` with `PEAQOS_RPC_URL`, `PEAQOS_PRIVATE_KEY`, and contract addresses. Run `peaqos init` to scaffold interactively.
2. **Generate machine keypair.** Call `PeaqosClient.generateKeypair()` (JS) or `PeaqosClient.generate_keypair()` (Python) to create a new address.
3. **Set up 2FA on owner wallet.** Call `setupFaucet2FA()` / `setup_faucet_2fa()` to enroll with the Gas Station. Scan the QR code into your authenticator app.
4. **Confirm 2FA.** Submit the TOTP code via `confirmFaucet2FA()` / `confirm_faucet_2fa()`.
5. **Fund the machine wallet.** Call `fundFromGasStation()` / `fund_from_gas_station()` with a fresh TOTP code to get initial gas.
6. **Register the machine.** Build a client with the machine's private key and call `registerMachine()` / `register_machine()`. This sends 1 PEAQ bond.
7. **Mint the Machine NFT.** Call `mintNft(machineId, address)` / `mint_nft()` to create the financial NFT.
8. **Write DID attributes.** Call `writeMachineDIDAttributes()` / `write_machine_did_attributes()` with documentation URL, data API, and visibility level.
9. **Verify.** Query the MCR API: `curl https://mcr.peaq.xyz/machine/did:peaq:0xYourAddress` should return the machine profile.

### Register a fleet (proxy operator)

1. **Self-register the proxy operator first.** Run the self-managed flow above for the proxy's own wallet. Persist the proxy's `machineId`.
2. **For each machine:** Generate a keypair, call `registerFor(machineAddress)` / `register_for()` (proxy signs), mint NFT, fund the machine wallet, then have the machine sign its own DID attributes.
3. **Publish the fleet.** Call `writeProxyDIDAttributes()` / `write_proxy_did_attributes()` with the proxy's `machineId` and the list of all machine IDs.
4. **Verify.** Query `GET /operator/did:peaq:0xProxyAddress/machines` to list the fleet.

### Submit a revenue event

1. **Validate parameters.** Call `validateSubmitEventParams()` / `validate_submit_event_params()` to catch errors early.
2. **Compute data hash.** Call `computeDataHash(rawData)` / `compute_data_hash()` to hash the raw event payload.
3. **Submit the event.** Call `submitEvent()` / `submit_event()` with machine ID, event type (0 for revenue), value in minor units, currency, timestamp, and trust level.
4. **Check the MCR.** After a few events, query `GET /mcr/{did}` to see the machine's updated credit score.

### Query machine credit rating

1. **Get the machine DID.** Format: `did:peaq:0x<40-hex-chars>` (the machine's EVM address).
2. **Call the MCR API.** `curl https://mcr.peaq.xyz/mcr/did:peaq:0xAddress` or use SDK `query_mcr()` / `query_mcr()`.
3. **Parse the response.** Extract `mcr` (letter rating), `mcr_score` (0-100), `bond_status`, `revenue_trend`, and `event_count`.

## Common gotchas

- **Missing environment variables.** `PeaqosClient.fromEnv()` throws `ValidationError` if any required variable is missing. Check `.env` and shell exports.
- **2FA lockout.** After 3 invalid TOTP codes, the Gas Station locks the owner for a cooldown window. Wait before retrying.
- **Machine not found on MCR API.** The machine must have written its own DID attributes (including `machineId` binding) before the API can find it. Proxy-registered machines must call `writeMachineDIDAttributes()` from the machine's own key.
- **Insufficient balance.** Register requires 1 PEAQ bond + gas. Proxy fleets need N * 1.1 PEAQ for N machines. Top up the wallet before retrying.
- **AlreadyRegistered error.** The address is already on the IdentityRegistry. Query the MCR API with the address to find the existing machine ID.
- **Event validation fails.** Check: `machineId` is positive, `eventType` is 0 or 1, `value` is non-negative, `currency` matches `^[A-Z0-9]{3,10}$` for revenue (empty for activity), `trustLevel` is 0/1/2, `sourceTxHash` is required when `trustLevel === 1`.
- **Proxy precondition.** The proxy operator must be self-registered first (have its own `machineId`). If not, `registerFor()` exits with an error before spending gas.
- **ROS 2 key leakage.** ROS 2 services wrap the SDK but keep keys out of ROS messages. Never pass private keys through ROS topics.
- **Testnet vs mainnet.** agung testnet uses different contract addresses. Use `PEAQOS_NETWORK=testnet` in the CLI or override contract addresses in the SDK.

## Verification checklist

Before submitting work:

- [ ] Environment variables are set and validated (`peaqos whoami` succeeds)
- [ ] Machine is registered on-chain (query MCR API returns the machine DID)
- [ ] Machine NFT is minted (check `tokenIdOf(machineId)` returns a non-zero ID)
- [ ] Machine DID attributes are written (MCR API `/machine/{did}` returns the machine profile, not 404)
- [ ] Events are submitted with valid parameters (no `ValidationError`)
- [ ] MCR score is updating (query `/mcr/{did}` after submitting events; score should change)
- [ ] Proxy fleet is published (query `/operator/{did}/machines` returns all registered machines)
- [ ] Private keys are stored securely (not in shell history, not in code, not in ROS messages)
- [ ] 2FA is set up on the owner wallet (required for Gas Station funding)
- [ ] Testnet vs mainnet is correct (check RPC URL and contract addresses match the target network)

## Resources

- **Comprehensive navigation:** https://docs.peaq.xyz/llms.txt
- **peaqOS overview:** https://docs.peaq.xyz/peaqos/overview
- **Self-managed onboarding guide:** https://docs.peaq.xyz/peaqos/guides/self-managed-onboarding
- **MCR API reference:** https://docs.peaq.xyz/peaqos/api-reference/overview
- **Submit events guide:** https://docs.peaq.xyz/peaqos/guides/submit-events
- **CLI reference:** https://docs.peaq.xyz/peaqos/cli
- **SDK reference (JS):** https://docs.peaq.xyz/peaqos/sdk-reference/sdk-js
- **SDK reference (Python):** https://docs.peaq.xyz/peaqos/sdk-reference/sdk-python
- **ROS 2 integration:** https://docs.peaq.xyz/peaqos/sdk-reference/ros2/overview
- **GitHub repos:** https://github.com/peaqnetwork
- **Discord community:** https://www.discord.gg/peaqnetwork

---

> For additional documentation and navigation, see: https://docs.peaq.xyz/llms.txt