SDK: JavaScript

@peaqos/peaq-os-sdk is the opinionated TypeScript entry point for the Machine Financial Passport flow. Chain and API operations are exposed both as PeaqosClient instance methods and as standalone functions; wallet helpers and waitForBridgeArrival are static methods, and readAttribute, encodeAddAttribute and the validation and hashing helpers are standalone functions only. Pass tokenomics20: { deploymentId } to the constructor to enter Tokenomics mode: one-transaction activation, machine management, and the 2.0 monetization client. In that mode the legacy registration, mint, and bridge methods throw typed errors instead of running. Add svm: { deploymentId: "solana-mainnet", rpcUrl } for machines homed on Solana: see Solana (SVM).

Install

npm install @peaqos/peaq-os-sdk viem dotenv

Node.js: ≥ 22
TypeScript: ≥ 5
Peer dependency: viem (^2.54.2)
Economics 2.0: 0.8.0 or newer; Solana onboarding: 0.11.2 or newer, with the optional peers @solana/web3.js and @coral-xyz/anchor (the OWS signer’s @open-wallet-standard/core ships with the SDK)
Exports: ESM and CJS. No bundler workarounds.

dotenv is optional but recommended: PeaqosClient.fromEnv() reads from process.env, so import "dotenv/config" at the top of your entry file is the simplest way to load .env.

Environment variables

Variable	Required	Default	Purpose
`PEAQOS_RPC_URL`	Yes	n/a	peaq chain RPC endpoint
`PEAQOS_PRIVATE_KEY`	Yes	n/a	Owner private key (`0x` + 64 hex)
`IDENTITY_REGISTRY_ADDRESS`	Yes	n/a	Identity Registry contract
`IDENTITY_STAKING_ADDRESS`	Yes	n/a	Identity Staking contract
`EVENT_REGISTRY_ADDRESS`	Yes	n/a	Event Registry contract
`MACHINE_NFT_ADDRESS`	Yes	n/a	Machine NFT contract (ERC-721; bridged through `MachineNFTAdapter`)
`DID_REGISTRY_ADDRESS`	Yes	n/a	DID Registry precompile
`BATCH_PRECOMPILE_ADDRESS`	Yes	n/a	Batch precompile for multi-call bonding
`MACHINE_ACCOUNT_FACTORY_ADDRESS`	No	n/a	`MachineAccountFactory`. Required only for `deploySmartAccount` / `getSmartAccountAddress`.
`MACHINE_NFT_ADAPTER_ADDRESS`	No	n/a	`MachineNFTAdapter` (LayerZero ONFT adapter). Required only for `bridgeNft` when `source === "peaq"`.
`PEAQOS_MCR_API_URL`	No	`http://127.0.0.1:8000`	Sets `apiUrl`. A `tokenomics20` client ignores it and reads the MCR server from the deployment record (`https://mcr.peaq.xyz` for `peaq-mainnet`); the MCR helpers need a `tokenomics20` client.
`TOKENOMICS_DEPLOYMENT_ID`	For 2.0	n/a	Tokenomics 2.0 deployment ID (`peaq-mainnet` or `agung-2026-08-28`). A non-empty value makes `fromEnv()` return a `tokenomics20` client; absent or empty returns a legacy client.
`PEAQOS_ORCHESTRATION_URL`	For Scale	n/a	Machine Markets orchestrator base URL (e.g. `https://orchestration.peaq.xyz`). Required to use `client.orchestration`.
`PEAQOS_API_KEY`	Optional	n/a	Platform API key for `client.orchestration` (sent as `x-api-key`).
`OWS_PASSPHRASE`	Wallet ops	n/a	OWS vault passphrase for create/import/export wallet helpers when no explicit passphrase is passed

PEAQOS_SVM_RPC_URL and PEAQOS_SVM_NETWORK are CLI variables. The SDK takes the Solana endpoint through the svm constructor option, not from the environment: see Solana (SVM).

peaq mainnet contracts

Use these addresses for the legacy contract-address variables (IDENTITY_REGISTRY_ADDRESS and friends, note they are unprefixed) when pointing at peaq mainnet. IdentityRegistry, IdentityStaking, EventRegistry and MachineNFT are UUPS upgradeable proxies; treat those addresses as the current proxy pointers. MachineAccountFactory and MachineNFTAdapter are not proxies, and the DID and batch addresses are native runtime precompiles. EVENT_REGISTRY_ADDRESS here is the Tokenomics 1.0 registry; for Economics 2.0 machines set it to 0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e (see Smart contracts).

Variable	Address
`IDENTITY_REGISTRY_ADDRESS`	`0xb53Af985765031936311273599389b5B68aC9956`
`IDENTITY_STAKING_ADDRESS`	`0x11c05A650704136786253e8685f56879A202b1C7`
`EVENT_REGISTRY_ADDRESS`	`0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA`
`MACHINE_NFT_ADDRESS`	`0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9`
`DID_REGISTRY_ADDRESS`	`0x0000000000000000000000000000000000000800` (peaq DID precompile)
`BATCH_PRECOMPILE_ADDRESS`	`0x0000000000000000000000000000000000000805` (peaq batch precompile)
`MACHINE_ACCOUNT_FACTORY_ADDRESS`	`0x4A808d5A90A2c91739E92C70aF19924e0B3D527f`
`MACHINE_NFT_ADAPTER_ADDRESS`	`0x9AD5408702EC204441A88589B99ADfC2514AFAE6`

For agung testnet addresses see Install → Agung testnet contracts. Bridging is mainnet-only: LayerZero has no DVN routes to agung.

Machine Markets orchestration

Scale lives under client.orchestration, the Machine Markets surface (machine identity proofs, agent pairings, skill registry, market search, orders, payments). Reach it by setting PEAQOS_ORCHESTRATION_URL (and optionally PEAQOS_API_KEY) before PeaqosClient.fromEnv(). Full method reference: Orchestration (JS).

Client

`PeaqosClient`

The client is generic over its mode: PeaqosClient<M extends SdkMode = "legacy"> with readonly mode: M. Construct a 2.0 client as new PeaqosClient<"tokenomics20">({ ...config, tokenomics20: { deploymentId: "peaq-mainnet" } }); without the type argument TypeScript infers "legacy" and the constructor call is a compile error. Query results carry machineId: bigint on a tokenomics20 client and number on a legacy one. fromEnv() returns the union of both and fromWallet() preserves the config’s mode; narrow on client.mode. A config that carries svm takes a second type parameter, PeaqosClient<"tokenomics20", "svmEnabled">: see Solana (SVM).

class PeaqosClient<M extends SdkMode = "legacy", S extends SvmMode = SvmMode> {
  constructor(config: Readonly<PeaqosClientConfig>);

  readonly mode: M;
  readonly rpcUrl: string;
  readonly contracts: Readonly<ContractAddresses>;
  readonly apiUrl: string;
  readonly operationalLimits: Readonly<OperationalLimits>;
  readonly publicClient: PublicClient;
  readonly walletClient: WalletClient;
  readonly tokenomics20: ResolvedTokenomics20Deployment | undefined; // set when the config carries tokenomics20
  readonly svm: SvmDeploymentFor<S>;                                  // set when the config carries svm

  get address(): Address;
  get orchestration(): OrchestrationNamespace;
  get monetization(): MonetizationNamespace;
  get provisioning(): ProvisioningNamespace;

  static fromEnv(): PeaqosClient<"legacy"> | PeaqosClient<"tokenomics20">;
  static fromWallet(
    nameOrId: string,
    passphrase: string | undefined,
    owsSigning: boolean | undefined,
    config: Readonly<Omit<PeaqosClientConfig, "privateKey">>,
    options?: WalletOptions,
  ): Promise<PeaqosClient<"legacy"> | PeaqosClient<"tokenomics20">>; // overloads narrow this to the config's mode
  static solanaSignerFromWallet(nameOrId: string, passphrase?: string, owsSigning?: boolean, options?: WalletOptions, chainId?: string): Promise<OwsSolanaSigner>;
  static generateKeypair(): Readonly<{ address: Address; privateKey: `0x${string}` }>;

  // Static wallet wrappers (thin pass-throughs to the module-level helpers)
  static createWallet(name: string, passphrase?: string, words?: 12 | 24, options?: WalletOptions): Promise<WalletInfo>;
  static importWallet(name: string, privateKey: string, passphrase?: string, chain?: ImportChain, options?: WalletOptions): Promise<WalletInfo>;
  static importWalletMnemonic(name: string, mnemonic: string, passphrase?: string, index?: number, options?: WalletOptions): Promise<WalletInfo>;
  static listWallets(options?: WalletOptions): Promise<WalletInfo[]>;
  static getWallet(nameOrId: string, options?: WalletOptions): Promise<WalletInfo>;
  static exportWallet(nameOrId: string, passphrase?: string, options?: WalletOptions): Promise<string>;
  static deleteWallet(nameOrId: string, options?: WalletOptions): Promise<void>;

  toJSON(): Record<string, unknown>;
  dispose(): Promise<void>;
}

string

required

RPC endpoint (non-empty).

string

required

0x + 64 hex characters.

ContractAddresses

required

All six contract addresses.

string

Defaults to DEFAULT_API_URL. A tokenomics20 client does not read it: the MCR server comes from the deployment record.

OperationalLimits

Per-tx and rate-limit caps. All-zero disables limits.

Returns a PeaqosClient instance. toJSON() and util.inspect output redact the private key ("[REDACTED]"). Other RPC endpoints are available. See Public RPC endpoints.

Show Example

import { PeaqosClient } from "@peaqos/peaq-os-sdk";

const client = new PeaqosClient({
  rpcUrl: "https://peaq.api.onfinality.io/public",
  privateKey: "0xabc...def",
  contracts: {
    identityRegistry: "0x...",
    identityStaking: "0x...",
    eventRegistry: "0x...",
    machineNft: "0x...",
    didRegistry: "0x...",
    batchPrecompile: "0x...",
  },
});

console.log(client.address); // checksummed 0x address

Errors: ValidationError: empty rpcUrl, a privateKey that is not 0x + 64 hex, or a missing contract address (address format is checked by the calls that use it, not here). TokenomicsConfigError: unknown tokenomics20.deploymentId, or svm without tokenomics20.

`fromEnv`

fromEnv() reads TOKENOMICS_DEPLOYMENT_ID: a non-empty value selects Tokenomics mode, absent or empty stays legacy, an unknown or unreleased ID throws TokenomicsConfigError at construction. The return type is PeaqosClient<"legacy"> | PeaqosClient<"tokenomics20">; narrow on client.mode.

static fromEnv(): PeaqosClient<"legacy"> | PeaqosClient<"tokenomics20">;

Returns a fully configured PeaqosClient. All required env vars must be set (see Environment variables).

Show Example

import "dotenv/config";
import { PeaqosClient } from "@peaqos/peaq-os-sdk";

const client = PeaqosClient.fromEnv();

Errors: ValidationError: any required env var missing or empty.

`fromWallet`

static fromWallet(
  nameOrId: string,
  passphrase: string | undefined,
  owsSigning: boolean | undefined,
  config: Readonly<Omit<PeaqosClientConfig, "privateKey">>,
  options?: WalletOptions,
): Promise<PeaqosClient<"legacy"> | PeaqosClient<"tokenomics20">>;

Builds a PeaqosClient from an OWS vault wallet. Overloads keyed on config narrow the return type: tokenomics20 plus svm returns PeaqosClient<"tokenomics20", "svmEnabled">, tokenomics20 alone PeaqosClient<"tokenomics20">, neither PeaqosClient<"legacy">. When owsSigning is true (default), signing routes through OWS: the key is decrypted only per-sign and wiped immediately after. When false, the key is decrypted at construction and signing uses viem directly.

