> ## 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.

# Stream: Distribution & P2P delivery

> Sell and deliver stream data end-to-end: purchases, payment rails (transfer and x402), the seller control socket, and delivery — buyer access over S3, or encrypted chunks machine-to-machine over the peaqos-p2p transport.

export const KeyTerms = ({all = {}, ids = [], title = "Key terms in this guide"}) => <details className="not-prose my-4 rounded-xl border border-zinc-200 px-4 py-3 dark:border-zinc-800">
    <summary className="cursor-pointer font-medium text-zinc-900 dark:text-zinc-100">
      {title}
    </summary>
    <div className="mt-3 space-y-2 text-sm text-zinc-700 dark:text-zinc-300">
      {ids.map(id => {
  const t = all[id] || ({});
  return <div key={id}>
            <strong>{t.term}.</strong> {t.def}
          </div>;
})}
    </div>
  </details>;

export const G = {
  onchain: {
    id: "onchain",
    cat: "chain-infra",
    term: "On-chain vs off-chain",
    def: "On-chain means written to the shared public ledger every machine agrees on: permanent and readable by anyone. Off-chain means kept on a normal private server instead."
  },
  blockchain: {
    id: "blockchain",
    cat: "chain-infra",
    term: "Chain / blockchain",
    def: "A shared, tamper-resistant public database maintained by a whole network of computers with no single owner. Different chains are separate such networks."
  },
  peaqChain: {
    id: "peaqChain",
    cat: "chain-infra",
    term: "peaq chain",
    def: "The machine-focused blockchain peaqOS uses as home base for identity and credit records."
  },
  transaction: {
    id: "transaction",
    cat: "chain-infra",
    term: "Transaction (tx) / tx hash",
    def: "A single signed request that changes the ledger. Its hash is a unique, receipt-like ID you can use to look it up later."
  },
  rpcUrl: {
    id: "rpcUrl",
    cat: "chain-infra",
    term: "RPC URL / endpoint",
    def: "The network address your code calls to read from or write to a chain, like the base URL of the chain's API server."
  },
  mainnet: {
    id: "mainnet",
    cat: "chain-infra",
    term: "Mainnet / testnet (agung)",
    def: "Mainnet is the real, live network where tokens have real value. Testnet is a free practice copy with worthless tokens; peaq's is called agung."
  },
  evm: {
    id: "evm",
    cat: "chain-infra",
    term: "EVM / EVM-compatible",
    def: "The Ethereum Virtual Machine: the standard runtime many chains share, so the same 0x... addresses and tools work across all of them. peaq is EVM-compatible."
  },
  node: {
    id: "node",
    cat: "chain-infra",
    term: "Node (RPC node)",
    def: "A server running the blockchain software that holds a copy of the ledger and answers queries. NOT a ROS 2 node, despite the shared word."
  },
  chainId: {
    id: "chainId",
    cat: "chain-infra",
    term: "Chain ID",
    def: "A number that uniquely labels a chain so software doesn't confuse networks (peaq is 3338, Base is 8453)."
  },
  precompile: {
    id: "precompile",
    cat: "chain-infra",
    term: "Precompile",
    def: "A built-in function baked into the chain at a fixed address that acts like a contract but runs as faster native code. The batch one bundles several actions into one all-or-nothing transaction."
  },
  dataHash: {
    id: "dataHash",
    cat: "chain-infra",
    term: "Data hash (keccak256)",
    def: "A short, fixed-length fingerprint of a file, stored on-chain instead of the file itself, so data can be verified later while the raw data stays off-chain."
  },
  wallet: {
    id: "wallet",
    cat: "wallet-keys",
    term: "Wallet",
    def: "An account on the chain, identified by a public address, that holds a machine's funds and approves its actions. Really just a pair of keys, not a place money is stored."
  },
  keypair: {
    id: "keypair",
    cat: "wallet-keys",
    term: "Keypair",
    def: "The two matched secrets behind a wallet: a public address you can share, and a private key you keep secret that signs actions."
  },
  privateKey: {
    id: "privateKey",
    cat: "wallet-keys",
    term: "Private key",
    def: "The secret string that proves you control a wallet. Anyone who has it has full control, like a master password that can never be reset."
  },
  sign: {
    id: "sign",
    cat: "wallet-keys",
    term: "Sign / signature",
    def: "Using your private key to produce a cryptographic stamp proving you approved a specific action, without ever revealing the key."
  },
  signer: {
    id: "signer",
    cat: "wallet-keys",
    term: "Signer / signing identity",
    def: "The wallet whose private key authorizes an action: the account the network treats as the one taking it. NOT a file or an app."
  },
  address: {
    id: "address",
    cat: "wallet-keys",
    term: "Address (0x...)",
    def: "The public 0x... identifier of a wallet or contract you can freely share so others can send to it or look it up, like an account number."
  },
  eoa: {
    id: "eoa",
    cat: "wallet-keys",
    term: "EOA (externally owned account)",
    def: "A plain wallet controlled directly by a private key, as opposed to one controlled by code. Here, the account that IS the machine."
  },
  ows: {
    id: "ows",
    cat: "wallet-keys",
    term: "OWS / wallet vault",
    def: "An open standard for storing wallet keys in an encrypted local file (a vault) with a backup phrase and an activity log, instead of a bare key in a text file."
  },
  passphrase: {
    id: "passphrase",
    cat: "wallet-keys",
    term: "Passphrase (OWS_PASSPHRASE)",
    def: "The password that unlocks the encrypted wallet vault so its key can be used to sign."
  },
  mnemonic: {
    id: "mnemonic",
    cat: "wallet-keys",
    term: "Mnemonic / seed phrase",
    def: "A list of 12 or 24 ordinary words that encodes a wallet's secret key, used to back it up and recover it. Whoever has the words controls the wallet."
  },
  derivation: {
    id: "derivation",
    cat: "wallet-keys",
    term: "Derivation path",
    def: "The deterministic recipe that turns one backup phrase into many specific keys and addresses, one per network or index."
  },
  challenge: {
    id: "challenge",
    cat: "wallet-keys",
    term: "Challenge (sign-to-prove)",
    def: "A login-style handshake: the server sends a random message, you sign it with your key, and the signature proves you control the account without sending the key."
  },
  eip191: {
    id: "eip191",
    cat: "wallet-keys",
    term: "EIP-191 / personal_sign",
    def: "A standard way to sign a plain message to prove you control an account, without sending any on-chain transaction."
  },
  did: {
    id: "did",
    cat: "identity",
    term: "DID / peaqID",
    def: "A globally unique, self-owned ID for a machine that lives on the chain and isn't issued by any single company. peaqID is peaq's version, written did:peaq:0x..."
  },
  register: {
    id: "register",
    cat: "identity",
    term: "Register a machine",
    def: "Putting a machine on the network for the first time, which gives it an ID, a DID, an ownership token, and a locked deposit. registerMachine is self-managed; registerFor is on someone else's behalf."
  },
  machineId: {
    id: "machineId",
    cat: "identity",
    term: "Machine ID",
    def: "The number the network assigns your machine when it registers, used as its handle in every later call."
  },
  ownerOperator: {
    id: "ownerOperator",
    cat: "identity",
    term: "Owner / operator",
    def: "The owner owns a machine; the operator runs it. They can be the same account (self-managed) or different (proxy-managed)."
  },
  proxyOperator: {
    id: "proxyOperator",
    cat: "identity",
    term: "Proxy operator",
    def: "One account that registers and manages many machines on behalf of their owners, so a fleet operator can handle a whole fleet from one wallet."
  },
  didAttributes: {
    id: "didAttributes",
    cat: "identity",
    term: "DID attributes",
    def: "Public name-value facts (a docs link, a data endpoint) attached to a machine's DID and stored on-chain for anyone to read. Writing them is a separate transaction from registration."
  },
  pairing: {
    id: "pairing",
    cat: "identity",
    term: "Pairing / pairing token",
    def: "The verified link between an AI agent and a machine, set up by signing a challenge. The pairing token is the signed credential the agent sends with each request, like a temporary access badge."
  },
  hardwareAttestation: {
    id: "hardwareAttestation",
    cat: "identity",
    term: "Hardware attestation",
    def: "A tamper-resistant chip on the machine cryptographically vouching that it's genuine hardware, so its identity can't be faked in software. This is the Verify layer."
  },
  gas: {
    id: "gas",
    cat: "tokens-economics",
    term: "Gas",
    def: "The small fee, paid in the chain's token, that every action writing to the ledger costs, like a per-write transaction cost."
  },
  peaqToken: {
    id: "peaqToken",
    cat: "tokens-economics",
    term: "PEAQ (token)",
    def: "The peaq network's own token, used to pay gas fees and to lock up as the deposit when registering a machine."
  },
  gasStation: {
    id: "gasStation",
    cat: "tokens-economics",
    term: "Gas Station / faucet",
    def: "A peaq service that hands a brand-new, empty wallet a tiny starting amount of tokens so it can afford its first network fees. Gated by 2FA."
  },
  bond: {
    id: "bond",
    cat: "tokens-economics",
    term: "Bond",
    def: "A refundable deposit (currently 1 PEAQ) you lock up to register a machine, proving skin in the game, like a security deposit. Bonded means the deposit is in place."
  },
  nft: {
    id: "nft",
    cat: "tokens-economics",
    term: "NFT",
    def: "A unique, one-of-a-kind ownership token recorded on the chain. Unlike a coin, no two are interchangeable."
  },
  mint: {
    id: "mint",
    cat: "tokens-economics",
    term: "Mint / minting",
    def: "Creating a brand-new token on the chain and assigning it to an owner, like stamping a fresh serial-numbered certificate into existence."
  },
  machineNft: {
    id: "machineNft",
    cat: "tokens-economics",
    term: "Machine NFT",
    def: "The unique token representing one specific physical machine and its financial profile. It can be sold or bridged on its own, separate from the machine's identity."
  },
  identityNft: {
    id: "identityNft",
    cat: "tokens-economics",
    term: "Identity NFT",
    def: "A non-transferable (soulbound) token minted automatically when a machine registers, representing its identity. Its token ID equals the machine ID."
  },
  tokenId: {
    id: "tokenId",
    cat: "tokens-economics",
    term: "Token ID",
    def: "The unique number identifying one specific token within a collection, like a serial number."
  },
  mcr: {
    id: "mcr",
    cat: "tokens-economics",
    term: "Machine Credit Rating (MCR)",
    def: "A creditworthiness score for a machine (a Moody's-style grade AAA down to NR, plus a 0-100 number) computed from its recorded earnings and activity. Like a credit score for a robot."
  },
  mcrApi: {
    id: "mcrApi",
    cat: "tokens-economics",
    term: "MCR API",
    def: "The public web service you call to fetch a machine's credit score and profile as JSON. No login needed."
  },
  provisioned: {
    id: "provisioned",
    cat: "tokens-economics",
    term: "Provisioned / NR (Not Rated)",
    def: "Early MCR statuses. Provisioned means registered and bonded but with too little history to score yet. NR means no grade, because the score is too low or the machine isn't bonded."
  },
  event: {
    id: "event",
    cat: "tokens-economics",
    term: "Event (revenue / activity)",
    def: "A recorded data point about a machine's work, submitted to the chain to feed its credit score. Revenue events report money earned; activity events report work with no money. NOT a ROS topic message."
  },
  trustLevel: {
    id: "trustLevel",
    cat: "tokens-economics",
    term: "Trust level",
    def: "A label on each submitted event saying how strongly its truth is backed: the machine's word (0), a checkable on-chain record (1), or tamper-proof hardware proof (2)."
  },
  escrow: {
    id: "escrow",
    cat: "tokens-economics",
    term: "Escrow",
    def: "Holding a buyer's payment in a neutral locked place until the service is delivered, then releasing it, so neither side has to trust the other first."
  },
  paymentRail: {
    id: "paymentRail",
    cat: "tokens-economics",
    term: "Payment rail",
    def: "The specific method or channel a payment moves through, like choosing card vs bank transfer vs a particular token."
  },
  x402: {
    id: "x402",
    cat: "tokens-economics",
    term: "x402",
    def: "A web payment standard where a server answers 'payment required' with exact instructions, and the buyer's wallet signs an authorization instead of sending a separate transaction — built for machines and agents paying per request."
  },
  usdt: {
    id: "usdt",
    cat: "tokens-economics",
    term: "USDT",
    def: "A stablecoin token meant to hold a value of one US dollar, used to pay service providers without price swings."
  },
  fractionalize: {
    id: "fractionalize",
    cat: "tokens-economics",
    term: "Fractionalize (ERC-3643)",
    def: "Splitting ownership of one machine into many small tradable shares so multiple people can each own a piece. ERC-3643 is the regulated-securities token standard used to do it."
  },
  smartContract: {
    id: "smartContract",
    cat: "smart-contracts",
    term: "Smart contract / contract address",
    def: "A program deployed on the chain that runs exactly as written and that anyone can call, identified by its own 0x... address."
  },
  registryContracts: {
    id: "registryContracts",
    cat: "smart-contracts",
    term: "Registry contracts",
    def: "On-chain programs that each keep an official, lookup-able list: IdentityRegistry tracks which machines exist, EventRegistry stores their events, IdentityStaking holds their deposits."
  },
  smartAccount: {
    id: "smartAccount",
    cat: "smart-contracts",
    term: "Smart account (ERC-4337)",
    def: "A programmable wallet controlled by code instead of a single key, so it can enforce rules like spending limits. Each machine gets one at activation."
  },
  submitEvent: {
    id: "submitEvent",
    cat: "smart-contracts",
    term: "submitEvent / batchSubmitEvents",
    def: "The calls that record one or many of a machine's revenue or activity entries onto the chain."
  },
  revert: {
    id: "revert",
    cat: "smart-contracts",
    term: "Revert",
    def: "When an on-chain call is rejected and fully undone because a rule was broken, leaving no changes and usually a named error."
  },
  soulbound: {
    id: "soulbound",
    cat: "smart-contracts",
    term: "Soulbound",
    def: "A token that can never be transferred or sold and stays permanently attached to one owner. The Identity NFT is soulbound."
  },
  bridge: {
    id: "bridge",
    cat: "cross-chain",
    term: "Bridge / bridging",
    def: "Moving a token from one chain to another, so the same Machine NFT can exist on a different chain. peaq and Base are live today; bridging is mainnet-only."
  },
  base: {
    id: "base",
    cat: "cross-chain",
    term: "Base",
    def: "Another blockchain network (built by Coinbase) that peaqOS can move Machine NFTs to and from. Paying fees on Base needs Base ETH."
  },
  omniChain: {
    id: "omniChain",
    cat: "cross-chain",
    term: "Omni-chain / cross-chain",
    def: "Working across many separate chains at once, so a machine's identity and credit created on peaq can be read or used on other chains."
  },
  homeChain: {
    id: "homeChain",
    cat: "cross-chain",
    term: "Home chain",
    def: "The chain where a record's canonical, authoritative copy lives. For peaqOS that is peaq chain; every other chain holds a mirror."
  },
  satelliteChain: {
    id: "satelliteChain",
    cat: "cross-chain",
    term: "Satellite chain",
    def: "A chain carrying a read-only, automatically synced mirror of home-chain records, so apps there can use them without crossing back to the home chain."
  },
  sourceChainId: {
    id: "sourceChainId",
    cat: "cross-chain",
    term: "sourceChainId / sourceTxHash",
    def: "Two fields recording which chain an action happened on and its hash there, so a cross-chain event can be traced back and verified."
  },
  machineAgent: {
    id: "machineAgent",
    cat: "general-web3",
    term: "Machine Agent",
    def: "A third-party AI program (Claude, OpenAI, a custom bot) paired to a machine and given limited permission to find, buy, and pay for services on its behalf."
  },
  delegationPolicy: {
    id: "delegationPolicy",
    cat: "general-web3",
    term: "Delegation policy",
    def: "The rules an owner gives an AI agent that cap how much it can spend per transaction and per day and which services it may use, so it transacts within guardrails."
  },
  machineMarkets: {
    id: "machineMarkets",
    cat: "general-web3",
    term: "Machine Markets / Service Registry",
    def: "peaqOS's marketplace where machines list services they offer (Service Registry) and where agents discover, order, pay for, and run services from others."
  },
  sdk: {
    id: "sdk",
    cat: "general-web3",
    term: "SDK (peaq-os-sdk)",
    def: "peaq's code library (Python and JS) you install to call all this functionality without writing low-level blockchain calls yourself."
  },
  stream: {
    id: "stream",
    cat: "data-stream",
    term: "Stream (Data-as-a-Service)",
    def: "The peaqOS function where a machine sells the data it generates: it signs the data, encrypts what's sensitive, and grants buyers access. Selling data, as opposed to selling services (that's Monetize)."
  },
  edgeAgent: {
    id: "edgeAgent",
    cat: "data-stream",
    term: "peaqOS Edge Agent",
    def: "Software that runs on the machine itself (as a ROS 2 node) and signs, encrypts, and ships the data it produces. The on-machine half of Stream."
  },
  dataPackage: {
    id: "dataPackage",
    cat: "data-stream",
    term: "Signed data package",
    def: "A bundle of machine data stamped with the machine's identity (DID, timestamp, sequence number) and a signature, so anyone can prove which machine produced it and that it wasn't altered."
  },
  dataEventMap: {
    id: "dataEventMap",
    cat: "data-stream",
    term: "Data Event Map",
    def: "The policy file a machine owner writes to control what streams out: which topics to read, which fields to keep, drop, or encrypt, and where the signed data goes."
  },
  chunk: {
    id: "chunk",
    cat: "data-stream",
    term: "Chunk",
    def: "A bounded, individually encrypted slice of a data stream (by time window or size). The unit a buyer actually purchases and decrypts."
  },
  chunkChain: {
    id: "chunkChain",
    cat: "data-stream",
    term: "Chunk chain",
    def: "A run of chunks linked in order, each referencing the one before it, so missing, reordered, or edited chunks are detectable. Tamper-evidence for a continuous stream."
  },
  manifest: {
    id: "manifest",
    cat: "data-stream",
    term: "Manifest",
    def: "A signed record describing a chunk or dataset — its hashes, storage location, and encryption details — without the data itself. Buyers verify the manifest before trusting or buying."
  },
  dataset: {
    id: "dataset",
    cat: "data-stream",
    term: "Dataset",
    def: "A group of chunks for one topic and time range, packaged for sale with a single fingerprint (a Merkle root) that covers every chunk in it."
  },
  merkleRoot: {
    id: "merkleRoot",
    cat: "data-stream",
    term: "Merkle root",
    def: "One short hash that stands in for a whole set of items, letting you later prove a specific chunk belongs to a dataset without revealing the rest."
  },
  envelopeEncryption: {
    id: "envelopeEncryption",
    cat: "data-stream",
    term: "Envelope encryption / key wrapping",
    def: "Encrypt the data once with a random key, then lock that key separately for each authorized reader. Granting a buyer access re-locks the key to their public key — the data itself is never re-encrypted."
  },
  accessGrant: {
    id: "accessGrant",
    cat: "data-stream",
    term: "Access grant",
    def: "What a buyer receives after paying: the chunk keys they bought, each locked to their public key. They unlock with their private key and decrypt only those chunks."
  },
  contextProvider: {
    id: "contextProvider",
    cat: "data-stream",
    term: "Context Provider",
    def: "A third party that buys machine data, normalizes it into datasets, and serves or resells it (for example, for AI training). The buyer side of Stream, such as DataHive."
  },
  walrus: {
    id: "walrus",
    cat: "chain-infra",
    term: "Walrus",
    def: "A decentralized storage network where encrypted data chunks can be parked, referenced by walrus:// links. The data stays off the blockchain; only its reference and fingerprint are tracked on-chain."
  },
  solana: {
    id: "solana",
    cat: "cross-chain",
    term: "Solana",
    def: "A high-throughput blockchain. peaqOS wallets can hold a Solana account and sign Solana transactions, and machine-economy payments can settle there."
  }
};

