---
name: peaq
description: Use when building machine economy applications, onboarding machines
  with identity and credit ratings, submitting revenue/activity events, querying
  machine credit scores, managing machine fleets, or integrating machine markets
  and autonomous agent delegation. Agents should reach for this skill when
  working with peaqOS (machine identity, credit, payments) or the peaq Trust
  Layer (chain primitives, smart contracts, staking).
metadata:
  mintlify-proj: peaq
  version: "1.0"
---

# Peaq Skill

## Product summary

Peaq is an economic infrastructure platform that turns machines (robots, vehicles, sensors, AI agents) into economic participants. **peaqOS** is the machine operating system layer where most teams start—it provides identity (peaqID), credit ratings (MCR), payments, and machine earnings through one SDK. **peaq Trust Layer** (peaq chain) is the underlying blockchain infrastructure for ownership, reputation, and coordination.

Agents work primarily with peaqOS via the CLI (`peaq-os-cli`), JavaScript SDK (`@peaqos/peaq-os-sdk`), or Python SDK (`peaq-os-sdk`). Key files: `.env` (configuration), `did.json` (DID document for activation), `peaqos.log` (transaction journal). Primary docs: https://docs.peaq.xyz

## When to use

Reach for this skill when:
- **Activating machines**: Onboarding a single machine or a fleet with identity and subscription bond
- **Querying credit ratings**: Fetching a machine's MCR (Machine Credit Rating) from any chain via the public API
- **Submitting events**: Recording revenue or activity events that feed the MCR scoring pipeline
- **Managing fleets**: Operating multiple machines with one operator controlling many machine-owned NFTs
- **Delegating to agents**: Pairing an AI agent to a machine and setting spend limits (Scale function, currently paused)
- **Verifying machines**: Checking hardware (chip) and operator (KYB) attestations
- **Bridging machines**: Moving Machine NFTs between peaq and Base via LayerZero
- **Solana integration**: Homing machines on Solana instead of peaq, paying bonds in PEAQ or USDC

Do not use this skill for: wallet setup alone, staking/validator operations, or raw chain transactions (use peaq chain SDK directly for those).

## Quick reference

### CLI commands (peaqOS)

| Task | Command |
| :-- | :-- |
| Initialize config | `peaqos init` |
| Check setup | `peaqos whoami` |
| Activate a machine | `peaqos activate --machine-type Sensor --credential-subject-hex 0x... --manufacturer 0x... --tier entry --did-document ./did.json` |
| Query MCR | `peaqos qualify mcr --machine-id <decimal-id>` |
| Submit revenue event | `peaqos qualify event --machine-id <id> --type revenue --value 500 --currency USD --ts $(date +%s)` |
| Submit activity event | `peaqos qualify event --machine-id <id> --type activity --value 0 --ts $(date +%s)` |
| Check machine status | `peaqos machine status --machine-id <id>` |
| Renew subscription | `peaqos machine subscription renew --machine-id <id>` |
| Verify machine | `peaqos verify status --machine-id <id>` |

### Environment variables (required)

| Variable | Purpose | Example |
| :-- | :-- | :-- |
| `PEAQOS_RPC_URL` | peaq chain RPC | `https://peaq.api.onfinality.io/public` |
| `PEAQOS_PRIVATE_KEY` | Owner wallet key (hex) | `0x...` |
| `TOKENOMICS_DEPLOYMENT_ID` | Economics 2.0 deployment | `peaq-mainnet` or `agung-2026-08-28` |
| `PEAQOS_GAS_STATION_URL` | Faucet for funding | `https://depinstation.peaq.xyz` |
| `EVENT_REGISTRY_ADDRESS` | Event contract (2.0) | `0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e` |

For Solana-homed machines, also set:
- `PEAQOS_SVM_RPC_URL`: Solana endpoint
- `PEAQOS_SVM_NETWORK`: `mainnet-beta`
- `PEAQOS_OWS_WALLET`: OWS vault wallet name

### DID document schema (required for activation)

```json
{
  "verificationMethods": [
    {
      "id": "#key-1",
      "methodType": "Ed25519VerificationKey2020",
      "controller": "0x...",
      "publicKeyMultibase": "z6Mk..."
    }
  ],
  "authentication": [0],
  "serviceEndpoints": [
    {
      "id": "#telemetry",
      "serviceType": "TelemetryService",
      "serviceEndpoint": "https://machine.example/telemetry"
    }
  ]
}
```

### Event submission (revenue vs activity)

