ROS 2 service catalog

Canonical peaqOS ROS 2 machine endpoints plus documented agent aliases, grouped by SDK capability.

This page lists the canonical machine endpoints and documented agent aliases exposed under /peaqos_node. Requests use ROS 2 service types from peaq_ros2_interfaces. All examples assume the node is running with a populated peaq_robot.yaml; see ROS 2 configuration.

Quote EVM addresses and large integers in ros2 service call YAML payloads. Unquoted addresses can parse as numbers and break the request.

Wallets

Local EVM wallet registry. Service calls return public metadata only: address, account_id, chain_id, network, label, and created_at. Private keys never cross ROS.

Service	Type
/peaqos_node/wallet/create	peaq_ros2_interfaces/srv/PeaqosCreateWallet
/peaqos_node/wallet/list	peaq_ros2_interfaces/srv/PeaqosListWallets
/peaqos_node/wallet/get	peaq_ros2_interfaces/srv/PeaqosGetWallet
/peaqos_node/wallet/delete	peaq_ros2_interfaces/srv/PeaqosDeleteWallet

# Create
ros2 service call /peaqos_node/wallet/create \
  peaq_ros2_interfaces/srv/PeaqosCreateWallet \
  "{label: 'robot-001'}"

# List
ros2 service call /peaqos_node/wallet/list \
  peaq_ros2_interfaces/srv/PeaqosListWallets "{}"

# Get
ros2 service call /peaqos_node/wallet/get \
  peaq_ros2_interfaces/srv/PeaqosGetWallet \
  "{address: '<MACHINE_EVM_ADDRESS>'}"

# Delete
ros2 service call /peaqos_node/wallet/delete \
  peaq_ros2_interfaces/srv/PeaqosDeleteWallet \
  "{address: '<MACHINE_EVM_ADDRESS>'}"

SDK import, export, and from_wallet flows are intentionally not exposed over ROS because they require private keys, mnemonics, or passphrases. Use the Python SDK or CLI for those.

Gas Station

Gas Station onboarding for fresh machine wallets. 2FA codes are request-only and should not be logged.

Service	Type
/peaqos_node/faucet/setup_2fa	peaq_ros2_interfaces/srv/PeaqosSetupFaucet2FA
/peaqos_node/faucet/confirm_2fa	peaq_ros2_interfaces/srv/PeaqosConfirmFaucet2FA
/peaqos_node/wallet/fund	peaq_ros2_interfaces/srv/PeaqosFundWallet

# 1. Start 2FA enrollment for the owner
ros2 service call /peaqos_node/faucet/setup_2fa \
  peaq_ros2_interfaces/srv/PeaqosSetupFaucet2FA \
  "{owner_address: '<OWNER_EVM_ADDRESS>', qr_format: 'svg'}"

# 2. Confirm with the OTP from the authenticator
ros2 service call /peaqos_node/faucet/confirm_2fa \
  peaq_ros2_interfaces/srv/PeaqosConfirmFaucet2FA \
  "{owner_address: '<OWNER_EVM_ADDRESS>', two_factor_code: '123456'}"

# 3. Fund the target wallet through the Gas Station
ros2 service call /peaqos_node/wallet/fund \
  peaq_ros2_interfaces/srv/PeaqosFundWallet \
  "{owner_address: '<OWNER_EVM_ADDRESS>', target_address: '<MACHINE_EVM_ADDRESS>', chain_id: 'peaq', two_factor_code: '123456', request_id: ''}"

See the error reference for INVALID_2FA, 2FA_LOCKED, RATE_LIMITED, and CAP_EXCEEDED_OWNER.

Registration

Tokenomics 1.0 path. The registration, NFT and DID services below write to the Tokenomics 1.0 contracts. Use them only for an existing Tokenomics 1.0 fleet. New machines use the Economics 2.0 flow in Activate, which has no ROS 2 service.

Service	Type
/peaqos_node/machine/register	peaq_ros2_interfaces/srv/PeaqosRegisterMachine
/peaqos_node/agent/register	peaq_ros2_interfaces/srv/PeaqosRegisterAgent
/peaqos_node/machine/register_for	peaq_ros2_interfaces/srv/PeaqosRegisterFor
/peaqos_node/agent/register_for	peaq_ros2_interfaces/srv/PeaqosRegisterFor

/machine/register and /agent/register are interchangeable surfaces over the same registration call. Pick whichever language matches your fleet model. /machine/register_for and /agent/register_for are likewise the same handler under two paths.