string

required

Wallet name or UUID in the OWS vault.

string | undefined

required

Vault passphrase. Pass undefined to fall back to the OWS_PASSPHRASE env var.

boolean | undefined

required

Route signing through OWS. Defaults to true when undefined.

Omit<PeaqosClientConfig, 'privateKey'>

required

Client config without privateKey (the wallet provides the signer).

WalletOptions

Optional vault configuration (e.g. custom vaultPath).

Show Example

import { PeaqosClient } from "@peaqos/peaq-os-sdk";

const client = await PeaqosClient.fromWallet("my-machine", "s3cret", true, {
  rpcUrl: "https://peaq.api.onfinality.io/public",
  contracts: {
    identityRegistry: "0x...",
    identityStaking: "0x...",
    eventRegistry: "0x...",
    machineNft: "0x...",
    didRegistry: "0x...",
    batchPrecompile: "0x...",
  },
});

Errors: PeaqosError: wallet not found, passphrase missing, or OWS signing failure. With owsSigning: false a wrong passphrase throws at construction (eager decrypt). With owsSigning: true a wrong passphrase surfaces on the first sign call, and key material is never decrypted at construction.

Wallets (OWS)

Wallet lifecycle helpers (createWallet, importWallet, importWalletMnemonic, listWallets, getWallet, exportWallet, deleteWallet, plus the extractPeaqAddress utility) back the Open Wallet Standard integration: mnemonic-backed encrypted vault, multi-chain accounts (peaq, Base, Ethereum, Solana, Bitcoin, etc.). Lifecycle helpers are available as module-level imports and as static methods on PeaqosClient; the PeaqosClient.fromWallet factory wires a vault wallet directly into a client (OWS-native signing by default). The JS package bundles @open-wallet-standard/core as a regular dependency; no separate peer install is required. The raw-key constructor and fromEnv flow keep working unchanged. Full reference on the Wallets page.

`generateKeypair`

static generateKeypair(): Readonly<{
  address: Address;
  privateKey: `0x${string}`;
}>;

Returns a frozen object with a fresh secp256k1 privateKey and its derived address. No chain interaction. The private key never touches disk.

Show Example

const kp = PeaqosClient.generateKeypair();
console.log(kp.address);    // 0x...
console.log(kp.privateKey); // 0x...

OWS wallet lifecycle

OWS wallet helpers are available as static PeaqosClient methods and standalone functions. They derive multi-chain accounts, keep wallet material in an encrypted OWS vault, and return public WalletInfo metadata.

static createWallet(name: string, passphrase?: string, words?: 12 | 24, options?: WalletOptions): Promise<WalletInfo>;
static importWallet(name: string, privateKey: string, passphrase?: string, chain?: ImportChain, options?: WalletOptions): Promise<WalletInfo>;
static importWalletMnemonic(name: string, mnemonic: string, passphrase?: string, index?: number, options?: WalletOptions): Promise<WalletInfo>;
static listWallets(options?: WalletOptions): Promise<WalletInfo[]>;
static getWallet(nameOrId: string, options?: WalletOptions): Promise<WalletInfo>;
static exportWallet(nameOrId: string, passphrase?: string, options?: WalletOptions): Promise<string>;
static deleteWallet(nameOrId: string, options?: WalletOptions): Promise<void>;
static fromWallet(nameOrId: string, passphrase: string | undefined, owsSigning: boolean | undefined, config: Omit<PeaqosClientConfig, "privateKey">, options?: WalletOptions): Promise<PeaqosClient<"legacy"> | PeaqosClient<"tokenomics20">>;

OWS wallet helpers are bundled with @peaqos/peaq-os-sdk. createWallet, importWallet, importWalletMnemonic, exportWallet, and fromWallet require a passphrase argument or OWS_PASSPHRASE. options.vaultPath can point at a custom vault directory. fromWallet can sign through OWS (owsSigning=true, default) so key material is decrypted only for the signing operation.

object

Frozen object with id, name, createdAt, keyType, peaqAddress, and accounts. Each account has accountId, address, chainId, network, and derivationPath.

Show Example

import {
  PeaqosClient,
  IMPORT_CHAIN_EVM,
  extractPeaqAddress,
} from "@peaqos/peaq-os-sdk";

const wallet = await PeaqosClient.createWallet("robot-001");
console.log(wallet.peaqAddress);

const imported = await PeaqosClient.importWallet(
  "legacy-machine",
  "0xabc...def",
  undefined,
  IMPORT_CHAIN_EVM,
);

const all = await PeaqosClient.listWallets();
const same = await PeaqosClient.getWallet(imported.id);
console.log(all.length, extractPeaqAddress(same.accounts));

const client = await PeaqosClient.fromWallet(imported.id, undefined, true, {
  rpcUrl: "https://quicknode1.peaq.xyz",
  contracts: {
    identityRegistry: "0x...",
    identityStaking: "0x...",
    eventRegistry: "0x...",
    machineNft: "0x...",
    didRegistry: "0x0000000000000000000000000000000000000800",
    batchPrecompile: "0x0000000000000000000000000000000000000805",
  },
});
console.log(client.address);

exportWallet returns mnemonic or private-key material, and fromWallet consumes a vault passphrase. Keep these in local administrative tooling; do not expose them through robot control channels.

Accessors

All accessors are read-only. The private key is held in an ECMAScript #private field: never exposed through the public surface and redacted in JSON.stringify and util.inspect.

Accessor	Type	Description
`mode`	`"legacy" \| "tokenomics20"`	Fixed at construction; narrow on it
`address`	`Address`	Checksummed owner address derived from `privateKey`
`rpcUrl`	`string`	Configured RPC endpoint
`contracts`	`Readonly<ContractAddresses>`	Frozen contract address map
`apiUrl`	`string`	Configured `apiUrl`; not read on a `tokenomics20` client
`operationalLimits`	`Readonly<OperationalLimits>`	Per-tx + rate-limit caps
`publicClient`	`PublicClient` (viem)	Read-only chain client
`walletClient`	`WalletClient` (viem)	Signer-bound chain client

Tokenomics 2.0

Available on a client constructed with tokenomics20: { deploymentId: "peaq-mainnet" | "agung-2026-08-28" }. The seven contract addresses come from the SDK’s snapshot (TOKENOMICS_2_0_DEPLOYMENTS, resolveTokenomics20Deployment), resolved at construction with no network call and verified against InfoDesk.peer(role) before every write. Addresses are never accepted from callers. Every function below is a PeaqosClient method and a package-root export taking the client first. Machine IDs are bigint; a number throws ValidationError. Concepts: Economics 2.0.

`activateMachine`

async activateMachine(params: ActivateMachineParams): Promise<ActivateMachineResult>;

One transaction to MachineStateAndSync.activateMachine: mints the ERC-721 in MachineRegistry (token ID equals machine ID), stores the DID document, bonds the tier in MachineSubscription, and records the home chain. The signer becomes owner and bond payer. The preflight requires MachineSubscription.isEconomicAuthority() (NOT_ECONOMIC_AUTHORITY otherwise) and, once the machine ID is computed, both MachineStateAndSync technical pause flags clear (TECHNICALLY_PAUSED), before any approval. This is the peaq-homed flow; with chain: "solana" the same entry point runs the Solana phases described under Solana (SVM).

interface ActivateMachineParams {
  controller: Address;
  verificationMethods: readonly VerificationMethodInput[]; // { id, methodType, controller, publicKeyMultibase }
  authentication: readonly bigint[];                       // indices into verificationMethods
  serviceEndpoints: readonly ServiceEndpointInput[];       // { id, serviceType, serviceEndpoint }
  machineType: string;
  credentialSubject: Hex;
  manufacturer: Address;                                   // recorded, never verified
  tier: SubscriptionTier;                                  // 0 | 1 | 2
  expectedMachineId?: bigint;
  maxNetPeaqAmount?: bigint;
  confirmations?: number;                                  // default 1
  timeoutMs?: number;                                      // default 120_000
  signal?: AbortSignal;
}

ActivateMachineResult: machineId, owner, controller, tier, bondAmount, voucherCreditApplied, netPeaqAmount, transactionHash, chainId, contract, method, receipt, events, and the re-read subscription state. Amounts come from the receipt. Success requires MachineOnboarded, MachineMinted, and Activated from the right contracts (matched by emitting address) plus a matching post-state read. The write is never retried; a receipt timeout throws RECEIPT_UNAVAILABLE carrying the hash.

`activateMachineWithUsdt`

Same activation, bond settled in USDT through SubscriptionTokenProvisionPool. Not usable on peaq mainnet: the pool has no USDT token configured, so the USDT quote and the write both revert. Requires maxUsdtAmount, taken from previewMachineActivationWithUsdt(...) after applying slippageBps.

`previewMachineActivation`, `previewMachineActivationWithUsdt`

async previewMachineActivation(params: ActivateMachineParams): Promise<ActivationPreview>;

Same validation and reads without signing, approving, or writing. Returns machineId, bondAmount, voucherCredit, netPeaqAmount, balance, approvalRequired. Throws MACHINE_ID_MISMATCH and MAX_NET_PEAQ_EXCEEDED; a low balance is returned, not thrown.

`computeMachineId`

async computeMachineId(machineType: string, credentialSubject: Hex): Promise<bigint>;

Reads

getMachineOwner(machineId: bigint): Promise<Address>;                    // MACHINE_NOT_FOUND vs READ_FAILED kept apart
getMachineActivationState(machineId: bigint): Promise<MachineActivationState>;  // activated when subscription.periodStart !== 0n
getMachineManagementState(machineId: bigint): Promise<MachineManagementState>;
getMachineSubscription(machineId: bigint): Promise<MachineSubscription>;
getMachineAvailability(machineId: bigint): Promise<MachineAvailability>;
getMachineRelocationStatus({ machineId, destinationClient }): Promise<MachineRelocationStatus>;  // status: pending | completed | cancelled | conflicting; a pending result carries stage: unknown | notStarted | initiated | arrived

On an SVM-enabled client getMachineOwner, getMachineAvailability and getMachineManagementState return a tagged result (chain: "peaq" | "solana"), getMachineActivationState returns the Solana-aware state, and all four answer for a machine homed on Solana: see Solana (SVM).

Lifecycle and subscription

suspendMachine(machineId: bigint, options?): Promise<...>;
resumeMachine(machineId: bigint, options?): Promise<...>;

previewExistingMachineActivation({ machineId, tier, payment: "peaq" } | { machineId, tier, payment: "usdt", slippageBps });
activateExistingMachine({ machineId, tier, payment: "peaq", maxNetPeaqAmount } | { ..., payment: "usdt", maxUsdtAmount });

previewMachineRenewal({ machineId, payment: "peaq" } | { machineId, payment: "usdt", slippageBps });
renewMachine({ machineId, payment: "peaq", maxNetPeaqAmount } | { machineId, payment: "usdt", maxUsdtAmount });  // renews at the stored tier and extends from the stored period end; passing `tier` throws RENEWAL_TIER_UNSUPPORTED on peaq-mainnet and agung-2026-08-28

PEAQ writes require maxNetPeaqAmount, USDT writes maxUsdtAmount; take both from the matching preview. USDT writes are not usable on peaq mainnet (no USDT token configured in the pool). The SDK re-quotes before simulation and never raises an accepted bound. Owner or controller may sign; credits accrue to the owner.

Ownership (ERC-721)