| Field | Revenue (type 0) | Activity (type 1) |
| :-- | :-- | :-- |
| `type` | `0` | `1` |
| `value` | ISO 4217 minor units (e.g., 500 = $5.00) | `0` |
| `currency` | 3-10 char code (e.g., `USD`) | Empty string `""` |
| `trustLevel` | `0` (self), `1` (on-chain), `2` (hardware) | `0` (self), `1`, or `2` |

### Subscription tiers (Economics 2.0)

| Tier | Value | USD price (365 days) |
| :-- | :-- | :-- |
| Entry | `0` | $0.02 |
| Basic | `1` | $0.20 |
| Pro | `2` | $40.00 |

### API endpoints (MCR API at https://mcr.peaq.xyz)

| Endpoint | Purpose |
| :-- | :-- |
| `GET /mcr/did:peaq:<decimal-id>` | Machine Credit Rating score and trend |
| `GET /machine/<decimal-id>` | Full machine profile (identity, rating, bond status) |
| `GET /operator/did:peaq:0x<address>/machines` | List machines owned/controlled by operator |
| `GET /machines/<decimal-id>` | Machine Card (services, registrations, operator) |
| `GET /health` | Readiness probe |

## Decision guidance

### When to use CLI vs SDK

| Scenario | Use |
| :-- | :-- |
| One-off activation, testing, scripting | CLI (`peaqos activate ...`) |
| Embedded in application, batch operations | SDK (JS or Python) |
| ROS 2 robot integration | ROS 2 node (Tokenomics 1.0 only) |
| Agent-driven workflows | Agent skill (`/peaqos` in Claude Code) |

### When to use peaqOS vs peaq chain SDK

| I want to... | Use |
| :-- | :-- |
| Activate a machine with identity | peaqOS SDK / CLI |
| Query machine credit rating | peaqOS MCR API |
| Submit revenue/activity events | peaqOS SDK / CLI |
| Delegate to an AI agent | peaqOS Scale (paused) |
| Deploy a smart contract | peaq chain SDK |
| Run a validator | peaq chain docs |
| Use DID/RBAC/storage primitives directly | peaq chain SDK |

### Solana vs peaq home chain

| Consideration | peaq home | Solana home |
| :-- | :-- | :-- |
| Bond payment | PEAQ on peaq | PEAQ or USDC on Solana |
| Identity storage | peaq contracts | Solana accounts |
| Activation steps | 1 transaction | 7 stages (2 chains) |
| Event submission | peaq EventRegistry | Solana EventRegistry program |
| CLI version required | 0.0.12+ | 0.0.19+ |
| Setup complexity | Simple | More complex (two wallets, two RPCs) |

## Workflow

### Typical activation flow (peaq home)

1. **Prepare environment**
   - Set `PEAQOS_RPC_URL`, `PEAQOS_PRIVATE_KEY`, `TOKENOMICS_DEPLOYMENT_ID`
   - Run `peaqos init` to scaffold `.env` interactively
   - Verify with `peaqos whoami`

2. **Create DID document**
   - Write `did.json` with three required fields: `verificationMethods`, `authentication`, `serviceEndpoints`
   - Ensure `authentication` indices are valid (bounds-checked by CLI)

3. **Preview activation**
   - Run `peaqos activate --machine-type Sensor --credential-subject-hex 0x... --manufacturer 0x... --tier entry --did-document ./did.json --dry-run`
   - Check bond amount, voucher credit, net PEAQ needed
   - Verify Gas Station URL is set if wallet needs funding

4. **Fund wallet (if needed)**
   - CLI prompts for 2FA code from Gas Station
   - Funding is automatic unless `--skip-funding` is set

5. **Submit activation**
   - Drop `--dry-run`, add `--yes` for non-interactive mode
   - CLI submits one atomic transaction to `MachineStateAndSync.activateMachine`
   - Mints ERC-721, stores DID, bonds PEAQ, records home chain

6. **Verify activation**
   - Check `peaqos.log` for transaction hash
   - Run `peaqos machine status --machine-id <id>` to confirm on-chain state
   - Query MCR: `peaqos qualify mcr --machine-id <id>` (may show "Provisioned" initially)

### Submitting events (revenue example)

1. **Validate event parameters** before submission
   - Machine ID must be positive `bigint` (JS) or `int` (Python)
   - Value in ISO 4217 minor units (cents for USD)
   - Currency code 3-10 uppercase alphanumerics for revenue
   - Timestamp must be on or before block time

2. **Compute data hash** (optional but recommended)
   - Use `computeDataHash` (JS) or `compute_data_hash` (Python)
   - Store hash for later verification

3. **Submit event**
   - CLI: `peaqos qualify event --machine-id <id> --type revenue --value 500 --currency USD --ts $(date +%s)`
   - SDK: `client.submitEvent(params)` returns `(txHash, dataHash)`

