Core concepts
The handful of ideas you need before integrating: devices, services, identifiers, and x402.
Devices and services
A device is a piece of hardware (an ESP32, a gateway, a robot). A device is just an identity — everything callable lives on its services. Each service is one capability (e.g. “set room temperature”) with its own price, payout wallet, access rules, and argument schema.
Identifiers
| ID | Visibility | Used for |
|---|---|---|
deviceId | Public — share freely | Addressing a device from an agent (appears in the URL). |
serviceId | Public — returned by discovery | Addressing a specific capability. |
connectorId | Private — never share | The server↔device MQTT transport identity. |
TheconnectorIdis a secret. It is never returned by any public or agent-facing endpoint. Knowing a publicdeviceIdlets you call a device, but can never be used to reach its transport directly. See Security.
Service types
- FREE — the call returns the device result directly (
201). No wallet. - PAID — the call requires a USDC payment over x402 before the device runs the work.
Password protection
Any service (free or paid) can require a username + passwordset by the owner. Callers supply them in the request body or viax-access-username / x-access-password headers.
x402 in one paragraph
x402 is the open HTTP 402 Payment Required standard. A paid endpoint answers a plain request with a 402 that describes what to pay. An x402 client signs a stablecoin payment, adds an X-PAYMENT header, and retries — the server verifies, settles, and returns the result plus an X-PAYMENT-RESPONSE receipt. 0xBS speaks the standard v1 wire format, so any x402 client works.