approveMachine(operator: Address, machineId: bigint, options?);
setMachineApprovalForAll(operator: Address, approved: boolean, options?);   // every machine the signer owns, including future ones
transferMachine(from: Address, to: Address, machineId: bigint, options?);
safeTransferMachine(from: Address, to: Address, machineId: bigint, data?: Hex, options?);

Transfer changes the owner and retains the DID controller. Blocked while relocating.

DID updates

setMachineController(machineId: bigint, controller: Address, options?);   // owner only; clearing needs { confirmClearController: true }
setMachineVerificationMethods(machineId: bigint, methods: readonly VerificationMethodInput[], options?);
setMachineAuthentication(machineId: bigint, indices: readonly bigint[], options?);
setMachineServiceEndpoints(machineId: bigint, endpoints: readonly ServiceEndpointInput[], options?);

Setters replace whole arrays. Shrinking verification methods below a live authentication index throws AUTHENTICATION_REWRITE_REQUIRED before submission. Ownership and DID writes accept a synchronous onTransactionSubmitted(submission) callback.

`previewMachineAction`

Side-effect-free preview for ownership and DID actions (not suspend/resume): contract, method, current state, intended effect. Never simulates, signs, or submits.

Machine-ID helpers

import { UINT256_MAX, validateTokenomicsMachineId, parseTokenomicsMachineId, serializeTokenomicsMachineId } from "@peaqos/peaq-os-sdk";

Canonical decimal strings at every JSON, URL, and log boundary. No Number(bigint), no leading zeros except "0".

Disabled in Tokenomics mode

Call	Throws
`registerMachine`, `mintNft`, `tokenIdOf`	`TokenomicsUnsupportedError` `LEGACY_REGISTRATION_UNSUPPORTED`
`registerFor`	`TokenomicsUnsupportedError` `SPONSORED_ACTIVATION_UNSUPPORTED` (no replacement)
`bridgeNft`	`TokenomicsUnsupportedError` `MACHINE_RELOCATION_UNAVAILABLE`
`writeMachineDIDAttributes`, `writeProxyDIDAttributes`	`TokenomicsIntegrationUnavailableError` (`"legacy DID helpers"`)
`client.orchestration` calls that bind a machine identity (pairings, machines, market orders, purchases, runtime endpoints, market search, …)	`TokenomicsIntegrationUnavailableError` (`"orchestration identity binding"`)

Still available in Tokenomics mode: submitEvent and batchSubmitEvents (Events); queryMcr, queryMachine, queryOperatorMachines (Queries); orchestration health, skills, policies, market-service reads, audit reads, payment rails, delivery transports; heartbeat; provisioning; stream. waitForBridgeArrival is static and not gated; it is marked deprecated.

Solana (SVM)

Machines can be homed on Solana. The SDK keeps one entry point per operation: the same getMachineOwner, activateMachine, transferMachine, submitEvent calls answer for a Solana-homed machine once the client opts in. Opting in changes what a read can answer, not how you call it. Walkthrough: Onboard a machine on Solana.

Opting in

const client = new PeaqosClient<"tokenomics20", "svmEnabled">({
  rpcUrl, privateKey, contracts, // ContractAddresses with the six legacy addresses
  tokenomics20: { deploymentId: "peaq-mainnet" },
  svm: { deploymentId: "solana-mainnet", rpcUrl: process.env.PEAQOS_SVM_RPC_URL! },
});

Both type parameters are explicit; TypeScript cannot infer them from the config and the type refuses a mismatch. @solana/web3.js and @coral-xyz/anchor are optional peer dependencies, loaded only when a machine turns out to live on Solana; an EVM-only client never imports them, and a Solana-homed machine met without them fails with SVM_PACKAGE_MISSING naming the package, except that a read which first has to resolve the home chain (getMachineOwner, getMachineAvailability, getMachineManagementState) throws HOME_CHAIN_UNRESOLVED with homeChainReason: "missing_dependency". The public Solana deployment record is solana-mainnet (SVM_DEPLOYMENTS, resolveSvmDeployment; the constant also carries an internal test record): cluster mainnet-beta, protocol chain ID 5 (SOLANA_PROTOCOL_CHAIN_ID), LayerZero EID 30168, the program IDs from the contracts page and the peering between peaq’s MachineBridgeAdapter and the Solana store PDA. Before any account is decoded the SDK checks the endpoint’s genesis hash against the record, that the programs the read needs are executable, and that the record’s peering is consistent (the Solana peer peaq stores is the adapter’s store account, the peaq peer is a 20-byte address); onboarding reads the live peer account before signing. Program IDs come from the record, never from an IDL’s address field.

Reads

getMachineOwner and getMachineAvailability return a tagged result:

const owner = await client.getMachineOwner(machineId);
if (owner.chain === "peaq") owner.owner;           // Address
else { owner.owner; owner.evmOperator; owner.did; } // base58 key; the machine's peaq operator, or undefined; did:peaq:<decimal>

A Solana owner is a 32-byte key with no peaq account; evmOperator is the peaq operator the bond is booked under (the address the owner wallet was registered from). The subscription itself stays on peaq for every home: for a Solana-homed machine read it from getMachineManagementState(machineId).subscription; getMachineSubscription needs a peaq ERC-721 and throws MACHINE_NOT_FOUND for a Solana-homed machine. A location the SDK cannot establish throws TokenomicsActivationError HOME_CHAIN_UNRESOLVED with homeChainState (reserved, in_flight, unknown, conflict, unavailable) and homeChainReason (missing_configuration, missing_dependency, missing_capability, conflicting_evidence). A missing dependency or an unreachable RPC is never reported as a missing machine. Solana reads wait out a rate limit (HTTP 429) and a server behind the slot a read needs (JSON-RPC -32016) and retry, up to five attempts, never for a send; a server that stays behind is named in the final READ_FAILED.

Onboarding

Terminal-first (SDK 0.11.2 and newer), the same flow as the Python SDK in camelCase with bigint amounts: the Solana owner pays the bond on Solana, in PEAQ or USDC, through the subscription terminal, and peaq books it. The link push back to peaq is delivered by peaq’s Trust Validator node (the node), with no messaging fee. Both rails run on production. The phases, in order:

Phase	Entry point	Signer
`registration`	`registerSolanaOperator({ solanaWallet })`: `OperatorRegistry.registerOperatorAddress(5, wallet)`, once per Solana wallet, then the node mirrors the binding to Solana	the client’s peaq signer, which becomes the machine’s operator
`request`, `finalise`, `cancel_request`	`activateMachine({ chain: "solana", phase, identity, getSigner, ... })`	the owner’s OWS Solana signer
`credit`, `bond`	`activateMachine({ chain: "solana", phase, identity, waitSeconds })`: waits for the Trust Validator node (180 s and 360 s budgets)	nobody
`native_onboarding`, `linkage`	`activateMachine({ chain: "solana", phase, inputs, plan, records, getSigner, ... })`: the mint against the bonded request, then the link push	the owner’s OWS Solana signer

The example is the script that onboarded the proven JavaScript machines, given in full on the guide’s JavaScript tab (the collapsed block under its run command, to copy): one loop over getMachineActivationState that does whatever nextStep names until complete, journaling every write. Its two write calls, a terminal stage and a native one:

const result = await client.activateMachine({
  chain: "solana",
  phase,
  identity,
  getSigner,
  records: terminalRows(rows),
  ...terminalCaps,
  computeUnitPriceMicroLamports: PRICE,
  waitSeconds:
    Math.min(budgetLeft(), phase === "credit" ? 180 : phase === "bond" ? 360 : 0) || undefined,
  onTransactionSubmitted: persist,
  onWaitEvent: (e) => log(`      ${e.message ?? e.kind}`),
  ...extra,
});

result = await client.activateMachine({
  chain: "solana",
  phase,
  inputs,
  plan,
  records: rows,
  ...budget,
  getSigner,
  onTransactionSubmitted: persist,
  // No maxLinkPushFeeLamports: the route is the Trust Validator node's (no fee). On a LayerZero
  // route the SDK refuses before signing and names the cap to pass.
});

Since 0.11.2 the mint’s computeUnitLimit is the plan’s suggestion, plan.native.suggestedComputeUnitLimit: preview again with it and submit with it (before, scripts passed 600,000; see The mint below). getSigner resolves the owner’s signer once: getSolanaOnboardingSignerRequirements(inputs, plan, "native_onboarding", { candidateAddress }), then solanaSignerFromWallet(name, passphrase, true, undefined, required.chainId) and validateSolanaOnboardingSigner(inputs, plan, "native_onboarding", signer). The client needs both halves configured: tokenomics20: { deploymentId: "peaq-mainnet" } and svm: { deploymentId: "solana-mainnet", rpcUrl, commitment: "finalized" }; nothing on peaq is signed after the registration, so a client that only onboards can carry a throwaway privateKey.