4. **Check MCR update**
   - MCR indexes events within minutes
   - Query `peaqos qualify mcr --machine-id <id>` to see updated rating
   - Revenue events under $10 USD do not count toward total_revenue

### Fleet onboarding (machine-owned, operator-controlled)

1. **Generate machine key** for each machine
   - Store securely; machine signs its own activation

2. **Activate with `--for` and `--machine-key`**
   - Operator's key signs nothing; machine key signs and pays
   - Operator address becomes DID controller
   - Operator can renew, suspend, update DID but cannot transfer NFT

3. **Manage fleet**
   - Operator submits events on behalf of all machines
   - Each machine's wallet must have gas for its own events
   - Use `--machine-id` to target specific machines

## Common gotchas

- **Wrong EVENT_REGISTRY_ADDRESS**: Sending a 2.0 event to the 1.0 registry (`0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA`) reverts with `MachineNotFound`. CLI 0.0.13+ defaults to the 2.0 registry; upgrade if needed.

- **Machine ID as number, not bigint**: JavaScript rounds 256-bit machine IDs. Always use `BigInt(id)` or pass as decimal string. The MCR API returns machine IDs as JSON strings for this reason.

- **Currency on activity events**: Activity events must have `currency: ""` (empty string), not omitted. Python SDK does not apply the default for Solana-homed machines; pass it explicitly.

- **Timestamp in the future**: Events with `timestamp` later than the block time are rejected. Use `Math.floor(Date.now() / 1000)` or `int(time.time())`, not a future value.

- **Bond is not withdrawable**: Once bonded, PEAQ stays locked until the subscription ends (grace + runoff = 28 days). Renewal extends the period; it does not unlock the bond.

- **Solana onboarding is seven stages**: Not one transaction. Use `--phase` to run stages individually or omit it to run all seven with waits. Rerun the same command to resume after interruption.

- **MCR is paused for Solana machines**: Events index within minutes, but the machine profile (`peaqos show machine`) does not list them yet (`event_history_not_indexed`).

- **Scale is paused**: Machine Markets registration fails for both Tokenomics 1.0 and Economics 2.0 machines. Pairing and delegation are not available.

- **Tier change on renewal**: The published deployment does not enable tier selection on renewal; `--tier` fails with `RENEWAL_TIER_UNSUPPORTED`. Tier stays the same.

- **USDT settlement not configured on mainnet**: `--payment usdt` fails on peaq mainnet. Pay in PEAQ.

- **Pending transactions**: If a receipt does not arrive, the CLI reports `PENDING` at exit code 2 with the hash. Never submit a second activation for the same machine. Rerun the same command to reconcile the hash.

## Verification checklist

Before submitting work with peaqOS:

- [ ] `.env` has all required variables (`PEAQOS_RPC_URL`, `PEAQOS_PRIVATE_KEY`, `TOKENOMICS_DEPLOYMENT_ID`)
- [ ] `TOKENOMICS_DEPLOYMENT_ID` matches the target network (`peaq-mainnet` or `agung-2026-08-28`)
- [ ] `EVENT_REGISTRY_ADDRESS` is the correct 2.0 registry (`0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e` on mainnet)
- [ ] DID document has exactly three root fields: `verificationMethods`, `authentication`, `serviceEndpoints`
- [ ] Machine ID is a decimal string or `bigint`, never a rounded number
- [ ] Event value is in ISO 4217 minor units (cents for USD, whole units for JPY/KRW/VND)
- [ ] Revenue events have a 3-10 char currency code; activity events have empty string
- [ ] `--dry-run` passes before submitting without it
- [ ] `peaqos.log` exists and is readable (transaction journal for recovery)
- [ ] For Solana machines: both `PEAQOS_SVM_RPC_URL` and `PEAQOS_SVM_NETWORK` are set
- [ ] For fleet operations: machine key is stored securely and `--for` + `--machine-key` are used together

## Resources

**Comprehensive navigation**: https://docs.peaq.xyz/llms.txt

**Critical pages**:
- [peaqOS overview](/peaqos/overview) — architecture, functions, onboarding patterns
- [peaqOS CLI](/peaqos/cli) — full command reference with examples
- [Submit events guide](/peaqos/guides/submit-events) — event types, validation, cross-chain patterns
- [API reference overview](/peaqos/api-reference/overview) — MCR API, Verify API, Machine Markets API
- [Install](/peaqos/install) — SDK setup, environment variables, contract addresses
- [Economics 2.0](/peaqos/concepts/economics-2-0) — activation, bonds, subscription lifecycle, trust validators

---

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