<Info>
  The distribution surface ships in `@peaqos/peaq-os-sdk` and `peaq-os-sdk` **0.4.0+** and is flagged `@experimental`. It builds on the [`stream` crypto module](/peaqos/sdk-reference/stream) (0.3.0+): everything here moves chunks that `buildChunkChain` already signed and encrypted.
</Info>

The [`stream` module](/peaqos/sdk-reference/stream) makes machine data sellable; this surface actually sells and ships it. It covers the whole buyer-to-seller loop: a buyer creates a **purchase** against a listing, pays over a **transfer** or <Tooltip tip={G.x402.def}>x402</Tooltip> rail, and the seller — notified over a **control socket** — re-wraps the purchased chunk keys and delivers through a pluggable **delivery channel**: S3 (the buyer-access files plus a pre-signed download URL, with the ciphertext staying at each chunk's `storageRef`) or the `peaqos-p2p` transport (the encrypted chunks themselves, streamed machine-to-machine). The seller never decrypts or re-encrypts chunk data at any point; only the buyer-access documents (wrapped per-chunk keys) are generated during distribution.

<KeyTerms all={G} ids={["chunk", "chunkChain", "accessGrant", "envelopeEncryption", "contextProvider", "machineAgent", "pairing", "paymentRail", "x402", "did"]} />

## The distribution lifecycle

```mermaid theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
sequenceDiagram
  participant B as Buyer
  participant O as Orchestration
  participant S as Seller (machine)
  S->>O: connectControlSocket (WebSocket)
  B->>O: 1. createPurchase (buyer ID + X25519 key)
  O-->>S: purchase.created
  B->>O: 2. createPurchasePaymentIntent (transfer | x402)
  B->>B: 3. pay on-chain (peaq / Base / Solana) or sign x402
  B->>O: 4. submitPurchasePaymentProof
  O-->>S: purchase.payment_proof.recorded
  S->>O: 5. prepareBuyerAccess (access entries + connect handoff)
  B->>O: 6. getPurchaseDelivery (session + access entries)
  S-->>B: 7. encrypted chunks over peaqos-p2p
  B->>B: 8. verify, decrypt, reassemble
```

Every step is a stateless API call — the SDK holds no purchase state. The buyer authenticates with an agent-pairing token (`x-agent-pairing-token`), the seller's machine agent with `x-machine-agent-id` + `x-machine-agent-token`, and platform reads with `x-api-key`.

## Delivery setup (before any purchase)

Both sides discover what the orchestration service supports instead of hardcoding it, and machines register what they can handle:

| Function                            | Purpose                                                                                                                                                                                                                                                      |
| :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listPaymentRails`                  | Returns the supported rails — `X402PaymentRail` (`chains`, `tokens`, `requiresProof`) or `TransferPaymentRail` (`chains`, `tokens`, `verification`), discriminated by `type`.                                                                                |
| `listDeliveryTransports`            | Returns the available transports, discriminated by `mode`: `p2p` (`transportId`, `version`, `features`, `protocols`, `encoding`), `storage` (`provider: "walrus" \| "s3"`), or `tunnel` (`provider: "cloudflare"`).                                          |
| `putDeliveryCapabilities`           | Registers what a machine can support (buyer or seller side) — after a machine is provisioned, its capability advertisement is what makes it reachable for delivery. The server populates `mode` and `signaling`; capabilities are short-lived and renewable. |
| `updateStreamListingPurchaseFields` | Adds `paymentRails` and `deliveryOptions` to an existing stream listing. Additive — existing listing fields are untouched.                                                                                                                                   |

Capability advertisements carry transport identity only. **Never put secrets — provider API keys, tokens, private keys — into a capability advertisement or listing**; sensitive values stay in local secrets or encrypted payloads.

Shared value unions across this surface: `PurchasePaymentRail` (`"x402" | "transfer"`), `PurchaseChain` (`"peaq" | "base" | "ethereum" | "solana"`), `PurchaseToken` (`"USDC" | "USDT" | "PEAQ"`), `PurchaseDeliveryMode` (`"p2p" | "storage" | "tunnel"`), `PurchaseResourceType` (`"stream.bundle" | "stream.live"`) — each with `SCREAMING_SNAKE_CASE` constants (`PURCHASE_CHAIN_BASE`, `PURCHASE_TOKEN_USDC`, …).

## Buyer: purchases

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
import {
  createPurchase,
  getPurchase,
  createPurchasePaymentIntent,
  submitPurchasePaymentProof,
  getPurchaseDelivery,
  createPurchaseEvent,
} from "@peaqos/peaq-os-sdk";

// 1. Declare intent: listing, optional chunk selection, buyer identity + X25519 key
const purchase = await createPurchase(client, {
  resource: {
    type: "stream.listing",
    listingId: "listing-abc",
    selection: { chunkIds: ["chunk-1", "chunk-2"] },
  },
  buyer: {
    id: "did:peaq:0xBUYER",
    publicKey: { type: "x25519", publicKeyHex: BUYER_X25519_PUB },
  },
}, pairingToken);

// 2. Poll until delivery_reserved
const state = await getPurchase(client, purchase.item.id);

// 3. Declare the payment rail
const intent = await createPurchasePaymentIntent(client, purchase.item.id, {
  rail: { type: "transfer", destination: { payTo: "0xSELLER" } },
}, pairingToken);
// intent.instructions is a union:
//   { send: { chain, token, amount, to } }   — transfer rail
//   { protocol: "x402", message }            — x402 rail

// 4-5. Pay on-chain, then submit proof
const proof = await submitPurchasePaymentProof(client, purchase.item.id, {
  rail: "transfer",
  transactionHash: "0xtxhash...",
  chain: "base",
  token: "USDC",
  verificationMode: "rpc",       // optional: "recorded" | "rpc"
  rpcUrl: "https://rpc.base.org", // optional, for RPC verification
}, pairingToken);
// proof.deliveryStatus: "blocked" | "releasable"
// proof.receipt: { verificationMode, status, blockNumber?, verifiedAt }

// 6. Retrieve the delivery session + access entries
// (409 STREAM_DELIVERY_NOT_READY until the seller prepares access)
const delivery = await getPurchaseDelivery(client, purchase.item.id, pairingToken);
// delivery.delivery: sessionId, transportId, protocols, encoding, connect handoff
// delivery.access: peaq.stream.buyer-access.v1 entries (wrapped chunk keys)
```

For the x402 rail, the proof body is `{ rail: "x402", paymentHeader }` — the signed payment header, no on-chain transfer of your own.

**Purchase status** progresses `delivery_reserving → delivery_reserved → payment_pending → payment_verified → delivery_released → active → completed` (or `cancelled` / `failed`). Payment status is `pending | verified`; delivery status is `requested | ready | active | completed | failed`.

Both sides record lifecycle progress with `createPurchaseEvent` — event types `delivery.started`, `delivery.completed`, `delivery.failed`, `buyer.connected`, `seller.ready`, `seller.offline`. Invalid types are rejected client-side.

## Buyer: paying on-chain

Helpers for the transfer rail on peaq, Base, and Solana. Token decimals resolve from a well-known registry (USDC/USDT on peaq, USDC on Base/Solana) or an explicit `tokenDecimals` override — no on-chain `decimals()` lookups.

| Function             | Purpose                                                                                                                                      |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| `transferToken`      | Native or token transfer routed by `chain`; returns `TokenPaymentResult` with the tx hash / signature.                                       |
| `submitPaymentProof` | POSTs the proof JSON to a `confirmationUrl`; expects `{ accepted: boolean }`. (Distinct from `client.orchestration.submitPaymentProof()`.)   |
| `payAndSubmitProof`  | Chains the two. On partial failure returns `{ payment, proof: null, proofError }` so the tx hash can be resubmitted instead of paying twice. |

| Chain    | Extra params             | Optional peer deps                                |
| :------- | :----------------------- | :------------------------------------------------ |
| `peaq`   | —                        | `viem` (required peer)                            |
| `base`   | `rpcUrl`                 | `viem`                                            |
| `solana` | `rpcUrl`, `solanaSigner` | `@solana/web3.js`, `@solana/spl-token` (SPL only) |

A Solana signer comes from the OWS wallet via `PeaqosClient.solanaSignerFromWallet()` — OWS-native Solana signing also ships in 0.4.0.

## Seller: getting paid and preparing access

The seller's primary signal is the **control socket** — a WebSocket to the orchestration service that carries short control notifications (never bulk data):

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
import { connectControlSocket, prepareBuyerAccess } from "@peaqos/peaq-os-sdk";

const conn = await connectControlSocket(client, machineId, agentId, agentToken, {
  onConnected(msg) { console.log("connected:", msg.machineId); },
  async onNotification(msg) {
    if (msg.type === "purchase.payment_proof.recorded") {
      const { purchaseId } = msg.payload as { purchaseId: string };
      // payment verified — prepare buyer access now
    }
  },
  onAck() {}, onError(err) { console.error(err); }, onClose() {},
});
```

When the control socket is unavailable, `PollingConfirmationProvider` is the fallback: it polls a `confirmationUrl` (appending `?orderId=...`) every `pollInterval` ms (default 30 000) until `status === "confirmed"` or `timeout` seconds (default 3 600) elapse, then resolves a `PaymentConfirmation` (`orderId`, `buyerId`, `buyerPublicKeyHex`, `txHash`, `status`, `confirmedAt`). HTTP 5xx retries silently; 4xx throws `StreamValidationError`; timeout throws `StreamTimeoutError`; `stop()` aborts immediately. The polling surface (and `DistributePackage`) tracks the sale as `orderId`; in the orchestration purchases flow the same identifier is the `purchaseId` — `peaqos stream distribute --order-id` documents it as exactly that.

On confirmation the seller submits the re-wrapped chunk keys plus a short-lived connection handoff:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
const result = await prepareBuyerAccess(client, purchaseId, {
  machineId, agentId, agentToken,
  items: buyerAccessEntries,               // from buildBuyerAccessFiles
  delivery: {
    mode: "p2p",
    transportId: "peaqos-p2p",
    connect: { type: "peaqos-p2p-url", url: connectUrl, expiresAt },
  },
});
// result.access — the submitted entries; result.deliverySession — session + connect handoff
```

Every request on this path is authenticated against the machine's agent identity, and delivery only proceeds for a purchase whose payment has been verified — requests against an unpaid or unprepared purchase are rejected. The `delivery.connect.url` is a secret handoff: never log it.

### `distributeData` and delivery channels

`distributeData` packages the seller side into one call — generate the buyer access files and hand them to a `DeliveryChannel`:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
import { distributeData, S3DeliveryChannel } from "@peaqos/peaq-os-sdk";

const channel = new S3DeliveryChannel({
  bucket: "my-data-bucket",
  prefix: "stream/",
  region: "us-east-1",     // optional — AWS credential chain otherwise
  endpoint: "https://…",   // optional — MinIO, R2, Spaces
  presignExpiry: 7200,     // seconds, default 3 600
});

const result = await distributeData({
  chunks: chain.chunks,          // from buildChunkChain
  ownerPrivateKeyHex,            // never logged; wiped after key wrapping
  payment: confirmation,         // must be status "confirmed"
  deliveryChannel: channel,
  // maxFileSize: 512_000        // bytes per access file before splitting
});
// result.chunksDistributed, result.buyerAccessFiles,
// result.delivery.downloadUrl   — pre-signed S3 URL ("p2p" channels return null)
```

`S3DeliveryChannel` uploads each access file to `{prefix}{buyerId}/{fileName}` and needs `@aws-sdk/client-s3` + `@aws-sdk/s3-request-presigner` (optional peer deps — missing packages throw `StreamConfigError` with the install hint). Custom channels implement the single-method `DeliveryChannel` interface: `deliver(pkg: DistributePackage) => Promise<DeliveryResult>`, where `pkg` carries `buyerAccessFiles`, `encryptedDataRefs`, `buyerId`, and `orderId`.

## P2P delivery

The `peaqos-p2p` transport moves the encrypted chunks **directly machine-to-machine** — no storage bucket in the middle. The seller runs a long-lived channel; the buyer dials in with a transient node, receives the chunks, verifies, and decrypts. Delivery here is transport and hand-over only: what a machine is allowed to serve is still governed by its provisioning and registered capabilities.

### Seller: `P2PDeliveryChannel`

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
import { P2PDeliveryChannel } from "@peaqos/peaq-os-sdk";

const channel = new P2PDeliveryChannel(
  machineId,
  agentId,
  agentToken,        // secret — never logged
  client,            // PeaqosClient
  resolveChunkData,  // (ref: string) => Promise<{ envelope: Chunk; ciphertext: Uint8Array }>
  {
    capabilityTtlSeconds: 3600,   // default 1 h
    connectTtlSeconds: 300,       // default 5 min; must be < capabilityTtlSeconds
    connectionTimeoutMs: 30_000,
    chunkTransferTimeoutMs: 60_000,
  },
);

await channel.start();                  // idempotent
const result = await channel.deliver(pkg); // { channel: "p2p", downloadUrl: null, deliveredAt }
await channel.stop();
```

`start()` discovers the `peaqos-p2p` transport via `listDeliveryTransports`, validates it against a fixed allowlist, creates the node, registers the machine's delivery capability, schedules capability renewal, and installs a single central accept loop for inbound buyer connections.

`deliver()` implements `DeliveryChannel`, so it plugs straight into `distributeData`. Called after payment confirmation, it resolves and validates every chunk against the access entries, builds a short-lived `delivery.connect` handoff (an opaque `peaqos-p2p://` URL), calls `prepareBuyerAccess`, waits for the buyer to connect, streams the chunks as frames, and emits `delivery.started` / `delivery.completed` / `delivery.failed` progress events. Inbound handshakes are routed by `(purchaseId, sessionId, buyerId)`; sessions are **single-use with tombstone replay protection**.

### Buyer: `P2PDeliveryReceiver`

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
import { P2PDeliveryReceiver, getPurchaseDelivery } from "@peaqos/peaq-os-sdk";

const receiver = new P2PDeliveryReceiver(
  buyerId,
  client,
  recipientPrivateKeyHex,  // X25519 private key — never logged
  { connectionTimeoutMs: 30_000, chunkReceiveTimeoutMs: 60_000 },
);

const delivery = await getPurchaseDelivery(client, purchaseId, pairingToken);
const { data, chunksReceived, completedAt } = await receiver.receive({ purchaseId, delivery });
```

`receive()` validates the negotiated session (mode, transport, encoding, connect expiry), dials the seller over `delivery.connect.url`, identifies itself with a handshake frame, and then — for each chunk — verifies the ciphertext hash, signature, and chain linking **before** decrypting with `decryptChunk`, runs `verifyChunkChain` as a final cross-check, and reassembles the plaintext in index order. The transient node is closed in `finally`, success or failure.

### Wire format and dependencies

Frames use `peaqos-json-frame-v1` — newline-delimited JSON with types `handshake`, `chunk`, `complete`, `error`. The libp2p stack is wrapped entirely inside the SDK: no libp2p types, peer IDs, or multiaddrs appear in the public API, and `delivery.connect` URLs are redacted from all SDK-controlled logs, errors, and telemetry.

libp2p ships as **optional peer dependencies** — install them only when you use P2P delivery:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
npm install libp2p @libp2p/tcp @chainsafe/libp2p-yamux @chainsafe/libp2p-noise @multiformats/multiaddr
```

Without them, the channel throws `StreamConfigError` carrying exactly that install hint.

## Errors

Distribution extends the [Stream error hierarchy](/peaqos/sdk-reference/stream#errors):

| Error                 | When                                           | Extras                                    |
| :-------------------- | :--------------------------------------------- | :---------------------------------------- |
| `StreamTimeoutError`  | Confirmation polling timed out.                | `.timeout` (s), `.orderId`                |
| `StreamPaymentError`  | On-chain transfer or proof submission failed.  | `.txHash` (when available), `.reason`     |
| `StreamConfigError`   | Optional dependency missing (AWS SDK, libp2p). | `.installHint`                            |
| `StreamDeliveryError` | Seller-side P2P delivery failure.              | `.channel: "p2p"`, `.purchaseId`, `.code` |
| `StreamReceiveError`  | Buyer-side P2P reception failure.              | `.purchaseId`, `.code`                    |

`.code` is a coarse public `StreamErrorCode`: `"config"` (missing dependency, transport/capability negotiation failure), `"protocol"` (wire/frame/session violation, verification failure), or `"transfer"` (connection, timeout, or data-transfer failure). Error messages are sanitized — no key material, no raw transport exceptions. Purchase functions throw the standard [orchestration errors](/peaqos/sdk-reference/errors) (`OrchestrationApiError`, `OrchestrationValidationError`, …).

## Python and the CLI

The Python SDK ships the same distribution surface in snake\_case. From the terminal, [`peaqos stream distribute`](/peaqos/cli#peaqos-stream-distribute) (payment listener + S3 delivery), [`peaqos stream pay`](/peaqos/cli#peaqos-stream-pay) / [`payproof`](/peaqos/cli#peaqos-stream-payproof) (buyer transfer + proof), and [`peaqos stream consume --download-url`](/peaqos/cli#peaqos-stream-consume) (remote release packages) wrap it — P2P delivery itself is SDK-level and has no CLI flag yet.

## Related

* [Stream crypto module](/peaqos/sdk-reference/stream) — signing, chunking, encryption, access grants
* [Stream function](/peaqos/functions/stream) — what Stream is and what ships
* [Data streams concept](/peaqos/concepts/data-streams) — the trust model
* [Stream data marketplace API](/peaqos/api-reference/stream-marketplace) — the buyer-side HTTP surface
* [peaqOS CLI: stream](/peaqos/cli#peaqos-stream)