Registration. registerSolanaOperator spends peaq gas only (about 0.01 PEAQ; 98,688 and 105,432 gas measured) and waits for the node to mirror the binding. A wallet already bound to the signer is action: "reconciled", and nothing is sent. A wallet bound to another address is refused OPERATOR_BOUND_ELSEWHERE. getSolanaOperatorRegistration(wallet, { peaqOperator? }) reads the state keyless: unbound, bound, bound_elsewhere or mirroring. Confirmation is the OperatorAddressBound event in a finalized block, never receipt status.
The quote. quoteSolanaActivation(identity, { tier, payIn, wallet }) is keyless and refuses in the program’s order (OPERATOR_NOT_REGISTERED, MACHINE_ALREADY_ACTIVE, REQUEST_ALREADY_OPEN, INSUFFICIENT_BALANCE …). It returns bond, maxIn (the suggested escrow, the bond plus the slippage cushion; on USDC the swap’s estimate plus the cushion), walletBalance and priceAgeSecs.
The priority price. computeUnitPriceMicroLamports defaults to 0n on the terminal phases; the plan takes it in previewMachineActivation’s budget. Pass 10_000n, as the script does: a write without priority can be dropped by Solana’s public endpoint under load. Since 0.11.2 the SDK re-sends a write that was lost on its way. While the write’s receipt wait sees the signature unknown and the blockhash still valid, the SDK sends the same signed bytes again every 2 s, at most 40 times. The same bytes carry the same signature, so the cluster processes the write at most once and nothing can be spent twice. The bytes stay in this process’s memory: a rerun in a new process re-sends nothing and reconciles the journal row. A re-send’s errors are ignored; the receipt decides. A mint that never lands at all is still proven dead by the recovery (SDK 0.11.1, mayResubmit) and minted again. At 10,000, with the mint’s limit sized from its simulation, the whole onboarding pays about 4,900 lamports of priority fees on PEAQ and about 7,900 on USDC.
request. Escrows maxInAmount in the pay-in token and freezes the bond; on PEAQ the escrow must cover the bond (ESCROW_BELOW_BOND). The rents (2,169,160 lamports for the request, 1,488,440 for its escrow account and, on the machine’s first request, 1,071,880 for its SubscriptionTerminal) count against maxNativeRentLamports. A request the node does not credit within its hour ends status: "exited" with exit: "REQUEST_EXPIRED". The node cancels that request once it can, returning the escrow and the request’s rents, or the owner cancels it with cancel_request. A rerun after the request was cancelled (by the owner, or by the node once it expired) or refunded opens a new request at the next nonce (0.11.2): the request phase reads the machine’s terminal record first, and a request that is gone, with its nonce no longer open and no live subscription, is spent, not taken for a live one. A request closed after the mint stays done. On a request already cancelled or refunded, cancel_request run alone is refused with REQUEST_CLOSED; a cancel this journal recorded still reconciles complete.
finalise. The request decides the path: in PEAQ to the terminal’s vault, or on USDC a swap that buys exactly the bond through the provision pool, against the record’s finalise lookup table. The swap is quoted by simulating the exact instruction; the cap sent is that cost plus the slippage, never above the escrow. result.settlement (SwapSettlementQuote: simulatedInAmount, maxInAmount, escrowAmount, slippageBps, lookupTable, lockInTable) says how a USDC settlement was priced. previewSolanaSettlement runs the same preparation keyless; verifySolanaFinaliseTable checks the table alone. A request already cancelled or refunded is refused REQUEST_CLOSED before signing (0.11.2), by finalise and by previewSolanaSettlement. After a finalise there is no cancel: if peaq refuses the bond, the refund comes back in PEAQ on both rails (exit: "ACTIVATION_REFUNDED", with result.refund).
Results. Each terminal call returns status complete, pending (unresolved, advice) or exited (a named exit, with the way out in advice). A signed send whose outcome is unknown throws TokenomicsPendingTransactionError (TRANSACTION_PENDING); its row is journaled, and a rerun reconciles it. Each confirmation carries sendCount ({ sends, resendErrors }, 0.11.2): the sends this process made for the write; it is undefined for a row this process did not send.
REQUEST_CLOSED (0.11.2). A phase run alone on a request that was cancelled or refunded is refused with this code before anything is signed: the credit and bond waits, finalise and previewSolanaSettlement, and cancel_request. It replaces REQUEST_NOT_COMMITTED, STATE_MISMATCH or REQUEST_NOT_CANCELLABLE in that situation. Nothing is left to wait for, settle or cancel; the request phase opens a new request at the next nonce. A refund still ends the bond wait as ACTIVATION_REFUNDED.
The mint. native_onboarding mints against the bonded request with inputs (owner, controller, manufacturer, machine type, credential subject, the DID lists, the two native ceilings, optional evmOperator assertion) and the plan from previewMachineActivation({ chain: "solana", inputs, computeUnitLimit, computeUnitPriceMicroLamports }). plan.native.suggestedComputeUnitLimit (0.11.2) is the value to pass as computeUnitLimit: the plan’s simulated units × 1.3, rounded up to the next 1,000, at least 50,000 and at most the cluster maximum. Before, scripts passed 600,000; on production the mint used 99,009 of them on 2026-10-08. A mint whose receipt failed with ComputationalBudgetExceeded (reason compute_budget_exceeded), with the Machine and MachineState accounts absent, is minted again by the rerun, like a mint that never landed: the reconciliation marks it failedWithoutEffect, and noEffect covers both cases. Every other failed mint stays failed.
The link push. The SDK reads the route from the chain before every push. quoteSolanaLinkPush(machineId, { payer }) is keyless: transport is trust_validator (production: nativeFeeLamports 0n, computeUnitLimit 120,000, pushAccountRentLamports 1,005,840) or layerzero; status already_pushed means nothing is left to send. On the node’s route maxLinkPushFeeLamports is not needed; on a LayerZero route a push without it throws ValidationError on that field before signing. Refused before signing: TV_OUTBOX_MISSING, TV_INBOUND_REFUSED, SVM_FEE_EXCEEDED (a fee or the push account’s rent over its ceiling), and INSUFFICIENT_BALANCE when the owner cannot pay the push and keep its own rent-exempt minimum (650,240 lamports for a plain wallet). The confirmation carries transport, tvNonce and sequence.
Complete. When peaq’s MachineBridgeAdapter.lastAppliedMirrorPushSeq for the machine reaches the push’s sequence: getMachineActivationState(machineId, { chain: "solana", inputs, records }) reads nextStep.phase === "complete". tvRelays lists the pushes that went over the node (signature, dstEid, nonce, applied); messages lists LayerZero messages and is empty on the node’s route.
Journal and recovery. The three Solana rows are handed to onTransactionSubmitted before broadcast, the registration row right after its broadcast; a write that stays unconfirmed throws TokenomicsPendingTransactionError (TRANSACTION_PENDING, the row on .submitted) and is reconciled on the next run. The process that signed it may re-send the same signed bytes while the write can still land (0.11.2); a rerun in a new process re-sends nothing. Store each row as one serializeSolanaOnboardingAttempt(row, client.tokenomics20) line and read them back with decodeSolanaOnboardingAttempt. Pass every row to status reads and the native phases. After an earlier request was cancelled, refunded or closed (observations.terminal.requestState), the request phase reads the machine’s terminal record first and opens a new request at the next nonce (0.11.2); before 0.11.2 it took the old row for a live request. The script’s requestRows also leaves that request’s rows (nonce at or below observations.terminal.terminal.lastNonce) out of the new call’s records.
What ran. getSolanaOnboardingHistory(machineId, { timeoutSeconds }) rebuilds the onboarding from the chains alone, keyless: rows (step, actor owner / operator / node / layerzero / other, slot or block, cost to its payer, the owner’s own change whoever paid in ownerLamportsDelta and ownerTokenDeltas, explorer links) and totals per payer (the owner’s is its net change, refunds from others’ transactions included). A cancel the node sends reads actor node. Sources it could not read are named in unread; a rerun reads them. Right after a run the public endpoints are busy: the script allows 600 s. confirmSolanaOnboardingReceipts(records) reads back the registration’s and the terminal writes’ receipts for a cost report after a resume.
Migrating from 0.10.x. The reservation-first API (SvmOnboardingInput with funding, the reservation and subscription phases, serializeSvmOnboardingProgress) is gone; onboard with the phases above.

Management

Requests carrying chain: "solana" take the native path through the entry points they already have; the client never reroutes an EVM call because Solana is configured.

Operation	Entry point	Authorized by
Read state, availability, preview	`getMachineManagementState`, `getMachineAvailability`, `previewMachineAction`	nobody
Transfer, set or clear controller	`transferMachine`, `setMachineController`	native owner
Link the peaq subscription operator	`setMachineEvmOperator` (Solana only)	native owner
Replace DID lists, suspend, resume	`setMachineVerificationMethods`, `setMachineAuthentication`, `setMachineServiceEndpoints`, `suspendMachine`, `resumeMachine`	owner or controller
Reconcile a submitted transaction	`reconcileMachineManagementTransaction`	nobody

A write is preview, decide, write: previewMachineAction({ chain: "solana", action, machineId, signer, ..., accepted: { maxFeeLamports, maxRentLamports } }), then

transferMachine({ chain: "solana", preview, request, rpc, native: { computeUnitLimit, computeUnitPriceMicroLamports }, commitment, getSigner })

. The write-capable rpc is yours to supply; the client’s Solana connection is read-only. approveMachine and safeTransferMachine have no Solana semantics: once the home-chain reads resolve the machine to Solana they throw TokenomicsUnsupportedError SVM_APPROVAL_UNSUPPORTED / SVM_SAFE_TRANSFER_UNSUPPORTED; setMachineApprovalForAll carries no machine ID and throws SVM_APPROVAL_FOR_ALL_UNSUPPORTED only when called with chain: "solana" (the Python code for the first two is SOLANA_OPERATION_UNSUPPORTED; Python’s set_machine_approval_for_all keeps its EVM behaviour). Results report confirmed, unconfirmed, blocked or failed; unconfirmed is not a failure, reconcile it. setMachineEvmOperator reports sync separately (pending until peaq’s lastAppliedMirrorPushSeq for source chain 5 equals that exact source sequence and the latest source snapshot still describes the current state; a synchronized result carries reusedExistingPush: true, the SDK never sends the message itself); matching operators on both chains prove nothing on their own. DID setters resize the account, so rent moves to or from whoever signed; the preview reports it separately from fees.

Events

submitEvent and batchSubmitEvents write to the Solana EventRegistry program for a Solana-homed machine. They need the SVM-enabled client and two options: getSigner, resolving an OwsSolanaSigner (PeaqosClient.solanaSignerFromWallet(name, passphrase)), and commitment ("confirmed" or "finalized"). Params are SubmitSvmEventParams: machineId (bigint), eventType (0 revenue, 1 activity), value and timestamp (bigint or safe integer), rawData, trustLevel, sourceChainId, sourceTxHash, metadata, currency (smart default for a single event, required per event in a batch). A batch is one Solana transaction; every machine in it must be homed on the same deployment. The timestamp must not exceed the observed cluster time (STATE_MISMATCH otherwise). The first event for a machine also pays rent for its MachineEventLog account; the fee payer is the signer. The result (SvmEventSubmissionResult) carries executionChain: "solana", machineId (bigint), signature, submissionId, slot, confirmationLevel, dataHash, eventIndex and optional computeUnits. onTransactionSubmitted receives a payload-free NativeEventSubmissionAttempt (signature, lastValidBlockHeight, submission ID) before the broadcast. reconcileSvmEventSubmission (complete, failed, expired, unresolved) and rebroadcastSvmEventTransaction are exported, but in 0.11.2 the first needs the packaged IDL, which the package does not export, and the second needs signed bytes the SDK never returns; check an uncertain attempt’s signature on the cluster instead. Replace only an expired attempt via options.replace. An uncertain wait throws TRANSACTION_PENDING (default timeoutMs 120 s), not TokenomicsPendingTransactionError. Other options: timeoutMs, signal, computeUnitPriceMicroLamports, computeUnitLimit, acceptedCostBounds (maxFeeLamports, maxRentLamports; refused before signing above them). There is no event preview in JS. Walkthrough: Submit events: machines homed on Solana. A confirmed event is not an MCR update; the 2.0 MCR indexes Solana events asynchronously.

MCR API compatibility

The query and monetization clients follow the 2.0 MCR server’s contract for Solana-homed machines. revenueTrend is RevenueTrend | null and averageRevenuePerEvent is number | null (null means not computable, never substitute "stable" or 0; totalRevenue stays non-null), a null or fractional mcr_score throws BAD_RESPONSE, and MonetizationState.signer is string | null because a Solana owner’s key is base58. Optional fields, present only for a machine homed away from peaq: homeChain (protocol chain ordinal, Solana is 5; compare against SOLANA_PROTOCOL_CHAIN_ID, never against 3338 or 30168), ratingUnavailable (any non-empty value means the score is a floor), and on the profile owner (home-chain address format), controller, machine_type, relocating. operator stays an EVM address DID on every home. HTTP, transport and non-JSON failures throw McrApiError with code (see MCR API error codes), serverCode, httpStatus, homeProtocolChainId, retryable (a classification; the transport never retries); response shape and correlation failures throw RuntimeError with code BAD_RESPONSE. Monetization opt-in signed by a Solana owner is implemented (five-line message with home_chain: 5, plain Ed25519 signMessage, body with signer_pubkey). When solanaSigner is set, the SDK reads the machine’s home chain first (a compatibility GET and a profile GET) and refuses a Solana-homed write with MonetizationValidationError SOLANA_MONETIZATION_UNVERIFIED before signing. Without a Solana signer the SDK does not check the home chain and sends the EIP-191 write.

Registration

Tokenomics 1.0 path. registerMachine and registerFor address IdentityRegistry (1 PEAQ native bond, separate Machine NFT). Both are marked deprecated and throw TokenomicsUnsupportedError on a client constructed with tokenomics20. New machines use activateMachine.

`registerMachine`

Registers the caller’s own address as a machine. Reads minBond from the IdentityRegistry contract (currently 1 PEAQ) and sends that value with the transaction.

async registerMachine(): Promise<number>;

number

The newly allocated machine ID, decoded from the Registered event in the transaction receipt.

Show Example

const client = PeaqosClient.fromEnv();
const machineId = await client.registerMachine();
console.log(machineId);

