> ## Documentation Index > Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Machine Markets > Machine Agents, skills, services, and search. How an AI agent paired to a machine actually buys what the machine needs. Machine Markets is the orchestration layer behind [Scale](/peaqos/functions/scale). It pairs an AI agent to an activated, bonded machine, gives that pairing a policy with spend limits and an allow/denylist, and exposes a curated catalogue of capabilities and provider services the agent can search against using the machine's context. The agent's legitimacy is the machine's: peaqID, Machine NFT, MCR, and trust level all carry through. ## Roles | Role | Description | | :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Machine** | An activated peaqOS device with a peaqID, Machine NFT, smart account, and bond. The machine is the principal. Funds, identity, and reputation belong to it. | | **Proxy Operator / Machine Owner** | Human (or org) that controls the machine. Funds the wallet, pairs the agent, sets the policy, can revoke or repair at any time. | | **Machine Agent** | Third-party AI agent (Claude, OpenAI, Virtuals, Teneo, your own) given delegated, bounded authority over the machine's smart account. peaq does not provide the agent. | | **Machine-Side Runtime Agent** | Optional process running on the device that registers local runtime endpoints. Used for skills that execute on the machine rather than at a remote provider. | | **Service Provider** | External entity (QVAC, agentic.market services over x402, pay.sh services, etc.) whose service is registered in the catalogue and consumed by Machine Agents. | ## Core objects ```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}} type Machine = { id: string; displayName: string; status: "draft" | "active" | "degraded" | "blocked" | "archived"; ownerId: string; identityRef: string; // did:peaq:0x... or peaqos:machine: identityProof?: { /* EIP-191 controller signature, see API ref */ } | null; machineType: string; runtimeProfile: string; capabilities: string[]; labels: Record; policyIds: string[]; skillKeys: string[]; createdAt: string; updatedAt: string; }; type AgentPairing = { id: string; machineId: string; status: "active" | "paused" | "revoked"; agentAddress: string; agentDid: string | null; agentProvider: string; // "anthropic" | "openai" | "virtuals" | ... agentRole: string; // free-form, e.g. "ops" | "trader" | "buyer" description?: string | null; verification: { method: "eip191"; signerAddress: string; verifiedAt: string; challengeExpiresAt: string; } | null; delegationPolicy: { allowedSkillKeys: string[]; deniedSkillKeys: string[]; allowedServiceIds: string[]; deniedServiceIds: string[]; perTransactionLimit?: number | null; dailySpendLimit?: number | null; currency?: string | null; }; hasAuthToken: boolean; tokenLastFour: string | null; sessionId: string | null; sessionTokenId: string | null; sessionIssuedAt: string | null; sessionExpiresAt: string | null; pairingToken?: string; // signed HS256 session JWT, returned once at create/rotate createdAt: string; updatedAt: string; }; ``` ## Skills vs services Two things look similar. They aren't. * A **skill** is a capability schema. `storage.object` says "an object-storage service exposes these operations". Skills are the contract. * A **service** is a concrete instance of a skill from a specific provider. "Exa search via agentic.market" is a service. Services are what you actually buy. Service types: ```text theme={"theme":{"light":"github-light-default","dark":"github-dark"}} oracle.price-feed compute.marketplace storage.object data.location network.partner-console identity.proof-of-person device.control machine.commerce ``` Execution modes: * **Native**: peaqOS executes the skill server-side or on a registered machine-side runtime endpoint. No human handoff. * **External handoff**: the orchestrator returns a structured handoff (URL, contact, setup steps) and the agent or operator completes the purchase out of band. Used when a provider integration is partner-required or credentials-required. Integration status surfaces how ready a service is to execute end-to-end: ```text theme={"theme":{"light":"github-light-default","dark":"github-dark"}} native | credentials-required | partner-required | local-config-required | setup-required | docs-only ``` ## Identity proof flow Machine registration with the orchestrator is gated by a DID-controller signature. The flow: 1. Call `POST /machine-identity/challenges` with the machine's `identityRef`. The orchestrator looks up the controller addresses from peaqOS MCR data and returns a short-lived `challengeId` plus a `message`. 2. Sign `message` with the controller's private key using EIP-191 `personal_sign`. 3. Submit `{ challengeId, signature }` as `identityProof` when calling `POST /machines`. The orchestrator verifies the signature recovers to one of the controller addresses before persisting. The stored proof is re-checked against MCR data on subsequent machine-bound writes. The proof expires. Re-challenge when it does. ## Pairing flow Pairing an agent to a machine follows the same challenge-sign-verify pattern, scoped to the agent's wallet key: 1. Call `POST /machines/:machineId/agent-pairings/challenges` with `agentAddress`, `agentProvider`, `agentRole`, and optional `agentDid`. The orchestrator returns an `AgentPairingChallenge` with a `challengeId`, a machine-bound `message`, and an `expiresAt`. 2. The Machine Agent signs `message` (EIP-191 `personal_sign`) with the wallet key behind `agentAddress`. 3. Call `POST /machines/:machineId/agent-pairings` with `agentProof: { challengeId, signature }` and the delegation policy. The orchestrator verifies the signature recovers to `agentAddress`, persists the pairing with `verification` metadata, and returns the `AgentPairing` with a signed HS256 session JWT in `pairingToken`. Store the token client-side and send it as `x-agent-pairing-token` on market writes. 4. Tokens expire (default 1 hour). Rotate by issuing a fresh challenge and calling `POST /machines/:machineId/agent-pairings/:pairingId/sessions` with the new proof. A policy change invalidates the current token's `delegationPolicyHash`, so rotate after every `PATCH` to the delegation policy. ## Order lifecycle A successful purchase walks the order state machine: ```text theme={"theme":{"light":"github-light-default","dark":"github-dark"}} created -> payment_pending -> ready -> executing -> delivered -> confirmed ``` Branches: `disputed` if the buyer raises a dispute after delivery; `cancelled` if a refund settles before delivery; `failed` if execution errors; `handoff` if the service ships as an external handoff rather than a native skill run. Each successful execution writes an `Outcome` and a `Run`. Outcomes record the service result; runs record the execution metadata (skill, route, status). Both are queryable via `GET /runs` and `GET /machines/:machineId/outcomes`. Payments follow their own state machine, coupled to the order: ```text theme={"theme":{"light":"github-light-default","dark":"github-dark"}} intent_created -> held -> release_pending -> released \-> refunded \-> frozen (on dispute) ``` `not_required` short-circuits the payment lifecycle for free or pre-authorised services. ## Payment rails The orchestrator quotes services in the rail the provider supports: | Rail | When it shows up | | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x402` | [agentic.market](https://agentic.market) services and most [pay.sh](https://pay.sh) services. Agent wallet responds to an HTTP 402 challenge. Execute goes through the `paidHttp` adapter — orchestrator replays the request with the agent's payment headers. | | `mpp` | Solana micro-payment protocol. Used by some pay.sh services on Solana. | | `vault-stripe` / `external` | Card-mediated or external handoff. The orchestrator returns a structured handoff and the agent or operator settles out of band. | | `wallet` / `wdk-usdt-transfer` | Direct USDT transfer on peaq. `wallet` upgrades to `wdk-usdt-transfer` once the proof is RPC-verified against the ERC-20 Transfer log. | | `onchain-escrow` / `escrow` | Funds locked into a service-specified escrow contract. | | `not-required` | Free or pre-authorised services. | | `offchain-record` | Off-chain attestation, recorded but not RPC-verified. | Payment proof modes: * **`recorded`**: operator attestation. The orchestrator stores the proof but does not verify on-chain. * **`rpc`**: the orchestrator queries an EVM RPC for the transaction receipt and the ERC-20 Transfer log, validating sender, recipient, token, and amount. Solana proofs are always `recorded`. Set `PEAQOS_PAYMENT_RPC_URL` (or `PEAQ_EVM_RPC_URL` / `PEAQOS_EVM_RPC_URL`) to enable RPC verification by default. ## Delegation, bounded The orchestration layer enforces the delegation policy server-side. Spend limits, allow/denylists, and skill restrictions are checked at request time, not just at pairing time. Mutating the policy through `PATCH /machines/:machineId/agent-pairings/:pairingId` takes effect immediately for new calls. Revoking a pairing (`DELETE`) terminates the agent's authority at once. ## Multichain shape Scale keeps peaq canonical for identity and registry state. Across supported chains: * peaqID, Machine NFT, and the Service Registry stay on peaq * Machine NFTs and smart accounts deploy on supported chains (Base first) * IdentityLite, DIDLite, and StakingLite mirror peaq state on each supported chain (Agung and Base Sepolia at launch); a dedicated MCR oracle on satellites is reserved * Machine Agents can pay across chains using the chain and token a service quotes in The orchestrator speaks `eip155:*` CAIP-2 identifiers through the SDK wallet layer. See [Wallets (OWS)](/peaqos/wallets) and the [Omni-chain concept](/peaqos/concepts/omni-chain) for the satellite-chain contract surface (DIDLite, IdentityLite, StakingLite). ## Related * [Scale function](/peaqos/functions/scale) * [Machine Markets API](/peaqos/api-reference/machine-markets-overview) * [Activate](/peaqos/functions/activate) * [Qualify](/peaqos/functions/qualify)