# Self-managed: machine signs for itself
ros2 service call /peaqos_node/machine/register \
  peaq_ros2_interfaces/srv/PeaqosRegisterMachine \
  "{address: '<MACHINE_EVM_ADDRESS>'}"

# Equivalent agent-flavored alias
ros2 service call /peaqos_node/agent/register \
  peaq_ros2_interfaces/srv/PeaqosRegisterAgent \
  "{address: '<AGENT_EVM_ADDRESS>'}"

# Proxy operator: operator signs on behalf of a fleet machine
ros2 service call /peaqos_node/machine/register_for \
  peaq_ros2_interfaces/srv/PeaqosRegisterFor \
  "{proxy_address: '<OPERATOR_EVM_ADDRESS>', machine_address: '<MACHINE_EVM_ADDRESS>'}"

For background on the two patterns, see Self-managed onboarding and Proxy operator fleet.

Machine NFT

Service	Type
/peaqos_node/nft/mint	peaq_ros2_interfaces/srv/PeaqosMintNft
/peaqos_node/nft/token_id_of	peaq_ros2_interfaces/srv/PeaqosTokenIdOf

ros2 service call /peaqos_node/nft/mint \
  peaq_ros2_interfaces/srv/PeaqosMintNft \
  "{signer_address: '<OWNER_OR_PROXY_ADDRESS>', machine_id: 1, recipient: '<RECIPIENT_EVM_ADDRESS>'}"

ros2 service call /peaqos_node/nft/token_id_of \
  peaq_ros2_interfaces/srv/PeaqosTokenIdOf \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', machine_id: 1}"

DID attributes

Service	Type
/peaqos_node/did/read_attribute	peaq_ros2_interfaces/srv/PeaqosReadDidAttribute
/peaqos_node/did/write_machine_attributes	peaq_ros2_interfaces/srv/PeaqosWriteMachineDidAttributes
/peaqos_node/did/write_proxy_attributes	peaq_ros2_interfaces/srv/PeaqosWriteProxyDidAttributes

/did/write_machine_attributes is the standard machine DID write path. It writes the six canonical attributes machineId, nftTokenId, operator, documentation_url, data_api and data_visibility in one call. /did/write_proxy_attributes is the proxy/operator equivalent; it atomically writes the two standard proxy DID attributes (machineId and the machines list the operator manages).

# Read one attribute by name from the DID precompile
ros2 service call /peaqos_node/did/read_attribute \
  peaq_ros2_interfaces/srv/PeaqosReadDidAttribute \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', did_address: '<DID_EVM_ADDRESS>', name: 'machineId'}"

# Write the standard machine attributes in one shot
ros2 service call /peaqos_node/did/write_machine_attributes \
  peaq_ros2_interfaces/srv/PeaqosWriteMachineDidAttributes \
  "{signer_address: '<MACHINE_EVM_ADDRESS>', machine_id: 1, nft_token_id: 1, operator_did: 'did:peaq:<OPERATOR_EVM_ADDRESS>', documentation_url: 'https://docs.example/robot-001', data_api: 'https://api.example/robot-001', data_visibility: 'onchain'}"

# Write proxy/operator DID attributes
ros2 service call /peaqos_node/did/write_proxy_attributes \
  peaq_ros2_interfaces/srv/PeaqosWriteProxyDidAttributes \
  "{signer_address: '<PROXY_EVM_ADDRESS>', proxy_agent_id: 1, machine_ids: [1, 2, 3]}"

Events

Service	Type
/peaqos_node/events/validate	peaq_ros2_interfaces/srv/PeaqosValidateEvent
/peaqos_node/events/submit	peaq_ros2_interfaces/srv/PeaqosSubmitEvent
/peaqos_node/events/batch_submit	peaq_ros2_interfaces/srv/PeaqosBatchSubmitEvents

/events/validate runs locally: it computes the data hash and checks the payload before you spend gas. /events/batch_submit goes through the peaq batch precompile (0x...0805) so a multi-event submission is atomic on chain.

raw_data_hex must be non-empty hex when set. Pass an empty string to submit an event without raw data; '0x' is rejected.

# Validate locally
ros2 service call /peaqos_node/events/validate \
  peaq_ros2_interfaces/srv/PeaqosValidateEvent \
  "{machine_id: 1, event_type: 1, value: 1, timestamp: 1770000000, raw_data_hex: '0x7b7d', trust_level: 0, source_chain_id: 3338, source_tx_hash: '', metadata_hex: '0x7b7d'}"