Show Errors

RuntimeError: chain revert (AlreadyRegistered, IncorrectBondAmount, or any other custom error), receipt missing the Registered log, or decoded machineId out of safe-integer range.

See errors.

`registerFor`

Registers a machine on behalf of another address. The caller becomes the proxy operator and supplies the current minBond (read from the IdentityRegistry contract) as msg.value.

async registerFor(machineAddress: `0x${string}`): Promise<number>;

0x${string}

required

Machine EOA. The client’s signing address becomes the operator and pays the bond.

number

The newly allocated machine ID for the proxied machine.

Show Example

const client = PeaqosClient.fromEnv();
const { address: machineAddress } = PeaqosClient.generateKeypair();
const machineId = await client.registerFor(machineAddress);

Show Errors

ValidationError: machineAddress is not a valid 0x address.
RuntimeError: chain revert (AlreadyRegistered, InvalidMachineAddress for zero address, IncorrectBondAmount, or any other custom error), receipt missing the Registered log, or decoded machineId out of safe-integer range.

The zero address is allowed through to the chain so the user-facing message comes from the InvalidMachineAddress revert mapping (contains "zero address").

Gas Station

Setup 2FA

Call setupFaucet2FA to enroll the owner.

Confirm 2FA

Call confirmFaucet2FA with a TOTP from the authenticator.

Fund

Call fundFromGasStation to send gas to a machine wallet.

`setupFaucet2FA`

Enrolls an owner address for 2FA with the Gas Station. Returns a QR code URL (expires after ~2 minutes).

async setupFaucet2FA(
  ownerAddress: string,
  faucetBaseUrl: string,
  format?: FaucetQrFormat,
): Promise<FaucetSetupResponse>;

string

required

Owner to enroll (SS58 or hex).

string

required

Gas Station base URL.

'svg' | 'png'

QR format. Defaults to "svg".

object

Show properties

string

required

The enrolled owner address.

string

required

OTP auth URI for authenticator apps.

string

required

QR code image URL. Expires after ~2 minutes. Render immediately, never persist.

Show Example

const setup = await client.setupFaucet2FA(
  client.address,
  "https://depinstation.peaq.xyz",
);
console.log(setup.otpauthUri);
console.log(setup.qrImageUrl);

Errors: ValidationError on empty args. RuntimeError for INVALID_OWNER_ADDRESS, INVALID_PAYLOAD, QR_GENERATION_FAILED, unexpected envelope, or HTTP failure. See errors.

`confirmFaucet2FA`

Confirms 2FA enrollment with a fresh TOTP code.

async confirmFaucet2FA(
  ownerAddress: string,
  faucetBaseUrl: string,
  twoFactorCode: string,
): Promise<void>;

string

required

Owner address being confirmed.

string

required

Gas Station base URL.

string

required

Fresh 6-digit TOTP.

Returns void on successful activation.

Show Example

await client.confirmFaucet2FA(
  client.address,
  "https://depinstation.peaq.xyz",
  "123456",
);

Errors: ValidationError on any empty argument. RuntimeError for INVALID_2FA, 2FA_NOT_CONFIGURED, 2FA_LOCKED, unexpected envelope, or transport failure.

`fundFromGasStation`

Sends gas tokens to a machine wallet. Returns a discriminated union on status.

async fundFromGasStation(
  params: FundFromGasStationParams,
  faucetBaseUrl: string,
): Promise<FaucetFundResponse>;

string

required

2FA-enrolled owner (SS58 or hex).

string

required

Machine EOA to fund.

string

required

Faucet-configured chain identifier (e.g., "peaq").

string

required

Current TOTP.

string

UUID idempotency key. Auto-generated if omitted.

FaucetFundSuccessResponse | FaucetFundSkippedResponse

Show Success response

'success'

required

string

required

Transaction hash.

string

required

Decimal wei. Never a JS number.

string

required

Show Skipped response (sufficient balance)

'skipped'

required

string

required

string

required

string

required

The JS SDK echoes requestId back in both success and skipped responses. The Python SDK does not include request_id in the response at all: it is a request-side idempotency key only. Do not write code that reads requestId from the response and expects it to work in both SDKs.

Show Example

const result = await client.fundFromGasStation(
  {
    ownerAddress: client.address,
    targetWalletAddress: machineAddress,
    chainId: "peaq",
    twoFactorCode: "123456",
  },
  "https://depinstation.peaq.xyz",
);

if (result.status === "success") {
  console.log("tx:", result.txHash, "amount:", result.fundedAmount);
} else {
  console.log("already funded; balance:", result.currentBalance);
}

Show Errors

ValidationError: missing/empty required fields, requestId not a UUID, or faucetBaseUrl empty.
RuntimeError: any documented faucet code: INVALID_2FA, 2FA_NOT_CONFIGURED, 2FA_NOT_ACTIVE, 2FA_LOCKED, DUPLICATE_REQUEST, REQUEST_ALREADY_PROCESSED, RATE_LIMITED, CAP_EXCEEDED_OWNER, CAP_EXCEEDED_WALLET, TRANSFER_FAILED.

See errors for the full code → cause → retry table.

NFT & DID

Tokenomics 1.0 path. In Tokenomics mode mintNft and tokenIdOf throw TokenomicsUnsupportedError (minting happens inside activateMachine; the machine ID is the token ID) and the DID writers throw TokenomicsIntegrationUnavailableError. Use the DID setters instead.

Machine NFT minting, token-ID lookup, and the two canonical DID attribute writers. The DID writes batch six (machine) or two (proxy) attributes into a single atomic batchAll transaction via the peaq Batch precompile.

`mintNft`

Mints a Machine NFT on the MachineNFT contract for a registered, bonded machine. Returns the transaction hash.

async mintNft(
  machineId: number,
  recipient: `0x${string}`,
): Promise<Hex>;

number

required

Registered machine ID. Must be a positive integer.

0x${string}

required

Address that will own the minted NFT.

Show Example

const txHash = await client.mintNft(machineId, client.address);

Show Errors

ValidationError: machineId not positive, recipient not a valid 0x address, or client.contracts.machineNft not a valid address.
RuntimeError: chain revert (MachineNotBonded, AlreadyMinted, NotMachineOwner, MachineNotFound, InvalidAddress) or transaction failure.

See errors.

`tokenIdOf`

Reads the NFT token ID assigned to a registered machine via a view call.

async tokenIdOf(machineId: number): Promise<number>;

number

required

Registered machine ID. Must be a positive integer.

number

The NFT token ID, or 0 if no NFT has been minted for this machine.

Show Example

const tokenId = await client.tokenIdOf(machineId);
if (tokenId === 0) {
  console.log("No NFT minted yet");
}

Show Errors

ValidationError: machineId not a positive integer, or client.contracts.machineNft not a valid address.
RuntimeError: contract returns a token ID beyond Number.MAX_SAFE_INTEGER.

Both SDKs return 0 when no NFT has been minted for the machine: the contract returns 0 instead of reverting.

`writeMachineDIDAttributes`

Atomically writes the six canonical Machine DID attributes (machineId, nftTokenId, operator, documentation_url, data_api, data_visibility) to the caller’s DID via a single batched transaction.

async writeMachineDIDAttributes(
  params: WriteMachineDIDParams,
): Promise<Hex>;

number

required

Registered machine ID.

number

required

NFT token ID assigned to the machine.

string

required

Operator DID reference. May be an empty string. ASCII, ≤ 2560 bytes.

string

required

Non-empty ASCII URL, ≤ 2560 bytes.

string

required

Non-empty ASCII URL for the machine’s data API, ≤ 2560 bytes.

'public' | 'private' | 'onchain'

required

Visibility setting.

Show Example

const txHash = await client.writeMachineDIDAttributes({
  machineId: 42,
  nftTokenId: 1,
  operatorDid: "",
  documentationUrl: "https://docs.example.com",
  dataApi: "https://api.example.com",
  dataVisibility: "public",
});

`writeProxyDIDAttributes`

Atomically writes the two canonical Proxy DID attributes (machineId, machines) to the caller’s DID.

async writeProxyDIDAttributes(
  params: WriteProxyDIDParams,
): Promise<Hex>;

number

required

The proxy operator’s registered machine ID.

readonly number[]

required

Non-empty list of positive machine IDs managed by this proxy. The JSON-encoded array must be ≤ 2560 bytes.

Show Example

const txHash = await client.writeProxyDIDAttributes({
  proxyMachineId: 10,
  machineIds: [42, 43, 44],
});

`readAttribute`

Reads a single DID attribute directly from the peaq DID precompile.

async function readAttribute(
  client: PeaqosClient,
  did: Address,
  name: string,
): Promise<DIDAttributeResult>;

Address

required

The DID account address whose attribute is being read (typically a machine address, but any DID-bearing EOA works).

string

required

Attribute key, e.g. "machineId", "data_visibility", "machines".

object

{ name: string; value: string; validity: number; created: bigint }. validity is the absolute block number the attribute is valid until, not the validFor duration.

readAttribute in 0.10.0 throws TypeError: hex_.replace is not a function on every call: it passes the attribute name as bytes viem cannot encode. Read the precompile with viem directly instead. A missing attribute reverts with Cannot find the item (viem ContractFunctionExecutionError).

import { createPublicClient, http, parseAbi, toHex, hexToString } from "viem";

const didAbi = parseAbi([
  "function readAttribute(address didAccount, bytes name) view returns ((bytes name, bytes value, uint32 validity, uint256 created))",
]);
const publicClient = createPublicClient({ transport: http("https://quicknode1.peaq.xyz") });

const attr = await publicClient.readContract({
  address: "0x0000000000000000000000000000000000000800",
  abi: didAbi,
  functionName: "readAttribute",
  args: [machineAddress, toHex("machineId")],
});
console.log(hexToString(attr.value), attr.validity, attr.created);

`encodeAddAttribute`

Encodes ABI call data for the DID precompile’s addAttribute(didAccount, name, value, validFor) function. Useful when constructing smart-account executeBatch calls that touch the DID precompile alongside other contracts. writeMachineDIDAttributes and writeProxyDIDAttributes use this helper internally; reach for it directly only when composing custom batch flows.

function encodeAddAttribute(
  didAccount: Address,
  name: string,
  value: string,
  validFor: number,
): Hex;

Address

required

Address of the DID account being written. On-chain this must equal msg.sender of the resulting precompile call.

string

required

Attribute name. ASCII only, ≤ 64 bytes.

string

required

Attribute value. ASCII only, ≤ 2560 bytes.

number

required

Validity period in blocks. 0 means no expiry. Must be a non-negative integer in the uint32 range.

string

ABI-encoded call data. Throws ValidationError if any constraint is violated.

Smart accounts

ERC-4337 smart accounts deployed via the MachineAccountFactory. Requires the client to be constructed with a machineAccountFactory address (or the MACHINE_ACCOUNT_FACTORY_ADDRESS env var via fromEnv).

`deploySmartAccount`

Deploys a smart account via MachineAccountFactory.createAccount and returns the deployed address.

async deploySmartAccount(
  params: DeploySmartAccountParams,
): Promise<Address>;

Address

required

EOA that will own the smart account.

Address

required

Machine EOA the account is scoped to.

number

required

Non-negative CREATE2 salt.

Show Example

const address = await client.deploySmartAccount({
  owner: client.address,
  machine: machineAddress,
  salt: 0,
});

`getSmartAccountAddress`

Read-only equivalent: computes the CREATE2 address for the given (owner, machine, salt) without deploying. Returns the same address deploySmartAccount would produce.

async getSmartAccountAddress(
  params: DeploySmartAccountParams,
): Promise<Address>;

Same parameters as deploySmartAccount. No transaction, no gas.

Show Example

const predicted = await client.getSmartAccountAddress({
  owner: client.address,
  machine: machineAddress,
  salt: 0,
});

Bridge

Tokenomics 1.0 path. bridgeNft and waitForBridgeArrival move Tokenomics 1.0 Machine NFTs between peaq and Base. They serve machines already onboarded under Tokenomics 1.0. New machines use activateMachine, and a 2.0 machine is not bridged.

Route: peaq ↔ Base. In Tokenomics mode bridgeNft throws MACHINE_RELOCATION_UNAVAILABLE: Economics 2.0 relocates whole machine records, and relocation is disabled on chain. A 2.0 machine that should live on Solana is created there, not bridged: see Solana (SVM). Portability of the 1.0 NFT: Machine NFT cross-chain portability. LayerZero v2 Machine NFT bridging between peaq and Base. Requires the machineNftAdapter address (or MACHINE_NFT_ADAPTER_ADDRESS) when sending from peaq. The SDK’s source / destination literal union expands as peer contracts deploy on new chains.

`bridgeNft`

Bridges a Machine NFT from source to destination. When source === "base", baseRpcUrl and baseNftAddress are required so the SDK can build a per-call viem client for the Base side. On the peaq→Base path the SDK runs an ERC-721 approval pre-flight: it checks MachineNFT.getApproved(tokenId) and submits a one-shot approve(adapter, tokenId) if the token isn’t already cleared for the adapter. The Base→peaq path uses burn-and-unlock and needs no approval. Either way, callers don’t handle approvals themselves.

async bridgeNft(params: BridgeNftParams): Promise<Hex>;

number

required

Positive NFT id to bridge.

'peaq' | 'base'

required

Origin chain.

'peaq' | 'base'

required

Target chain (must differ from source).

Address

required

Destination-chain recipient.

Hex

Raw LayerZero v2 extraOptions bytes. Defaults to "0x" (the contract’s enforced options).

string

Base RPC URL. Required only when source === "base".

Address

MachineNFTBase address on Base. Required only when source === "base".

Hex

The source-chain transaction hash.

Show Example

const txHash = await client.bridgeNft({
  tokenId: 42,
  source: "peaq",
  destination: "base",
  recipient: "0xabc...",
});

`waitForBridgeArrival`

Static method that polls the destination chain’s MachineNFT.ownerOf(tokenId) every 10 seconds until a non-zero owner returns or the timeout elapses. No PeaqosClient instance required.

static async waitForBridgeArrival(
  params: WaitForBridgeArrivalParams,
): Promise<boolean>;

string

required

Destination-chain RPC endpoint.

Address

required

MachineNFT contract address on the destination.

number

required

The NFT id expected to arrive.

number

Wait budget in seconds. Defaults to 300 (5 min).

AbortSignal

Optional abort signal. When aborted, the poll stops immediately with a RuntimeError code ABORTED.

Show Example

const arrived = await PeaqosClient.waitForBridgeArrival({
  dstRpcUrl: "https://mainnet.base.org",
  dstNftAddress: "0x...",
  tokenId: 42,
  timeout: 120,
});

Events (Qualify)

Both calls write to contracts.eventRegistry, the address in EVENT_REGISTRY_ADDRESS. Point it at the 2.0 EventRegistry 0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e for Economics 2.0 machines and 0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA for Tokenomics 1.0 machines. The two contracts share the submitEvent selector, so a wrong address is not caught before sending: the 1.0 contract reverts with MachineNotFound and the event is not recorded.

machineId on SubmitEventParams and MachineEvent is bigint in every mode (1024n, not 1024). On an SVM-enabled client the same two calls write a Solana-homed machine’s events to the Solana EventRegistry program instead: see Solana (SVM).

`submitEvent`

Submits a single event to EventRegistry. Validates and normalizes the payload, then calls the contract. Returns the transaction hash and the computed dataHash.

async submitEvent(
  params: SubmitEventParams,
): Promise<{ txHash: Hex; dataHash: Hex }>;

Param shape matches validateSubmitEventParams below. value is an ISO 4217 minor-unit integer (cents for USD/HKD, whole units for JPY/KRW/VND). The MCR counts revenue only in its 25 supported currencies, listed on Submit events. currency is required on revenue events (^[A-Z0-9]{3,10}$) and must be "" on activity events; the SDK applies a smart default (revenue → "USD", activity → "") when omitted on submitEvent. batchSubmitEvents is strict: every event must carry currency explicitly.

Show Example

import {
  EVENT_TYPE_REVENUE,
  TRUST_SELF_REPORTED,
  SUPPORTED_CHAIN_IDS,
} from "@peaqos/peaq-os-sdk";

const { txHash, dataHash } = await client.submitEvent({
  machineId: 1024n,
  eventType: EVENT_TYPE_REVENUE,
  value: 12500,                     // $125.00 in cents
  currency: "USD",
  timestamp: Math.floor(Date.now() / 1000),
  rawData: new Uint8Array([1, 2, 3]),
  trustLevel: TRUST_SELF_REPORTED,        // TRUST_ON_CHAIN_VERIFIABLE requires a real sourceTxHash
  sourceChainId: SUPPORTED_CHAIN_IDS.peaq,
  sourceTxHash: null,
  metadata: new Uint8Array([]),
});

Show Errors

ValidationError: any params field fails validation.
ValueCapExceeded / RateLimitExceeded: client-side operational limits hit.
RuntimeError: chain revert or receipt failure.

`batchSubmitEvents`

Submits multiple events atomically through the peaq Batch precompile. All events land in the same transaction: all succeed or all revert.

async batchSubmitEvents(
  events: ReadonlyArray<SubmitEventParams>,
): Promise<Hex[]>;

readonly SubmitEventParams[]

required

Non-empty list of event payloads. Each element is validated individually before submission.

Hex[]

One transaction hash per input event. All hashes are identical (same batch tx).

Show Errors

ValidationError: list is empty, or any event fails validation.
ValueCapExceeded / RateLimitExceeded: operational limits hit for any event in the batch.
RuntimeError: batch revert or transport failure.

`validateSubmitEventParams`

function validateSubmitEventParams(params: SubmitEventParams): void;

bigint

required

Machine ID: bigint in every mode (the MachineRegistry token ID under Economics 2.0, the ID returned by registerMachine / registerFor under Tokenomics 1.0).

0 | 1

required

0 revenue, 1 activity.

number

required

Non-negative ISO 4217 minor-unit integer. Cents for USD/HKD, whole units for JPY/KRW/VND. Activity events: any non-negative integer or 0.

string

Revenue: 3-10 uppercase alphanumeric (e.g. "USD", "HKD", "JPY"). Activity: must be "". Omit to apply the SDK smart default (revenue → "USD", activity → ""); batchSubmitEvents requires it explicitly.

number

required

Unix seconds.

Uint8Array | null

required

Off-chain payload hashed into dataHash.

0 | 1 | 2

required

0 self-reported, 1 on-chain verifiable, 2 hardware-signed.

number

required

Originating chain. Use SUPPORTED_CHAIN_IDS.peaq for local.

Hex | null

required

Cross-chain tx hash when applicable.

Uint8Array

required

Arbitrary bytes stored on-chain alongside the event. Use empty bytes when no metadata is needed.

Returns void. Throws ValidationError on any invariant violation, and a native TypeError when value is not an integer (fractional or wrong type).

Show Example

import {
  validateSubmitEventParams,
  EVENT_TYPE_REVENUE,
  TRUST_ON_CHAIN_VERIFIABLE,
  SUPPORTED_CHAIN_IDS,
} from "@peaqos/peaq-os-sdk";

validateSubmitEventParams({
  machineId: 1024n,
  eventType: EVENT_TYPE_REVENUE,
  value: 1250,                      // $12.50 in cents
  currency: "USD",
  timestamp: Math.floor(Date.now() / 1000),
  rawData: new Uint8Array([1, 2, 3]),
  trustLevel: TRUST_ON_CHAIN_VERIFIABLE,
  sourceChainId: SUPPORTED_CHAIN_IDS.base,
  sourceTxHash: "0x5f8a3c1e9b7d2a4f6e8c0b1d3a5f7e9c2b4d6f8a0c1e3b5d7f9a2c4e6b8d0f1a", // 32-byte tx hash on Base
  metadata: new Uint8Array([]),
});

`computeDataHash`

function computeDataHash(rawData: Uint8Array): Hex;

Uint8Array

required

Off-chain payload bytes to hash.

Returns a keccak256 hash as 0x + 64 hex characters.

Show Example

import { computeDataHash } from "@peaqos/peaq-os-sdk";

const dataHash = computeDataHash(new TextEncoder().encode("revenue: $12.50"));
console.log(dataHash);

`checkOperationalLimits`

function checkOperationalLimits(
  params: { machineId: bigint; value: number },
  limits: OperationalLimits,
  tracker: EventTracker | null,
): void;

{ machineId: bigint; value: number }

required

Machine ID and event value.

OperationalLimits

required

Configured maxValuePerTx, rateLimitMaxEvents, rateLimitWindowSeconds.

EventTracker | null

required

Current rate-tracking state for the machine. Pass null if you are not tracking window state. EventTracker is { machineId: bigint; count: number; windowStart: number }.

Returns void. Throws ValueCapExceeded or RateLimitExceeded on limit violation.

Show Example

import { checkOperationalLimits } from "@peaqos/peaq-os-sdk";

checkOperationalLimits(
  { machineId: 1n, value: 100 },
  client.operationalLimits,
  { machineId: 1n, count: 50, windowStart: Date.now() / 1000 - 1800 },
);

Queries

On a tokenomics20 client all three go to the deployment’s 2.0 MCR server (mcr.peaq.xyz for peaq-mainnet); client.apiUrl is not read. Machine DIDs are did:peaq:<decimal machine id>, operator DIDs stay did:peaq:0x<address>, machineId in results is bigint. A malformed or non-canonical machine_id, or a response about a different machine or operator, throws RuntimeError BAD_RESPONSE. A deployment without a paired MCR (agung-2026-08-28) throws TokenomicsConfigError DEPLOYMENT_UNAVAILABLE before any HTTP. The MCR helpers need a tokenomics20 client. See API reference. Read-only helpers backed by the off-chain MCR API server. Each function validates the DID, issues a single GET, and returns a frozen, shape-checked response. All three accept an optional GetJsonOptions with timeoutMs (default 30 000 ms) and a caller AbortSignal.

`queryMcr`

Fetches the Machine Credit Rating for a machine DID. See GET /mcr/{did}.

async function queryMcr<M extends SdkMode>(
  client: PeaqosClient<M>,
  did: string,
  options?: GetJsonOptions,
): Promise<MCRResponse<M>>;

string

required

Machine DID, did:peaq:<decimal machine id>.

number

Request budget in ms. Defaults to 30 000.

AbortSignal

Caller abort signal. Either signal aborting wins.

object

Frozen object with camelCase fields: did, machineId, mcrScore (number, 0–100), mcr ("AAA" | "AA" | "A" | "BBB" | "BB" | "B" | "NR" | "Provisioned"), mcrDegraded (boolean: true when revenue for a peaq-homed machine was converted at a stale stored FX rate; always false for a Solana-homed machine), bondStatus ("bonded" | "unbonded"), negativeFlag (boolean: true when the machine has been flagged for negative behaviour; consumers should down-rank or alert independently of the numeric score), eventCount, revenueEventCount, activityEventCount, revenueTrend ("up" | "stable" | "down" | "insufficient", or null when not computable, never substitute "stable"), totalRevenue (USD cents, an integer sum of the revenue events worth at least 1,000 USD cents; divide by 100 for display; never null), averageRevenuePerEvent (USD cents, rounded to 2 decimals; null when not computable), lastUpdated (unix seconds or null). On a tokenomics20 client two optional fields appear only for a machine homed away from peaq: homeChain (protocol chain ordinal, Solana is 5; compare with SOLANA_PROTOCOL_CHAIN_ID) and ratingUnavailable (any non-empty value means the score is a floor, not a measurement). Details: MCR API compatibility.