# Submit one event
ros2 service call /peaqos_node/events/submit \
  peaq_ros2_interfaces/srv/PeaqosSubmitEvent \
  "{signer_address: '<MACHINE_EVM_ADDRESS>', machine_id: 1, event_type: 1, value: 1, timestamp: 1770000000, raw_data_hex: '0x7b7d', trust_level: 0, source_chain_id: 3338, source_tx_hash: '', metadata_hex: '0x7b7d'}"

# Atomic batch
ros2 service call /peaqos_node/events/batch_submit \
  peaq_ros2_interfaces/srv/PeaqosBatchSubmitEvents \
  "{signer_address: '<MACHINE_EVM_ADDRESS>', events_json: '[{\"machine_id\":1,\"event_type\":1,\"value\":1,\"timestamp\":1770000000,\"raw_data_hex\":\"0x7b7d\",\"trust_level\":0,\"source_chain_id\":3338,\"source_tx_hash\":\"\",\"metadata_hex\":\"0x7b7d\"}]'}"

For event field rules, see Events and SDK JS event validation.

MCR queries

Service	Type
/peaqos_node/mcr/query	peaq_ros2_interfaces/srv/PeaqosQueryMcr
/peaqos_node/mcr/machine	peaq_ros2_interfaces/srv/PeaqosQueryMachine
/peaqos_node/mcr/operator_machines	peaq_ros2_interfaces/srv/PeaqosQueryOperatorMachines

The node registers Tokenomics 1.0 machines, and its mcr/query, mcr/machine and mcr/operator_machines services do not work with the MCR API.

Smart accounts

ERC-4337 machine accounts are deployed through MachineAccountFactory. Address prediction is deterministic (CREATE2 salt) and cheap; call address first, deploy second.

Service	Type
/peaqos_node/smart_account/address	peaq_ros2_interfaces/srv/PeaqosGetSmartAccountAddress
/peaqos_node/smart_account/deploy	peaq_ros2_interfaces/srv/PeaqosDeploySmartAccount

# Predict address (no tx)
ros2 service call /peaqos_node/smart_account/address \
  peaq_ros2_interfaces/srv/PeaqosGetSmartAccountAddress \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', owner: '<OWNER_EVM_ADDRESS>', machine: '<MACHINE_EVM_ADDRESS>', daily_limit: '', salt: '0'}"

# Deploy
ros2 service call /peaqos_node/smart_account/deploy \
  peaq_ros2_interfaces/srv/PeaqosDeploySmartAccount \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', owner: '<OWNER_EVM_ADDRESS>', machine: '<MACHINE_EVM_ADDRESS>', daily_limit: '', salt: '0'}"

daily_limit is kept on the service for backward compatibility. The current MachineAccountFactory ignores it, so an empty string is fine. Both calls require peaq_os.contracts.machine_account_factory (or MACHINE_ACCOUNT_FACTORY_ADDRESS) to be set.

Bridge

Service	Type
/peaqos_node/bridge/nft	peaq_ros2_interfaces/srv/PeaqosBridgeNft
/peaqos_node/bridge/wait_arrival	peaq_ros2_interfaces/srv/PeaqosWaitForBridgeArrival

ros2 service call /peaqos_node/bridge/nft \
  peaq_ros2_interfaces/srv/PeaqosBridgeNft \
  "{signer_address: '<OWNER_EVM_ADDRESS>', token_id: 1, source: 'peaq', destination: 'base', recipient: '<RECIPIENT_EVM_ADDRESS>', base_rpc_url: '', base_nft_address: '', options_hex: ''}"

ros2 service call /peaqos_node/bridge/wait_arrival \
  peaq_ros2_interfaces/srv/PeaqosWaitForBridgeArrival \
  "{dst_rpc_url: 'https://mainnet.base.org', dst_nft_address: '0xee8A521eA434b11F956E2402beC5eBfa753Babfa', token_id: 1, timeout: 900}"

Bridging moves Tokenomics 1.0 Machine NFTs only and has its own page: see Bridge for the full peaq to Base flow, gas requirements, and arrival polling. Bridging back from Base to peaq needs Base ETH on the signer wallet.

Tips

• Source ROS and the workspace before every session: source /opt/ros/<distro>/setup.bash && source install/setup.bash.
• Stream logs in another terminal: tail -f /tmp/peaqos_node.log.
• For batched onboarding flows, prefer /events/batch_submit over multiple /events/submit calls: single tx, lower fees.