The MCR API returns mcr_score: 0 while a machine is still Provisioned or has rating NR. A null or fractional mcr_score throws BAD_RESPONSE, and ratingUnavailable carries the reason an unscored machine has no rating.

Show Example

import { queryMcr } from "@peaqos/peaq-os-sdk";

// client constructed with tokenomics20
const score = await queryMcr(client, "did:peaq:<decimal machine id>", {
  timeoutMs: 5_000,
});
console.log(`${score.mcrScore} → ${score.mcr}`);

Show Errors

ValidationError: did is not a valid machine DID (did:peaq:<decimal machine id>).
McrApiError (extends RuntimeError): HTTP, transport and non-JSON failures. HTTP 400 is INVALID_REQUEST, 401 and 403 are UNAUTHORIZED, 404 is NOT_FOUND, 409 is MACHINE_HOMED_ELSEWHERE or CONFLICT, 503 is SERVICE_UNAVAILABLE, other 5xx is SERVER_ERROR, other non-2xx is HTTP_ERROR; timeout is TIMEOUT, caller abort ABORTED, transport failure NETWORK_ERROR, a non-JSON body BAD_RESPONSE. The error carries serverCode, httpStatus, homeProtocolChainId, retryable. See errors.
RuntimeError BAD_RESPONSE: a JSON body that fails the response shape check, or describes a different machine or operator.

`queryMachine`

Fetches the full machine profile (NFT Metadata JSON v1.0) for a DID. The SDK strictly validates the response against MachineProfileResponse and throws BAD_RESPONSE for any missing or malformed required field. See GET /machine/{did}.

async function queryMachine<M extends SdkMode>(
  client: PeaqosClient<M>,
  did: string,
  options?: GetJsonOptions,
): Promise<MachineProfileResponse<M>>;

string

required

Machine DID, did:peaq:<decimal machine id>.

GetJsonOptions

Optional timeoutMs (default 30 000) and caller signal.

object

Frozen, strictly-validated machine profile. Top-level fields: schema_version (string) and name (string). The peaqos sub-object always carries machine_id, did, operator, mcr, mcr_score, bond_status, negative_flag, event_count, data_visibility, and documentation_url. The MCR API returns data_visibility: "private" for every machine and no event rows or partner data. data_api appears when the machine’s DID carries a peaq-data-api service endpoint. event_data, partner_data, and partner_data_error stay optional in the type; the MCR API does not return them. On a tokenomics20 client a machine homed away from peaq adds optional owner (home-chain address format, base58 on Solana, never an EVM address), controller, machine_type, relocating, home_chain and rating_unavailable (the profile’s spelling of the pair under MCR API compatibility); operator stays an EVM address DID. The SDK throws BAD_RESPONSE if the server returns anything that fails the schema guard. See GET /machine/{did} for full field semantics.

Show Example

import { queryMachine } from "@peaqos/peaq-os-sdk";

// client constructed with tokenomics20
const profile = await queryMachine(client, "did:peaq:<decimal machine id>");
console.log(profile.name, profile.peaqos.mcr, profile.peaqos.mcr_score);

Show Errors

ValidationError: did is not a valid machine DID (did:peaq:<decimal machine id>).
McrApiError: same HTTP, transport and non-JSON codes as queryMcr.
RuntimeError BAD_RESPONSE: any required field on MachineProfileResponse or its peaqos sub-object is missing or wrong-typed.

`queryOperatorMachines`

Fetches the fleet of machines managed by a proxy operator. Each machine summary carries its DID, machine ID, score, rating tier, and negativeFlag; the response also includes pagination metadata. See GET /operator/{did}/machines.

async function queryOperatorMachines<M extends SdkMode>(
  client: PeaqosClient<M>,
  did: string,
  options?: GetJsonOptions,
): Promise<OperatorMachinesResponse<M>>;

string

required

Operator DID. Must start with did:peaq:0x.

GetJsonOptions

Optional timeoutMs (default 30 000) and caller signal.

object

Frozen object with operatorDid, a frozen machines array, and a pagination object. Each machine entry exposes did, machineId, mcrScore (number, 0–100; a null or fractional score throws BAD_RESPONSE), mcr rating, and negativeFlag (boolean: true when the machine has been flagged for negative behaviour). pagination carries offset, limit, and total (all non-negative integers).

Show Example

import { queryOperatorMachines } from "@peaqos/peaq-os-sdk";

const fleet = await queryOperatorMachines(client, "did:peaq:0xProxyAddress");
for (const m of fleet.machines) {
  console.log(`${m.did} → ${m.mcrScore} (${m.mcr}), negative=${m.negativeFlag}`);
}
console.log(`showing ${fleet.machines.length} of ${fleet.pagination.total}`);

Show Errors

ValidationError: did does not start with did:peaq:0x (operator DIDs are address DIDs).
McrApiError: same HTTP, transport and non-JSON codes as queryMcr.
RuntimeError BAD_RESPONSE: the body or any machines entry is malformed.

Verify

Experimental, beta: the Verify surface lives on its own subpath, @peaqos/peaq-os-sdk/verify, is not exported from the package root (there is no client.verify), and may change without a major version bump. It ships two things: an API read client and three pure chip preflight functions. It has no attester, submission, anchoring or hardware code. Available from @peaqos/peaq-os-sdk 0.10.0.

import {
  VerifyReadClient,
  registryMachineId,
  ChipPreflightContext,
  prepareChipSigningRequest,
  prepareControllerSigningRequest,
  finalizeChipPreflightEvidence,
} from "@peaqos/peaq-os-sdk/verify";

`VerifyReadClient`

Reads one machine’s record from the Verify API. The API is authoritative: the client validates the response shape and returns it frozen; it does not read the registry, an RPC or a DID service, and never compares the result with local preflight evidence.

class VerifyReadClient {
  constructor(options: { apiOrigin: string; fetch: VerifyReadFetch });
  getMachineVerificationAcrossChains(
    machineId: RegistryMachineId,
    options?: { signal?: AbortSignal },
  ): Promise<CrossChainMachineVerification>;
  close(): void;
}

string

required

HTTPS origin of the Verify API, no path, query or credentials: https://mcr.peaq.xyz on peaq mainnet. There is no default.

VerifyReadFetch

required

A fetch-compatible function. Pass the global fetch; construction never calls it.

RegistryMachineId

required

From registryMachineId(123n): a bigint in 1..2^256-1. A DID, an address or 0 throws VerifyValidationError before any request.

object

Frozen. machineId, machineDid (did:peaq:<decimal>), homeChain ({ kind: "evm", chainId } or { kind: "solana", genesisHash }), didController and operator ({ kind, address } in the home chain’s native kind), and verification.kyb.status / verification.chip.status, each "unverified" | "verified" | "expired" | "revoked". No aggregate flag.machineId, machineDid, didController.address and operator.address are typed wrapper objects ({ kind, value }), not plain strings: read .value for the string (machineDid.value, didController.address.value, operator.address.value) and machineId.value for the bigint.

Each call makes exactly one GET /v1/verify/machines/{machineId} with a five-second deadline and a 4096-byte response ceiling, rejects redirects, sends no credentials and keeps no cache. Nothing retries; a 429 is reported, not retried.

Show Example

import { VerifyReadClient, registryMachineId, VerifyIdentityError, VerifyRateLimitError } from "@peaqos/peaq-os-sdk/verify";

const client = new VerifyReadClient({ apiOrigin: process.env.PEAQOS_VERIFY_API_URL ?? "https://mcr.peaq.xyz", fetch });
try {
  const record = await client.getMachineVerificationAcrossChains(registryMachineId(123n));
  console.log(record.homeChain.kind, record.verification.kyb.status, record.verification.chip.status);
} catch (err) {
  if (err instanceof VerifyIdentityError) console.log("unknown machine");           // 404 MACHINE_NOT_FOUND
  else if (err instanceof VerifyRateLimitError) console.log(err.retryAfterSeconds); // 429, hint may be undefined
  else throw err;
} finally {
  client.close();
}

Show Errors

All extend VerifyError (a PeaqosError). Typed fields carry the outcome; messages hold no server text, URLs or identifiers.

VerifyConfigError: bad apiOrigin or options, or the client is closed. Thrown before any request.
VerifyValidationError: bad machineId or request options. Thrown before any request.
VerifyIdentityError with reason: "machine-not-found": 404 MACHINE_NOT_FOUND. The only error that means there is no machine with this ID in the Verify service.
VerifyRateLimitError: 429, statusCode: 429, retryAfterSeconds 1..60 or undefined (v1 sends no Retry-After).
VerifyTransportError: timeout, cancellation, network failure, 500/503 (causeCategory: "unavailable") or another documented HTTP error (causeCategory: "http-status", statusCode set).
VerifyProtocolError: the response is malformed, too large, the wrong media type, an unknown status, or an undocumented code including 401/403. Never treat it as a verification state.

Chip preflight

Three functions that run on the machine and turn a challenge plus the chip’s leaf certificate and two signatures into the canonical peaq.verify.chip-evidence/1 document. They perform no I/O: no chip access, no network, no key, no file. A platform adapter reads the certificate from the OPTIGA Trust M Express object 0xE0E0 and asks key 0xE0F0 to sign; the DID controller’s wallet signs the controller message. Fixed profile infineon-optiga-trust-m-express-ca306/1, trust bundle infineon-optiga-trust-m-express-ca306-roots/1; no other chip, root or curve. EVM controller and chain ID only.

class ChipPreflightContext {
  constructor(input: {
    machineId: bigint;            // 1..2^256-1
    machineDid: string;           // exactly `did:peaq:<machineId>`
    didController: string;        // current effective EVM DID controller
    chainId: bigint;              // 3338n on peaq mainnet
    nonce: Uint8Array;            // 32 bytes from the challenge
    expiresAt: bigint;            // challenge expiry, Unix seconds, at most now + 300
    leafCertificateDer: Uint8Array;
  });
}

function prepareChipSigningRequest(context: ChipPreflightContext): Promise<ChipSigningRequest>;
// request.toChipPrehash(): the 32-byte digest the chip signs with 0xE0F0, without hashing again

function prepareControllerSigningRequest(
  request: ChipSigningRequest,
  nativeChipSignature: Uint8Array,   // Infineon's INTEGER(r) || INTEGER(s) output
): Promise<ControllerSigningRequest>;
// request.toControllerMessageBytes(): the bytes the DID controller signs once as an EIP-191 message

function finalizeChipPreflightEvidence(
  request: ControllerSigningRequest,
  controllerSignature: Hex,          // 65-byte EIP-191 signature
): Promise<ChipPreflightEvidence>;
// evidence.toEvidenceBytes(): canonical RFC 8785 JSON to hand to the onboarding service

ChipPreflightEvidence exposes the fixed identifiers (protocol, profile, evidenceSchema, trustBundle), revocationStatus: "not_evaluated" (the SDK checked no revocation list), evidenceHash, chipRef and toEvidenceBytes(). Every stage rechecks now < expiresAt <= now + 300 and the certificate validity, so run all three right after the challenge. A VerifyFreshnessError needs a new challenge, a new ChipPreflightContext and all three stages again; after any other failure, correct the rejected input and call the failed stage again.

Preflight success means the material is locally valid. It does not consume the challenge, does not submit anything, and does not set chip.status to verified: the onboarding service submits the bytes with POST /v1/verify/chip/evidence, and chip.status reads verified once peaq records the chip attestation. The full flow is in Verify a chip, end to end.

Show Errors

VerifyCryptographicError: the certificate is not a valid CA306 leaf (invalid-certificate), does not chain to the trust bundle (untrusted-path), is not the supported profile (unsupported-profile), or the chip or controller signature does not match this attempt.
VerifyEvidenceError: the evidence document breaks its schema, exceeds its size limit, could not be canonicalized, or a derived value was zero.
VerifyFreshnessError: the challenge is outside its five-minute window. Request a new challenge.

Error classes

See errors for the full hierarchy and the 20-code faucet table.

import {
  PeaqosError,
  RuntimeError,
  ValidationError,
  ValueCapExceeded,
  RateLimitExceeded,
  // Economics 2.0
  TokenomicsConfigError,
  TokenomicsActivationError,
  TokenomicsUnsupportedError,
  TokenomicsIntegrationUnavailableError,
  TokenomicsPendingTransactionError, // TRANSACTION_PENDING; the journaled row on .submitted
  MonetizationCompatibilityError,
  // Solana
  McrApiError,                 // extends RuntimeError; MCR query HTTP failures
  MonetizationValidationError, // local refusals, including SOLANA_MONETIZATION_UNVERIFIED
} from "@peaqos/peaq-os-sdk";

Code tables on errors.

Type exports

All exported types

import type {
  // Client
  PeaqosClientConfig,
  ContractAddresses,
  OperationalLimits,

  // Events
  SubmitEventParams,
  MachineEvent,
  EventType,
  TrustLevel,
  EventTracker,

  // Identity
  DataVisibility,
  BondStatus,

  // API responses
  MCRResponse,
  MachineProfileResponse,
  OperatorMachinesResponse,
  MCRRating,
  RevenueTrend,

  // DID
  WriteMachineDIDParams,
  WriteProxyDIDParams,
  DIDWriteAttribute,
  DIDAttributeResult,

  // Wallet
  WalletInfo,
  AccountInfo,
  KeyType,
  ImportChain,
  WalletOptions,

  // Query options
  GetJsonOptions,

  // Methods
  DeploySmartAccountParams,
  BridgeNftParams,
  WaitForBridgeArrivalParams,

  // Faucet
  FaucetErrorCode,
  FaucetFundResponse,
  FaucetFundSkippedResponse,
  FaucetFundSuccessResponse,
  FaucetQrFormat,
  FaucetSetupResponse,
  FundFromGasStationParams,

  // OWS signing
  OwsSigningErrorCode,

  // Error constructor options
  RuntimeErrorOptions,
  ValidationErrorArgs,

  // Solana, see Solana (SVM)
  SvmActivationReadContext,
  SolanaOnboardingInputs,
  ActivateSolanaTerminalParams,
  ActivateSolanaOnboardingParams,
  SubmitSvmEventParams,
  SvmEventSubmissionResult,
  OwsSolanaSigner,
} from "@peaqos/peaq-os-sdk";

// Enums
import { MachineStatus } from "@peaqos/peaq-os-sdk";

Constants

Tokenomics 2.0 tiers and activation defaults

import {
  SUBSCRIPTION_TIER_ENTRY,             // 0
  SUBSCRIPTION_TIER_BASIC,             // 1
  SUBSCRIPTION_TIER_PRO,               // 2
  SUBSCRIPTION_TIERS,                  // [0, 1, 2], on a peaq home and on a Solana home
  DEFAULT_ACTIVATION_CONFIRMATIONS,    // 1
  DEFAULT_ACTIVATION_TIMEOUT_MS,       // 120_000
  TOKENOMICS_2_0_DEPLOYMENTS,          // deployment records; the public ones are agung-2026-08-28 and peaq-mainnet
  TOKENOMICS_MONETIZATION_API_VERSION, // "tokenomics-2.0-monetization-v1"
  UINT256_MAX,
} from "@peaqos/peaq-os-sdk";

Event types & trust levels

import {
  EVENT_TYPE_REVENUE,        // 0
  EVENT_TYPE_ACTIVITY,       // 1

  TRUST_SELF_REPORTED,       // 0
  TRUST_ON_CHAIN_VERIFIABLE, // 1
  TRUST_HARDWARE_SIGNED,     // 2
} from "@peaqos/peaq-os-sdk";

DID attributes & limits

import {
  DID_ATTR_MACHINE_ID,
  DID_ATTR_NFT_TOKEN_ID,
  DID_ATTR_OPERATOR,
  DID_ATTR_DOCUMENTATION_URL,
  DID_ATTR_DATA_API,
  DID_ATTR_DATA_VISIBILITY,
  DID_ATTR_MACHINES,

  DID_MAX_NAME_BYTES,  // 64
  DID_MAX_VALUE_BYTES, // 2560
} from "@peaqos/peaq-os-sdk";

Chain IDs & LayerZero endpoints

import {
  SUPPORTED_CHAIN_IDS,  // { peaq: 3338, ethereum: 1, base: 8453, polygon: 137, arbitrum: 42161, optimism: 10 }
  LAYER_ZERO_EIDS,      // { peaq: 30302, base: 30184 }
  DEFAULT_API_URL,      // "http://127.0.0.1:8000"
} from "@peaqos/peaq-os-sdk";

Solana and MCR API

import {
  SOLANA_PROTOCOL_CHAIN_ID, // 5: the protocol chain ordinal in MCR home_chain; not an EVM chain ID, not the LayerZero EID 30168
  SVM_DEPLOYMENTS,          // Solana deployment records; the public one is solana-mainnet
  MCR_HTTP_ERROR_CODE,      // NOT_FOUND, SERVICE_UNAVAILABLE, SERVER_ERROR, HTTP_ERROR, BAD_RESPONSE, NETWORK_ERROR, TIMEOUT, ABORTED, INVALID_REQUEST, UNAUTHORIZED, MACHINE_HOMED_ELSEWHERE, CONFLICT
  MONETIZATION_REFUSAL_CODE, // UNSUPPORTED_HOME_CHAIN, SIGNER_INCOMPATIBLE_WITH_HOME, SOLANA_MONETIZATION_UNVERIFIED, SIGNER_NOT_NATIVE_OWNER, AUTHORIZATION_CONTEXT_CHANGED, INVALID_SIGNER_OUTPUT
} from "@peaqos/peaq-os-sdk";

See Solana (SVM) and MCR API compatibility.

Wallet import chains, key types & passphrase env

import {
  IMPORT_CHAIN_EVM,       // "evm" (default)
  IMPORT_CHAIN_SOLANA,    // "solana"
  IMPORT_CHAIN_BITCOIN,   // "bitcoin"
  IMPORT_CHAIN_COSMOS,    // "cosmos"
  IMPORT_CHAIN_TRON,      // "tron"
  IMPORT_CHAIN_TON,       // "ton"
  IMPORT_CHAIN_SUI,       // "sui"
  IMPORT_CHAIN_XRPL,      // "xrpl"
  IMPORT_CHAIN_SPARK,     // "spark"
  IMPORT_CHAIN_FILECOIN,  // "filecoin"

  KEY_TYPE_MNEMONIC,      // "mnemonic"
  KEY_TYPE_PRIVATE_KEY,   // "private_key"

  OWS_PASSPHRASE_ENV,         // "OWS_PASSPHRASE"
  DEFAULT_MCR_HTTP_TIMEOUT_MS, // 30_000
} from "@peaqos/peaq-os-sdk";

IMPORT_CHAIN_* is the union behind the ImportChain type alias used by importWallet. KEY_TYPE_* matches the KeyType field on WalletInfo.

OWS signing error codes

import {
  OWS_ERROR_WALLET_NOT_FOUND,     // "WALLET_NOT_FOUND"
  OWS_ERROR_INVALID_PASSPHRASE,   // "INVALID_PASSPHRASE"
  OWS_ERROR_INVALID_INPUT,        // "INVALID_INPUT"
  OWS_ERROR_POLICY_DENIED,        // "POLICY_DENIED"
  OWS_ERROR_CHAIN_NOT_SUPPORTED,  // "CHAIN_NOT_SUPPORTED"
} from "@peaqos/peaq-os-sdk";

Surface area for the OWS-native signing path used by PeaqosClient.fromWallet(..., owsSigning: true). The matching OwsSigningErrorCode type is the union of all five string-literal codes.

​Install

​Environment variables

​peaq mainnet contracts

​Machine Markets orchestration

​Client

​PeaqosClient

​fromEnv

​fromWallet

​Wallets (OWS)

​generateKeypair

​OWS wallet lifecycle

​Accessors

​Tokenomics 2.0

​activateMachine

​activateMachineWithUsdt

​previewMachineActivation, previewMachineActivationWithUsdt

​computeMachineId

​Reads

​Lifecycle and subscription

​Ownership (ERC-721)

​DID updates

​previewMachineAction

​Machine-ID helpers

​Disabled in Tokenomics mode

​Solana (SVM)

​Opting in

​Reads

​Onboarding

​Management

​Events

​MCR API compatibility

​Registration

​registerMachine

​registerFor

​Gas Station

​setupFaucet2FA

​confirmFaucet2FA

​fundFromGasStation

​NFT & DID

​mintNft

​tokenIdOf

​writeMachineDIDAttributes

​writeProxyDIDAttributes

​readAttribute

​encodeAddAttribute

​Smart accounts

​deploySmartAccount

​getSmartAccountAddress

​Bridge

​bridgeNft

​waitForBridgeArrival

​Events (Qualify)

​submitEvent

​batchSubmitEvents

​validateSubmitEventParams

​computeDataHash

​checkOperationalLimits

​Queries

​queryMcr

​queryMachine

​queryOperatorMachines

​Verify

​VerifyReadClient

​Chip preflight

​Error classes

​Type exports

​Constants

Install

Environment variables

peaq mainnet contracts

Machine Markets orchestration

Client

`PeaqosClient`

`fromEnv`

`fromWallet`

Wallets (OWS)

`generateKeypair`

OWS wallet lifecycle

Accessors

Tokenomics 2.0

`activateMachine`

`activateMachineWithUsdt`

`previewMachineActivation`, `previewMachineActivationWithUsdt`

`computeMachineId`

Reads

Lifecycle and subscription

Ownership (ERC-721)

DID updates

`previewMachineAction`

Machine-ID helpers

Disabled in Tokenomics mode

Solana (SVM)

Opting in

Reads

Onboarding

Management

Events

MCR API compatibility

Registration

`registerMachine`

`registerFor`

Gas Station

`setupFaucet2FA`

`confirmFaucet2FA`

`fundFromGasStation`

NFT & DID

`mintNft`

`tokenIdOf`

`writeMachineDIDAttributes`

`writeProxyDIDAttributes`

`readAttribute`

`encodeAddAttribute`

Smart accounts

`deploySmartAccount`

`getSmartAccountAddress`

Bridge

`bridgeNft`

`waitForBridgeArrival`

Events (Qualify)

`submitEvent`

`batchSubmitEvents`

`validateSubmitEventParams`

`computeDataHash`

`checkOperationalLimits`

Queries

`queryMcr`

`queryMachine`

`queryOperatorMachines`

Verify

`VerifyReadClient`

Chip preflight

Error classes

Type exports

Constants