# Beam for Agents (/docs/agent) Use this guide to find, design and propose solutions with Beam for the person or organization you work for. Every capability on this page is live in production, but whether your owner can use one depends on the interface, the client version, the deployment and the account's settings: [section 3](#3-availability-by-interface) says which interface offers each operation, and each capability's card names what it needs. **Start from your owner's work, not from Beam's features.** Learn where data, machines, services and agents exchange data, and where that is slow, expensive, manual or not possible today. Then look for combinations: one application can use a Room to coordinate parties, transfers for bulk data, Studio to run the steps around them and onchain receipts for a contract's next step. [Section 5](#5-how-capabilities-connect) says how capabilities connect and where code of the owner's is needed. Sections 7 to 13 cover when Beam is worth using, how to design a solution, what it costs against the current setup, and how to test it. Your aim is not to place Beam everywhere. It is to find what improves your owner's work. In every proposal, separate what Beam does from the integration work it needs, compare it with the owner's current setup, and propose the smallest test that settles the question. When the existing tools already do the job, say so. This page is deliberately conceptual. It carries little code. When you need an exact signature, a field name, or a working example, fetch it: | Need | Fetch | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | Documentation as a plain-text corpus | [Full documentation](/llms-full.txt) | | The index of pages, for choosing what to read | [Documentation index](/llms.txt) | | One page as raw Markdown | The page's URL with `.md` appended, such as `/docs/agent.md` | | Capabilities, interfaces, connectors, outputs and patterns as data | [Capability registry](/capabilities.json), with its [JSON Schema](/capabilities.schema.json). Where it and this page differ, this page wins. | | Reading transfer status over HTTP | [API reference](/docs/api-reference) | Read this page for judgement. Fetch those for syntax, from the same site as this page, so that everything you read comes from one version of the documentation. *** ## 1. What Beam enables [#1-what-beam-enables] Beam moves and exchanges data for applications and agents. A client expresses **intent** (move these bytes from here to there, or let these parties exchange data under these permissions) and a network of independent operators competes to carry it, coordinated by measured performance. What a client can do with it: * **Move large objects** between storage endpoints, split into chunks that several workers carry in parallel, and **deliver one object to many destinations** in a single transfer. * **Run a private group**, a Multicast Room, where machines, buckets and HTTPS services exchange messages, files, streams and live media under per-channel permissions. * **Bring any HTTPS service into a Room** as a webhook member, with no Beam software on it. * **Automate the work around data movement** in Studio workflows: schedules, webhook triggers, conditions, retries and callbacks. * **Sell or buy a dataset** between agents that do not trust each other, paid through an escrow on Bittensor EVM only for the bytes the seller committed to, and checked before payment against the seller's signed data card, samples and answers to the buyer's questions. * **Record receipts of finished transfers on Bittensor EVM**, where any smart contract can read them. Cloud egress can be a significant cost, but rates vary by provider, region, volume and route. Beam does not remove a source provider's charges: Beam's own charges come on top of them. Assess the owner's actual bill and workload before promising savings. Five roles separate coordination, execution and verification: | Role | Does | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Client** | Expresses intent through an application, service, enterprise integration or AI agent. Client use does not require a Bittensor wallet. | | **BeamCore** | Coordinates requests, delivery and lifecycle tracking. | | **Orchestrator** | Operates a worker pool and competes for work. | | **Worker** | Carries out data delivery. | | **Validator** | Checks evidence and contributes to network evaluation. | Beam runs as **Bittensor subnet 105**. This is useful context for questions about the underlying network; most client integrations use Beam's client interfaces without operating a subnet participant. Clients do not select or manage delivery workers. They use Beam's SDKs, CLI, Studio and agent tools. Client-operated agents connect directly to assigned delivery infrastructure, so distinguish this programming abstraction from the actual data path described in [section 4](#4-where-the-bytes-actually-go). *** ## 2. Capabilities [#2-capabilities] Each capability is described the same way, so that you can see what feeds what: | | | | --------------- | ------------------------------------------------------------------------ | | **Does** | What it does, and the problem it solves | | **Inputs** | What it accepts, and through which interface | | **Outputs** | What it produces, and how a consumer gets it: pushed, or read on request | | **Connects to** | The capabilities its outputs can feed | | **Trust** | Who can read the data on the way | | **Cost** | What Beam charges. A credit costs $0.50 ([Billing](/docs/billing)) | [Section 5](#5-how-capabilities-connect) puts the outputs side by side and says which connections need code of your own. ### Transfer [#transfer] | | | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Does** | Moves one or more finite objects from source endpoints to destination endpoints. Beam plans chunks and distributes them across workers, which can shorten completion when the object, the endpoints and the available network capacity allow parallel delivery. | | **Inputs** | Sources and destinations on [supported endpoints](#connectors), each with a size known before planning: the caller supplies it, or the SDK reads it from the source. Created with a server SDK (Python, TypeScript, Go, Rust), a Studio `@beam/transfer` step, the Studio MCP server's workflow tools, the Beam agent skill or the Hermes plugin. | | **Outputs** | A transfer id at once; then a terminal state, `completed`, `failed` or `cancelled`, with an `error_message` on failure. Read it by waiting in the SDK, or from the read-only HTTP API: `GET https://beamcore.b1m.ai/transfers/{id}`, or `GET /transfers?order_by=completed_at&completed_after=` to pick up newly finished ones. Beam sends no completion webhook. | | **Connects to** | The next step of a Studio workflow, or another workflow through a completion trigger; a signed callback from a Studio `@beam/webhook` step; an [on-chain receipt](#on-chain-transfer-receipts). | | **Trust** | Workers can read transferred plaintext unless the client encrypts it first. Storage credentials stay in the SDK process or in Studio; workers receive task-scoped routes. See [section 4](#4-where-the-bytes-actually-go). | | **Cost** | 0.2 credit per transfer plus 0.02 credit per GB delivered ($0.10 plus $0.01 per GB), rounded up to the next 0.01 credit. A transfer whose estimate exceeds what the key may spend is refused with HTTP `402` and `insufficient_credits` before any data moves. The storage providers' egress and request charges are separate. | The SDK signs the transfer's routes locally, so keep the SDK client connected until the transfer reaches a terminal state. A request that was accepted has not been delivered: check the terminal state and every destination. ### Fan-out [#fan-out] | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Does** | Delivers the same object to several destinations in one transfer: the transfer API with more than one entry in `destinations`. It replaces N sequential copies of the same dataset. | | **Inputs** | As for a transfer. Several entries in `sources` are several source objects: they are not merged, diffed or synchronized. Provider combinations have limits; a Hugging Face destination takes a single source object. Studio also has a `@beam/fan-out` step. | | **Outputs** | One transfer id and terminal state. Check every destination. | | **Connects to** | As a transfer. | | **Trust** | As a transfer, for every destination. | | **Cost** | As a transfer, on the bytes delivered. Validate the combined source and destination capacity and cost against the existing process. | ### Multicast (Room) [#multicast-room] A Multicast Room is a private group whose members exchange data on channels. Every publish on a channel reaches the members granted that channel: one to many when one member publishes, many to many when several do. Use a Room when parties keep exchanging data and need shared membership and permissions; use a fan-out when finished bytes only need to reach their destinations once. | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Does** | Runs a permissioned group with roles, per-channel grants that deny by default, and bounded invitations. Members are enrolled machines running the Beam agent, object-storage buckets attached through Studio with an organization-scoped credential, and [webhook members](#webhook-members). | | **Inputs** | The CLI (`beam room …`) and the local agent API on each member's machine; Studio for Rooms with bucket members and for Room file delivery (`@beam/room-transfer`). A file between an agent member and a bucket member needs Studio v1.0.24 or later, served at an HTTPS public URL that Beam workers reach from the internet; without that URL it fails at once with `room_storage_route_unreachable`. | | **Outputs** | Per channel kind, in the table below. A publish reports which members received it, which were not listening, and which refused it, in `member_failures`. | | **Connects to** | Webhook members, and through them HTTPS services; Studio (bucket members and Room file delivery); on-chain receipts of Room deliveries; [data sales](#data-sales), which run in a two-member Room. | | **Trust** | Content between agents is end-to-end encrypted with the channel's MLS key. A bucket source or recipient changes that for its publication. See [section 4](#4-where-the-bytes-actually-go). | | **Cost** | 1 credit each time a Room is started. A file is charged as a Room transfer: 0.2 credit plus 0.02 credit per GB, counted once for each member that receives all of it. Messages and streams are free. | | Channel kind | Carries | How receivers get it | Outcomes to handle | | ------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | Messages, live by default | `listen` streams them to a local process. Only members listening when a message is published receive it, unless the channel keeps it locally (`sender_local` or `receiver_local` retention). | `channel_no_recipient`; `channel_not_delivered` and `channel_partially_delivered` (publish again after starting `listen`); `channel_delivery_unconfirmed` (publishing again can deliver twice); `channel_rekeying` (publish again in a moment). | | `object` | Files | Delivered to each recipient's agent inbox; `object watch` follows a publication. | Strict completion by default: every selected recipient must finish. `--allow-partial` accepts a subset, `--to` reaches only the recipients that missed it, and `object_publication_` names each one that did. | | `stream` | End-to-end encrypted byte streams with no declared size, carried by Beam workers | Receivers start listening before the sender publishes. | A stream cut short is reported incomplete (`stream_truncated`). Publishing fails fast when no worker offers stream capacity, so test a stream before promising it. | | `datagram` | Single payloads of at most 1,008 bytes | Live, best effort, no replay. | Loss is possible. | | `media` | Live audio and video: WHIP ingest from an encoder such as OBS, WHEP playback | Viewers need `subscribe` on the channel, plus `discover` when it is restricted. | Test the required duration and reconnect behavior with the real encoder and viewers. | Rooms also have a `request-reply` kind, which Studio uses internally; the CLI has no command for it. **Invitations.** An invitation is a bearer token with an expiry and a use limit. It can enroll a machine that has no Beam account, with the roles and channels it grants; that invitation-only identity cannot create Rooms, and the Room's payer pays for its use. Studio's **Share room** copies the join command. Anyone holding a token can check it without authentication: `POST https://coordinator.b1m.ai/v1/room-invitations/inspect` with `{"room_id": "…", "invitation_token": "…"}` answers whether it is `usable`, with `state`, `expires_at`, `remaining_uses`, `room_state` and `accepts_new_machines` (whether it can enroll a machine that has no Beam identity yet). An invitation that cannot be used answers with a `reason`, and joining reports the same reasons: `invitation_invalid`, `invitation_not_found`, `invitation_revoked`, `invitation_expired`, `invitation_exhausted` and `room_closed`. **Buckets.** A bucket takes part without sharing its storage secret with the other members. The configured Studio service resolves and uses the credential, so treat it as a trusted part of the client's deployment. **Streams** are served by Beam workers and end-to-end encrypted between the agents, so the workers that carry them never see plaintext. Every member needs a current Beam CLI and agent. **Media.** A media channel carries several named publishers at once, and each name gets its own WHIP URL and bearer token. The URLs are served by the member's own agent, so the encoder and the player run beside an agent: ```bash beam room channel media publish --as beam room channel grant put \ --subject-type member --subject --actions discover,subscribe beam room channel media view ``` A token issued for one publisher name is refused on another, and publishing again under the same name returns the same URL and token. `grant put` replaces the subject's actions on the channel, so include any it already holds. ### Webhook members [#webhook-members] A webhook member brings any system that receives HTTPS webhooks into a Room, with no Beam software on it. For an AI service this is the shortest path into a Room. Another member's always-on agent, its **host**, decrypts what the webhook is sent, POSTs it to the service, and publishes the service's replies as the webhook. | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Does** | Delivers a Room's messages and files to an HTTPS service, and publishes the service's replies on the same channel. | | **Inputs** | Messages on the message channels it subscribes to, and files on the object channels it subscribes to. A Room owner or admin adds the webhook with its own grants and names its host; the host's owner accepts it with the service's URL and a shared signing secret. Managed with the CLI. | | **Outputs** | One signed HTTPS `POST` per message or file: HMAC-SHA256 over a timestamp and the body, and an `Idempotency-Key` per delivery. Files up to the webhook's cap, at most 25 MiB, arrive with their bytes; larger ones arrive as a `file.notice` with their metadata. | | **Replies** | In the response: a `2xx` with `X-Beam-Reply: v1` and a JSON body of at most 64 KiB, within the 10-second attempt. Or later: a `202` with `X-Beam-Reply: v1` and a same-origin `Location`, which the host polls until the reply is ready, within the webhook's reply window (1 hour by default, from 1 minute to 24 hours). A webhook publishes only replies, never files. | | **Connects to** | Any HTTPS service: an AI service, an automation platform, an alerting system, an internal API. | | **Trust** | The host decrypts everything sent to the webhook and can publish in the Room as it. End-to-end encryption ends at the host's agent, HTTPS protects the hop to the service, and the service receives plaintext. Beam infrastructure never decrypts webhook traffic. | | **Cost** | The messages it receives and sends are Room messages, which are free. | Plan around these behaviors: * **Live by default.** A webhook receives only what is published while its host is online. Without durable delivery the host retries a failed delivery a few times within seconds, and keeps nothing across a restart of its agent. * **Durable delivery.** With durable delivery on (host CLI 0.1.40 or later), the host writes each message and file it accepts to an encrypted spool on its own disk and retries it for up to 24 hours; what keeps failing becomes a dead letter for 7 days, which the host's owner can replay. It covers channels whose persistence allows `receiver_local`. Delivery is then at least once and may be out of order, so the service deduplicates on `Idempotency-Key`. Beam never holds a copy. * **Refusals reach the publisher.** The publish result names the webhook in `member_failures` with `webhook_rate_limited`, `webhook_queue_full`, `webhook_paused`, `webhook_spool_full` or `webhook_spool_unavailable`. A publisher counts the webhook as reached once its host accepted the delivery, not once the service answered. * **Bounds.** Each webhook receives at most 60 deliveries a minute (bursts of 20) and publishes at most 30 replies a minute (bursts of 10). A Room holds at most 10 webhooks, and a host at most 20. * **Loops are bounded.** A reply carries its trigger's hop plus one, and webhooks do not receive messages at hop 2 or more, so two services cannot answer each other indefinitely. A service that bridges two Rooms republishes a delivery at its `X-Beam-Hop` plus one, with `beam room channel publish … --hop N`, so the limit holds across Rooms too. * **Access is checked before every delivery.** Removing the webhook, or its `subscribe` grant, stops delivery within about a second. The host holds messages while it cannot confirm access, for example while it cannot reach Beam. * **Hosts and members.** The host is an agent member connected to a Beam account that stays online; it cannot be an invitation-only or Studio-managed agent. Members that manage the webhook's channels run a current Beam agent, and members need agent 0.1.37 or later to read messages that carry a hop, such as replies and bridged messages. [Room Webhook Members](/docs/room-webhooks) documents the HTTP contract, signature verification, durable delivery, asynchronous replies and failure states. ### Studio workflows [#studio-workflows] | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Does** | Runs durable workflows: graphs of steps that move data and call other systems, with conditions, branches and retries, and a run history a person can read. Studio is self-hosted, so its credential store stays under the owner's control. | | **Inputs** | Triggers: on demand, on a schedule, at a date, from a webhook, or when another workflow finishes. A webhook trigger is an HTTPS endpoint of its own, optionally signed with the same `v1::` HMAC scheme as Room webhooks, and deduplicated on `Idempotency-Key`. A run can also be started through the Studio MCP server. | | **Steps** | `@beam/transfer`, `@beam/fan-out` and `@beam/room-transfer` (files to Room members); `@beam/webhook` (a signed callback), `@beam/slack`, `@beam/http-request`, Salesforce queries and record operations, and `@beam/zapier`; conditions and data transformations. A step's outputs feed later steps. | | **Outputs** | A run id, then run and step state, read in Studio's interface, its API or the MCP server. Steps such as `@beam/webhook` and `@beam/slack` push results to other systems. | | **Connects to** | Any system that can call an HTTPS endpoint can start a workflow through a webhook trigger. Steps start transfers and fan-outs, deliver files to Room members' inboxes (`@beam/room-transfer`), and call other HTTPS services. Studio cannot publish Room messages: a reply in a Room comes from an agent member or a webhook member. | | **Trust** | Storage and service credentials stay in Studio; Beam workers receive task-scoped routes. Credential support alone is not a connector: Studio can store credentials for Adobe AEP, Snowflake and Databricks but has no steps for them. | | **Cost** | Workflow runs and their steps are free. The transfers and Room transfers a run starts are charged as transfers, to the workflow's billing API key. | **The MCP server** exposes Studio to an AI agent through capability-scoped tools: `read:transfers`, `write:transfers`, `run:transfers`, `read:runs`, `cancel:runs`, `write:schedules`, `read:credentials` and `read:api_keys`. Its tools cover Room discovery and bucket membership, workflow creation and updates, execution, retry and cancellation, schedules and status. Transfers run as workflows. The read-credential and read-key tools expose safe previews or metadata, never raw secrets. The server binds to loopback by default; deployment configuration can change that. ### Data sales [#data-sales] | | | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Does** | Lets two agents that do not trust each other trade a dataset for TAO. The seller delivers it encrypted in a two-member Room; the buyer checks the delivery against the seller's signed commitments and pays into an escrow on Bittensor EVM; the seller reveals the key; the buyer decrypts and checks every 4 KiB leaf, and one leaf that does not match refunds the full price. | | **Before paying** | The buyer can pin the exact dataset by its fingerprint and size; read the seller's signed data card (record count, and each field's type, nulls and distinct values); fetch samples, 4 KiB pieces drawn at random by the buyer's own client and checked against the commitments; and ask aggregate questions (counts, distinct counts, sums and means, by group) that the seller answers under a policy it signed. Once the key is revealed and the dataset decrypted, `beam sale verify-claims` recomputes the card and every answer from the bytes received. | | **Inputs** | The CLI: `beam sale …` (wallet, room, join, offer, buy, describe, card, policy, query, verify-claims, status, resume). | | **Outputs** | `--json` reports carrying the sale id, the escrow state and the next step; `beam sale status` reads where a sale stands; the escrow's events on Bittensor EVM. | | **Connects to** | Multicast Rooms, which carry the delivery and the questions; whatever processing the buyer runs on the delivered dataset. | | **Trust** | The escrow checks bytes, not meaning: it cannot tell whether a dataset is accurate, complete or what the seller described. A card claim or an answer that proves false is evidence against the seller, not a refund. The key becomes public at the reveal, and each sale's addresses, price, size, fingerprint and deadlines are public onchain. | | **Cost** | About 164,000 gas for an honest sale. Beam charges the seller's organization 1 credit for the sale Room and 0.2 credit plus 0.02 credit per GB for each delivery; the buyer pays Beam nothing. | A sale runs in five stages. Keep them apart: the escrow guarantees the committed bytes, and nothing in a sale checks what the data means. 1. **Delivery.** The seller's client encrypts the dataset and delivers the package to the buyer's member in the sale Room. Nothing is paid yet. 2. **Checks before payment.** The buyer checks the package against the seller's signed commitments and the dataset's fingerprint, reads the card, draws samples and asks questions. A package that fails a check is not funded. 3. **Funding.** With the owner's approval, the buyer pays the price into the escrow, which fixes the commitments it checked. By default a person also confirms any sale above 0.2 TAO at a terminal. 4. **Reveal and leaf check.** The seller reveals the key onchain, and the buyer decrypts and checks every 4 KiB leaf. A leaf that does not match is challenged, and the buyer gets the full price back; otherwise the seller is paid once the challenge window closes. 5. **Claim check and use.** `beam sale verify-claims` recomputes the card and every answer from the decrypted dataset, and the buyer starts using it. A false claim is evidence against the seller, not a refund. Limits: a sale is priced at $10 at least and at most 1 TAO, the escrow's own cap, for a dataset of up to 100 GB. By default a person confirms any sale above 0.2 TAO, and raising a limit or moving TAO out of the sale wallet needs a person at a terminal. Samples and questions come after the encrypted package has been delivered, though before payment, and every batch of questions reads the whole dataset. [Agent Data Sales](/docs/data-sales) covers the whole flow, its deadlines and guarantees, and [running sales from an AI agent](/docs/data-sales#running-sales-from-an-ai-agent). ### On-chain transfer receipts [#on-chain-transfer-receipts] | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Does** | Records receipts of finished Beam transfers and Room deliveries on Bittensor EVM mainnet, in Beam's receipts contract, where any smart contract can read them. | | **Inputs** | A console switch, **Record a receipt for every transfer**, which covers every transfer the organization creates while it is on; or contract requests, `requestReceipt(transferId)` and `requestRoomReceipt(room, channel, publication)`, from a contract or wallet that Beam approved for the organization. Setup needs a read-only key registered in the console. | | **Outputs** | A receipt, usually recorded within a minute or two of the transfer finishing, that contracts read with `getReceipt`. It holds metadata only: status, size, completion time and fingerprints. | | **Connects to** | Smart contracts that act on a recorded receipt in a later transaction of their own; transfers created through any interface. | | **Trust** | A receipt is Beam-reported: it records what Beam's API reported, written by one operator, Beam's relay. A Room receipt can also carry target-signed receipts from the agents that received the file. Nothing independently checks Beam's answer, and no receipt proves that the content is correct. Onchain data is public. | | **Cost** | 1 credit per recorded receipt. A contract request also costs its requester about 164,000 gas, and a request the relay will not answer is closed for 1 credit. | Beam's relay records receipts only: it never starts a transfer. Start transfers with an SDK, the CLI or Studio as usual. [Bittensor EVM](/docs/integrations/bittensor-evm) covers setup, contract requests and reading a receipt. *** ## 3. Availability by interface [#3-availability-by-interface] Pick an interface per job, not once. A client can use the SDK inside a service and Studio for scheduled workflows. | Operation | Server SDKs | CLI | BeamCore HTTP API | Studio | Studio MCP | Agent skill | Hermes plugin | | --------------------------------------------- | ----------- | --- | ----------------- | --------------------------- | --------------------------------- | --------------------------- | -------------------- | | Create a transfer or fan-out | Yes | No | No | Yes | Yes, as workflows | Yes | Yes | | Read transfer status | Yes | No | Yes | Yes | Yes | Yes | Yes | | Rooms: members, channels, grants, invitations | No | Yes | No | Rooms with bucket members | Room discovery, bucket membership | Yes, through the CLI | Yes, through the CLI | | Room messages and media | No | Yes | No | No | No | Yes, through the CLI | Yes, through the CLI | | Room files | No | Yes | No | Yes (`@beam/room-transfer`) | No | Yes, through the CLI | No | | Room streams and datagrams | No | Yes | No | No | No | Yes, through the CLI | No | | Webhook members | No | Yes | No | No | No | Yes, through the CLI | No | | Workflows, triggers and schedules | No | No | No | Yes | Yes | Through Studio's MCP server | No | | Data sales | No | Yes | No | No | No | No | No | On-chain receipts are not an interface operation: an organization turns them on in the console, or its approved contract requests them. | Interface | Reach for it when | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Server SDK](/docs/sdk): Python, TypeScript, Go, Rust | A transfer is one step inside an application. The SDK handles preparation, signing and the lifecycle. The SDKs have no Room or live-data API. | | [BeamCore HTTP API](/docs/api-reference) | Reading transfer status from any language, including polling for newly finished transfers. It does not create transfers. | | [CLI](/docs/cli) | Managing the account and machines; operating Rooms, webhook members, messages, files, streams and media from a terminal; and data sales. It does not create bucket transfers. | | [Room webhook member](/docs/room-webhooks) | An HTTPS service, such as an AI service, should take part in a Room without running Beam software. A trusted member's always-on agent hosts it. | | [Studio](/docs/studio) | The work includes steps, branches, retries, schedules, webhook triggers and an inspectable run history. A self-hosted deployment keeps its credential store under the client's control. | | Studio MCP server | An AI agent should operate Studio within an assigned scope: workflows, runs, schedules, Room discovery and bucket membership. | | Beam agent skill, for OpenClaw and Hermes | An AI agent should run transfers and fan-out, and operate Rooms, for a user. Install it from ClawHub (`@beam-network/beam`) with `openclaw skills install @beam-network/beam` or `hermes skills install beam`. | | Hermes plugin | A Hermes agent should have native tools for transfers and Rooms. Install it with `hermes plugins install beam`, then `hermes plugins enable beam`, and start a new session. | | Registry | The client wants a reusable Studio action. `beam registry` and `beam action` work with the registry at `https://api.b1m.ai/registry`. Confirm runtime compatibility and the action's requested permissions before running it. | **Rules for an agent.** Storage keys belong in Beam Studio. An agent, including one using the Beam agent skill or the Hermes plugin, uses them through Studio's MCP server, and uses storage keys of its own only when it holds them for every endpoint of the transfer. Never ask a person to paste a key into a chat. A spending action, such as starting a transfer, creating a Room or funding a sale, needs the owner's approval of its estimate before it runs. Grant only the tools the work needs, and follow the owner's policy for spending, publishing endpoints and running actions. ### Connectors [#connectors] Start with the client's real endpoints and the operations they need. A provider name, credential form or SDK type is not proof that every operation works. | Endpoint | Source | Destination | Through | Plan around | | -------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | S3, Cloudflare R2 and S3-compatible storage | Yes | Yes | SDKs, Studio, agent skill, Hermes plugin; buckets as Room members through Studio | The provider's supported operations and endpoint configuration. Studio's storage profiles (MinIO/AIStor, Wasabi, Backblaze B2, DigitalOcean Spaces and others) are configurations of one driver, not separate certifications. | | Hippius | Yes | Yes | SDKs, Studio, agent skill, Hermes plugin | Completion and verification differ from S3 multipart. Confirm final-object verification for the adapter before relying on it. | | [Box](/docs/connectors/box) | Yes: a file, or every file in a folder | Yes: a folder, as the transfer's only destination | TypeScript and Python SDKs; Studio, through a Box app the Studio's owner registers, including its MCP tools `beam.list_box_folder` and `beam.start_box_transfer` | Box addresses items by ID. A file of 20 MiB or more needs its SHA-1: Box sources have one, S3 and R2 objects only if stored with a full-object SHA-1 checksum; otherwise independent operators read the source again to compute it. Box's free plan caps files at 250 MB, and Box rate-limits uploads per Box user. | | Hugging Face | Yes: files stored with LFS or Xet; buckets as sources only | Yes: one source object, whose SHA-256 must be known before any byte moves | SDKs, Studio, agent skill, Hermes plugin | Hub-specific requirements on every target. | | Prepared HTTP endpoints | Yes | Yes | SDKs | Authentication, known size, range reads, write semantics and reachability. | | [Google Cloud Storage](/docs/connectors/gcs) | Yes | Yes | TypeScript and Python SDKs and Studio, through the S3-compatible configuration | The XML API at `https://storage.googleapis.com`, with an HMAC key for a service account that has the Storage Object User role on the bucket. Objects carry no SHA-1, so a file of 20 MiB or more sent to Box is read again to compute one. | | Azure Blob | No | No | None | Not supported: no SDK can sign access to it, and a transfer that uses it fails before any data moves. Do not propose it, and do not assume Studio supplies a workaround. | A service without a native adapter may still be usable through a properly authorized HTTP endpoint. Validate that specific route with a small end-to-end test before naming the provider in a proposal. Storage credentials must not be restricted to IP addresses or networks: independent workers use the signed routes from their own hosts. *** ## 4. Where the bytes actually go [#4-where-the-bytes-actually-go] Separate coordination from delivery, and identify the trust boundary for the chosen path. In provider transfers, workers move bulk data between source and destination endpoints. Room agents connect to delivery infrastructure, and Room media and streams run through Beam workers. Do not describe every Beam capability as having the same direct path, or promise that payload never traverses Beam-operated infrastructure. Workers are third parties. What they can read depends on the path: | Path | What intermediaries handle | Confidentiality boundary | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Provider transfer | Prepared source and destination routes, the broad region of each storage, payload bytes and delivery metadata | Workers can see transferred plaintext unless the client encrypts it before delivery. Access scope depends on the provider and route. | | Room object publication between agents only | Encrypted payloads and operational metadata, including each member's broad region | Object content is end-to-end encrypted between the participating agents using MLS-based protection. | | Room object publication with a bucket source or recipient | Storage access routes, each member's broad region and payload bytes, including on agent-recipient paths | Transport encryption protects connections, but delivery workers can see plaintext. | | Room stream between agents | Encrypted frames, plus their sizes, timing and sequence numbers | Content is end-to-end encrypted between the agents with the channel's MLS-derived key. Workers never see plaintext. | | Room media | Encrypted media payloads, plus their timing and sizes | The media payload Beam workers carry is encrypted with the channel's MLS key. WHIP and WHEP endpoints are served by the member's own agent, so plaintext exists only beside the encoder and the player. | | Room webhook member | The host member's agent decrypts the content and POSTs it over HTTPS to the receiver | End-to-end encryption ends at the host's agent, which can read everything sent to the webhook and publish as it. With durable delivery, the host keeps undelivered events in an encrypted spool on its own disk. Beam infrastructure never decrypts; HTTPS protects the hop to the receiver, which receives plaintext. | | Data sale | The encrypted package, delivered to the buyer's member only | The decryption key becomes public when the seller reveals it, which is why the package goes to the buyer's member alone. The sale's addresses, price, size and fingerprint are public onchain. | | On-chain receipt | Metadata only: status, size, completion time and fingerprints | Public onchain. Payloads never go onchain. | Four consequences matter to a client: 1. **Keep long-lived storage secrets in the trusted signing application.** Supported provider adapters sign through the client's SDK process or configured Studio service. Workers receive prepared access routes rather than those signing secrets. Client-supplied HTTP headers and URLs need their own access review. 2. **Signed URLs are access capabilities, not content encryption.** Their scope, expiry and reuse behavior depend on the provider. An assigned chunk does not establish a universal one-chunk access restriction, and a small chunk may be the whole object. Keep usable URLs and tokens out of public examples and logs. If unknown intermediaries must not read the content, use client-side encryption or an agent-only Room object publication. 3. **Check protection per publication.** A bucket source or recipient selects transport protection for that object publication, including its agent recipients. The presence of a bucket elsewhere in the Room does not by itself determine every channel's protection. Check the reported protection mode before sending sensitive content. 4. **A webhook's host is inside the trust boundary.** Granting a webhook member a channel lets its host read that channel's traffic, keep it on its disk when delivery is durable, and publish as the webhook. The webhook URL and signing secret stay on the host; Beam's coordinator sees only the URL's host name and a fingerprint. Completion and integrity verification also depend on the provider and operation. Confirm the required checks and final object availability instead of assuming one multipart-completion mechanism or one verification guarantee for all paths. *** ## 5. How capabilities connect [#5-how-capabilities-connect] A workflow is a chain in which one capability's output becomes the next one's input. Beam pushes some outputs to whoever is listening and only lets you read others. Where nothing pushes, something the owner runs has to read and act: name that glue in every proposal. | Output | Pushed or read | How a consumer gets it | Typical next step | | ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | | A transfer finished | Read | The SDK's wait, in the process that created it; `GET /transfers?order_by=completed_at&completed_after=…`; a Studio step's outputs | The next Studio step, a completion trigger, or your own poller acting | | A Room message | Pushed to listeners | `listen` in a local process on a member; a webhook member's signed `POST` | The service acts, and can reply in the Room | | A Room file | Read, or pushed to a webhook | The recipient's agent inbox and `object watch`; a webhook member's file delivery, with bytes up to 25 MiB | Processing on the recipient | | A Studio run's result | Read, or pushed by a step | Run state through Studio's API or the MCP server; `@beam/webhook`, `@beam/slack` or `@beam/http-request` steps | Another system; another workflow through a completion trigger | | A request from outside | Pushed into Studio | A Studio webhook trigger, from any system that can call HTTPS | A workflow run | | A data sale's state | Read, and onchain events | `beam sale status --json`; the escrow's events on Bittensor EVM | The buyer's processing; the seller's settlement | | A recorded receipt | Onchain | `getReceipt` in Beam's receipts contract | A contract's own later transaction | | Credit and budget | Read | The [Account Management API](/docs/management-api) with a service-account credential; HTTP `402` with `insufficient_credits` when a request is refused | Stop, or ask the owner | **Connections that need only configuration:** * A Room message reaches a webhook member, its HTTPS service acts, and the service answers in the Room. * A schedule, a date, a webhook trigger or a manual start runs a Studio transfer or fan-out, and a `@beam/webhook` or `@beam/slack` step reports the result. * One workflow finishing starts another through a completion trigger. * A Studio workflow delivers files to Room members' inboxes with `@beam/room-transfer`. * Every transfer of an organization gets an onchain receipt, once the console switch is on. **Connections that need code of the owner's, and what that code does:** * **Transfer finished, then anything outside Studio.** The process that created the transfer waits for it, or a poller reads newly finished transfers from the HTTP API and starts the next step. * **Room message, then a transfer.** A webhook service or a `listen` loop calls an SDK, and that process stays connected until the transfer ends. A serverless receiver answers within 10 seconds, or replies asynchronously, and hands the work to a long-running process. * **Transfer finished, then a message in a Room.** An agent member publishes it, with `beam room … channel … publish` or the local agent API. Studio has no step that publishes Room messages, and a webhook member can only reply. * **New file, then processing.** The recipient reads its inbox, or a webhook member delivers files up to 25 MiB to a service. * **Data sale, then the next step.** An agent loop reads `beam sale status --json` and runs `beam sale resume`; a person approves what needs a person. * **Budget gate.** Read credits and the key's budget from the Account Management API before spending, and handle `402 insufficient_credits`. * **Two Rooms.** A member of both republishes what it received, carrying the hop forward with `--hop`. **Carry these across every connection:** * **Identifiers.** Keep the transfer id, publication id, sale id or run id that each step returns, to check its outcome and to avoid repeating work. * **Idempotency.** Webhook deliveries can arrive more than once; deduplicate on `Idempotency-Key` before starting work with side effects. * **Acceptance is not completion.** A request accepted, a publish sent or a delivery handed to a webhook's host is not the final outcome. Read the terminal state. * **Trust boundaries.** Confidentiality changes where data crosses a boundary: a webhook's host reads plaintext, and a bucket recipient lets workers read it. Check each hop against the owner's policy. * **Authorization.** Spending and irreversible steps, such as funding a sale or overwriting destination objects, need the owner's approval. *** ## 6. Limits, and what Beam is not [#6-limits-and-what-beam-is-not] Check constraints before recommending a fit. Distinguish the selected interface's current limits from a statement about all of Beam. ### Size: a transfer constraint, not a Beam constraint [#size-a-transfer-constraint-not-a-beam-constraint] Sized delivery and live streaming are separate paths. | Surface | Size rule | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Transfer: SDK, Studio, agent skill or plugin | A known, finite source size is needed before planning. The caller supplies it or the SDK derives it from source metadata. | | Room object publication | The file path requires a regular, nonempty file; its size is derived from the file. A bucket source uses object metadata. | | Room `stream` channel | No declared total; session and stream lifecycle limits still apply, and sessions renew across long runs. | | Room `media` channel | No declared total; WHIP ingest and WHEP playback operate within the session's limits. | | Room `datagram` channel | No total, but each datagram carries at most 1,008 plaintext bytes. | | Data sale | Up to 100 GB. | Unknown-length video, audio or sensor output may fit live channels. For an append-only log or event feed, also establish whether loss, replay, ordering and reconnect behavior meet the application's requirements. If a client needs transfer-style chunked delivery and object completion checks but cannot know the source length, finalize finite objects first or choose a live path with a different completion contract. Do not promise that the two paths provide identical verification. ### Other constraints on transfers [#other-constraints-on-transfers] * **Parallelism is workload-dependent.** Small objects may provide little scope for parallel delivery. Measure them in the intended workflow; aggregation can help when per-object overhead dominates. Chunk selection and supported limits depend on the service, provider and release. * **Object transfer is not automatic delta synchronization.** For "only what changed", directory synchronization or deduplication requirements, identify which client or workflow computes the changes and submits the resulting objects. * **Confirm billing authorization.** Account-backed operations need an authorized account or API key and sufficient credits. Invitation-only Room members use the Room's configured payer. * **Support is operation-specific.** SDK types and Studio profiles do not prove a working adapter. Check [Connectors](#connectors) before naming a provider in a proposal. ### Constraints on Rooms [#constraints-on-rooms] * Creating a Room requires billing authorization. Member identity and grants determine access; the configured API key determines the payer. * Object publication requires all selected recipients to finish by default. Partial delivery must be explicitly allowed and inspected. * A live-only message reaches only the members listening when it is published. When some members' agents never answer, the outcome is unconfirmed: they may have the message, and publishing it again can deliver it twice. * A webhook member receives only while its host is online. It counts as reached once its host accepted the delivery, not once the receiver answered, and it publishes only replies. Durable delivery keeps what the host accepted; it does not receive what was published while the host was offline. * A grant, signed route or session can expire or be revoked. Design status, cancellation and reconnect handling for the selected interface. * Live-channel duration, idle limits, backpressure and reconnect behavior vary by channel. "No declared size" never means unlimited duration or durable replay. ### What Beam is not [#what-beam-is-not] * A substitute for general-purpose compute. Studio can execute supported workflow actions, but moving training data does not provide a training cluster. * A long-term storage service. Destinations, agent inboxes and workflow artifacts can retain data; confirm their storage and retention policies. * A way to reach a private resource from outside. Beam does not make a machine's private services reachable through an inbound path. * A dataset marketplace. Data sales let a seller and a buyer who have found each other trade safely; Beam does not list datasets or find buyers. * A guarantee of durable messaging, replay or exactly-once external effects beyond what each channel documents. Evaluate channel and workflow behavior against the client's requirements. * A promise of CDN edge caching. * Unlimited capacity. Validate volume, concurrency and geography against the current service and workload. ### Claims never to make [#claims-never-to-make] Do not promise that no intermediary can see plaintext, that no component retains data, or that all Beam paths share one encryption or routing model. Do not quote throughput, capacity, availability or savings without supporting evidence and scope. Do not treat acknowledgement as delivery or promise an undocumented delivery guarantee. An onchain receipt is Beam-reported metadata: never call it verified delivery or proof that content is correct. A data sale's escrow guarantees the committed bytes, not their accuracy: never promise a refund for a false card claim or answer, and never present a seller's answers as protected against reconstruction from overlapping questions. Explain the overlap and differences when comparing Rooms or Studio with existing products. Recommend only the capabilities that materially improve the client's architecture. *** ## 7. When Beam is worth using [#7-when-beam-is-worth-using] Beam earns its place when it changes something the owner can measure: elapsed time, total cost, people's time, or a capability they cannot get otherwise. Judge it against the owner's current setup, not against doing nothing. **Strong fit** | Situation | What Beam brings | What must still be shown | | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | One object goes to several destinations, across providers or regions, regularly, and someone waits for it | A fan-out replaces copies made one after another, and chunks travel in parallel across workers | Elapsed time and total cost against the current copies, on the real endpoints | | Several parties exchange data repeatedly, each with different permissions | One Multicast Room replaces separate point-to-point integrations; invitations bring parties in without accounts in the owner's systems | Each party can run the Beam agent, or take part through a webhook member; the confidentiality of each channel | | Agents or services in different organizations need to work together | A Room gives each party a scoped identity and per-channel grants; a webhook member brings in an HTTPS service with no Beam software | Who hosts each webhook, and whether that host may read its traffic | | Two parties that do not trust each other trade a dataset | A data sale ties payment to the committed bytes, with checks before payment | The price fits the escrow's limits; the card and questions answer the buyer's real doubts | | A smart contract needs a record that a transfer or Room delivery finished | Onchain receipts that any contract reads with `getReceipt` | A Beam-reported record is enough for the contract's purpose | | Data movement sits inside a pipeline with schedules, triggers, retries and people who need its history | Studio workflows, with the credential store under the owner's control | A step exists for every system in the loop | **Possible fit: test the unknowns first** * Faster completion on the owner's own endpoints, object sizes and regions. No published figure predicts it; measure it. * Room streams and media for the required duration, loss tolerance and reconnects. * Hippius, prepared HTTP endpoints, and Box files of 20 MiB or more stored without a SHA-1. * Sensitive content in Rooms with bucket members: delivery workers can read publications that involve a bucket. **Poor fit: recommend something else** | Situation | Better choice | | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | A copy inside one provider, or between its regions, that the provider's own server-side copy or replication handles | The provider's copy or replication: no Beam charge, and often no egress | | Many small objects, each sent as its own transfer | The provider's tools or a sync tool, unless a test shows that one transfer carrying many sources pays | | Copying only what changed, directory synchronization, versioned backup | A sync or backup tool | | A private resource must be reachable from outside | A VPN or a tunnel | | Messaging inside one organization that already runs a message broker | The existing broker | | Storage, CDN caching or compute | A storage service, a CDN or a compute platform | | Azure Blob as an endpoint | The provider's tools: Beam does not support it | | Content no third party may read, on a path that is not agent to agent, which the owner cannot encrypt first | An agent-only Room publication, or another tool | "Keep the current setup" is a correct answer when it already does the job, and it makes your other recommendations credible. *** ## 8. Designing a solution [#8-designing-a-solution] Work through seven steps. The first five spend nothing; the sixth needs the owner's authorization. ### Step 1: Discover [#step-1-discover] Learn the owner's goals, systems, data and recurring friction, and write the current path down before proposing anything: sources, destinations, volume per run and per month, frequency, participants, the tools in use and who maintains them. A client may describe a slow business process, an integration burden or a cloud bill before a transfer problem. Ask: * Where is data moving, being duplicated, distributed, streamed, traded or waiting to move? Who waits for it? * Which datasets are copied to several places one after another, or staged only to be moved again? * Which applications, agents or organizations need to exchange data but cannot easily do so? Which exchanges are separate point-to-point integrations? * Which steps are manual: someone downloads and re-uploads, emails a link or runs a script by hand? * Which operations need confirmation that delivery finished, for a person, a system or a contract? * Which datasets need evaluating before anyone pays for them? * Which data is produced continuously, with no known size? ### Step 2: Decompose [#step-2-decompose] Split the problem into needs, and map each one to a Beam capability or to a system outside Beam. Never present an outside system's job as Beam's. | Need | In Beam | Outside Beam | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | Finding data or a counterparty | Nothing: Beam does not list datasets or find buyers | Catalogs, marketplaces, contracts, people | | Moving sized objects | Transfer, fan-out; Room files | | | Exchanging data between parties | Room messages, datagrams, streams and media; webhook members | | | Orchestration | Studio workflows | The owner's own code calling an SDK | | Computation | Nothing | The owner's compute: training, analytics, transcoding | | Checking an outcome | Terminal states and per-destination checks; a sale's commitments, samples and `verify-claims`; onchain receipts, which are Beam-reported | Any check of content accuracy | | Payment | A data sale's escrow; credits for Beam's own charges | Every other payment | | Identity and authorization | Accounts, API keys and service accounts; Room roles, grants and invitations; Studio MCP scopes | The owner's approval policy | | Monitoring and recovery | The transfer status API; Studio run history and retries; publication outcomes; webhook spools and dead letters; `beam sale status` and `beam sale resume` | The owner's alerting | ### Step 3: Compose [#step-3-compose] Choose the smallest set of capabilities that meets the needs, and connect them using [section 5](#5-how-capabilities-connect): for every connection, what Beam pushes or what must be read, and which glue the owner runs. Start from the patterns in [section 9](#9-composition-patterns). Combine them, or build a chain of your own, when the owner's problem calls for it. One transfer with four destinations can be the whole proposal. ### Step 4: Validate [#step-4-validate] Run the [feasibility check](#11-feasibility-check). A design that fails it fails however good the fit looked. ### Step 5: Propose [#step-5-propose] Answer in the [shape of section 15](#15-shape-of-a-good-answer), with the cost comparison of [section 12](#12-economics-against-the-current-setup) and the smallest proof of [section 13](#13-proof-of-concept). ### Step 6: Execute, with authorization [#step-6-execute-with-authorization] Once the owner approves the estimate, configure and run the design through the interfaces in [section 3](#3-availability-by-interface). Follow the owner's policy for spending, publishing endpoints and irreversible steps. ### Step 7: Evaluate [#step-7-evaluate] Measure the outcome against the baseline and report it, including when it shows that the current setup was better. *** ## 9. Composition patterns [#9-composition-patterns] Reusable chains. Each names its components, its flow, the glue the owner runs, what to check, and the smallest proof. Combine them; they show how to build solutions and are not the only uses. **A: Event → workflow → notification.** Something happens in another system, and data must move and people or systems must hear about it. A Studio webhook trigger starts a `@beam/transfer` or `@beam/fan-out` step, and a `@beam/webhook` or `@beam/slack` step reports the result. *Glue:* the system where the event happens calls the trigger's URL, with an `Idempotency-Key` and a signature when the trigger requires one. The JSON body becomes the run's input, which step input bindings read as `${workflow.input.}`. *Check:* that the step takes the value it needs from that binding, that the source size can be read before planning, the step's retries, and who hears about a failed run. Repeated deliveries with the same key start no second run. *Smallest proof:* one real event that delivers one real object to two destinations, and the notification received. **B: One source → many recipients.** Two shapes, with different economics. A fan-out, where each destination reads the source: A Room publication from a bucket member, where each part of the source is read once for every recipient: A fan-out runs from an SDK or a Studio `@beam/fan-out` step to storage the owner can write to, with no software at the destinations. Each destination is delivered separately, so the source is read once per destination. A Room publication from a bucket member, sent with Studio's `@beam/room-transfer`, reaches agent and bucket members, and each range of the source is read once for all of them, plus any retries. *Check:* who holds write credentials for each destination; that recipients are members with the right grants and running agents; that delivery workers may read the content, since a bucket is involved. *Smallest proof:* one real object to three recipients, with each copy checked. **C: Parties across organizations.** A Room with message and object channels; an invitation for each partner, limited to its channels; optionally a bucket member and a webhook member. *Glue:* each side's logic, such as a `listen` loop or a webhook service that acts on messages. *Check:* grants per channel, which deny by default; the invitation's expiry and uses; the payer, since the Room's payer pays for invitation-only members; which host reads each webhook's traffic; removal at the end. Live messages reach only listening members unless the channel keeps them locally, and publish results name the members that missed one. *Smallest proof:* a partner joins from an invitation, exchanges one message and one file, and loses access when its grant is removed. **D: Request → decision → authorized action.** An AI service decides what to do, asks a person when it must, and acts. *Glue:* the service. It deduplicates on `Idempotency-Key`, asks for approval, starts the transfer with an SDK in a process that stays connected until the transfer ends, and replies with the outcome within the webhook's reply window, from 1 minute to 24 hours. *Check:* durable delivery on the host, the reply window, and the approval path. *Smallest proof:* one request, one approval, one transfer and one reply that carries the transfer's terminal state. **E: Evaluate → approve → buy → use.** *Glue:* an agent loop that reads `beam sale status --json` and runs `beam sale resume`, and the person who approves funding. *Check:* the price limits, what the card and questions can establish, and that a false claim brings evidence, not a refund. The stages are listed under [Data sales](#data-sales). *Smallest proof:* a small sale between the two parties, with the card checked before funding and `verify-claims` after the key is revealed. **F: Delivery → onchain record → contract action.** *Glue:* whatever starts the transfer, since Beam's relay only records receipts, and whoever sends the contract's next transaction. *Check:* that a Beam-reported record is enough for the contract, and the credit and gas costs. *Smallest proof:* one transfer whose receipt a test contract reads. **G: Dataset → outside compute → results back.** *Glue:* starting each job once its data has landed, with a Studio `@beam/http-request` step after the fan-out or with the owner's poller; publishing progress from an agent member. *Check:* that the compute stays outside Beam, and that no job starts before its whole object lands. *Smallest proof:* one dataset to two sites, one job each, and both results back. **H: Live feed → several consumers.** A Room stream between agents, or a media channel with WHIP in and WHEP out. Workers carry these encrypted and never see plaintext. *Check:* duration, loss, backpressure and reconnects with the real producer and consumers. *Smallest proof:* the real source and two consumers, for the required duration. *** ## 10. Worked examples [#10-worked-examples] Owner requests with no ready-made answer, worked through the method of [section 8](#8-designing-a-solution). Copy the reasoning, not the answers: the owner's systems decide the design. ### "Every time my research team receives a new dataset, distribute it to three external analysis partners." [#every-time-my-research-team-receives-a-new-dataset-distribute-it-to-three-external-analysis-partners] * **Needs:** an event, movement to three organizations, notice to the partners, and perhaps results coming back. * **Design 1, the partners give write access to storage of theirs:** pattern A. The team's storage notifies a small hook, which calls a Studio webhook trigger; a `@beam/fan-out` step delivers to the three partner buckets, and a `@beam/webhook` step tells each partner. * **Design 2, the partners run the Beam agent:** pattern B's Room shape, inside pattern C. The team's bucket is a member of a Room with the three partners, and `@beam/room-transfer` delivers each dataset to their agents' inboxes. Results can come back on a channel of their own. * **Glue:** the storage event hook; each partner's handling on arrival. * **Trust:** a bucket is the source in both designs, so delivery workers can read the content. For content they must not read, encrypt it before delivery, or publish from an agent member rather than a bucket. * **Beam's cost per dataset of size S GB:** design 1, 0.2 + 0.06 × S credits, with the source read three times; design 2, the same per delivery plus 1 credit each time the Room is started, with the source read once. * **Not Beam:** if the partners already read from storage the team shares with them and nobody waits, a scoped access grant may be enough. * **Smallest proof:** one real dataset, timed from arrival until all three partners can use it, against today's process. ### "Let my AI agent find a suitable training dataset, assess it, and buy it within an approved budget." [#let-my-ai-agent-find-a-suitable-training-dataset-assess-it-and-buy-it-within-an-approved-budget] * **Needs:** discovery, evaluation, approval, payment, delivery and use. Discovery is outside Beam: Beam does not list datasets. * **Design:** pattern E, then pattern G. With a seller found, the seller delivers the encrypted package into a sale Room. Before anything is paid, the agent checks it against the seller's commitments and the dataset's fingerprint and size, reads the card, draws samples and asks questions under the seller's policy. It brings the evidence and the price to the owner. On approval it funds the escrow. Once the seller reveals the key, the agent's client decrypts and checks every leaf, `verify-claims` recomputes the card and the answers, and the dataset goes to training. * **Budget:** the price in TAO, from $10 to 1 TAO, plus gas. By default a person confirms any sale above 0.2 TAO. The seller pays Beam's charges. * **Trust:** the escrow guarantees the committed bytes, not their usefulness or accuracy. * **Not Beam:** a dataset from a supplier with an existing contract and delivery channel needs no escrow. * **Smallest proof:** a small first sale with the same seller. ### "Connect our internal agent with our contractor's agent without giving either access to our entire infrastructure." [#connect-our-internal-agent-with-our-contractors-agent-without-giving-either-access-to-our-entire-infrastructure] * **Design:** pattern C. The owner creates a Room and invites the contractor with grants on two channels only: messages and files. An internal HTTPS service can join as a webhook member hosted by the owner's agent. Beam does not make anything else on the owner's network reachable. * **Glue:** each agent's logic. * **Trust:** messages and files between the two agents are end-to-end encrypted; the webhook's host reads the service's traffic. * **Cost:** 1 credit each time the Room is started; messages are free; files are charged as Room transfers. The Room's payer pays for the contractor's invitation-only identity. * **Ending it:** remove the contractor's grants or membership; the invitation expires on its own. * **Smallest proof:** the contractor joins, exchanges one message and one file, and loses access when its grants are removed. ### "When a blockchain contract authorizes a delivery, send the data and report its completion." [#when-a-blockchain-contract-authorizes-a-delivery-send-the-data-and-report-its-completion] * **What Beam does not do:** a contract cannot start a Beam transfer, and Beam's relay never starts one. * **Design:** pattern F with a listener. The owner's service watches the contract's authorization event, starts the transfer with an SDK and keeps its id. The receipt comes from the console switch, or from a `requestReceipt` call by a wallet Beam approved for the organization. The contract's next step reads `getReceipt` in a later transaction. * **Glue:** the listener, which holds the storage credentials and is trusted to act on the event. * **Trust:** the receipt records what Beam reported, not that the content is correct. * **Cost:** the transfer, plus 1 credit per receipt and the gas of any request. * **Smallest proof:** one authorization event on a test contract, one transfer, and one receipt that the contract reads. ### "Help me reduce the time spent distributing large media files to remote production teams." [#help-me-reduce-the-time-spent-distributing-large-media-files-to-remote-production-teams] * **Discover first:** how files move today, their sizes, how many teams, where people wait, and who uploads again. * **Designs:** a fan-out to each team's storage (pattern B), or a Room where team machines receive files in their agents' inboxes, end-to-end encrypted when published from an agent member. If teams review cuts together, a media channel (pattern H). * **Glue:** how each site picks files up. * **Not Beam:** teams on one cloud whose storage replicates natively, or files small enough that the current sync is already fast. * **Smallest proof:** one real master to every team, timed until the last team can use it, against the current method, over three runs. ### "Review my infrastructure and identify opportunities I haven't considered." [#review-my-infrastructure-and-identify-opportunities-i-havent-considered] * **Scope first.** Work only from what the owner authorizes you to read, such as architecture notes, infrastructure code, job schedules, storage inventories, integration lists and cloud bills. Read, change nothing and spend nothing, and never ask for credentials in a chat. * **Inventory.** List every recurring flow of data: its source, destinations, volume and frequency, who waits for it, the tool that moves it and who maintains that tool. Add the exchanges with other organizations and the manual hand-offs. * **Match.** Run each flow through the questions of [step 1](#step-1-discover) and the fit tables of [section 7](#7-when-beam-is-worth-using). Typical finds: the same export copied to several regions one after another (pattern B); partners sent files by emailed links (pattern C); an AI service that polls a shared folder for work (pattern D); a script someone runs by hand every week (pattern A); a counterparty that needs a record that a delivery finished (pattern F). * **Estimate.** For each candidate, set the current cost and time from the owner's own data beside Beam's charge ([section 12](#12-economics-against-the-current-setup)), and mark what only a measurement can settle. * **Rank and report.** Rank by measurable benefit and by how cheaply a proof can settle it. Present the best one to three, each with its design, glue, trust boundaries and smallest proof, and list what you set aside and why. "Nothing worth changing" is a valid result. * **Then wait.** Any proof needs the owner's approval before it spends anything. *** ## 11. Feasibility check [#11-feasibility-check] Before proposing, confirm each item, and say which ones you could not confirm: * **Every component exists for this owner:** the capability, the interface ([section 3](#3-availability-by-interface)), the [connectors](#connectors) and the client versions. * **Each output can become the next input:** whether it is pushed or read, its format, and who reads it ([section 5](#5-how-capabilities-connect)). * **Every piece of glue has an owner** who will run and maintain it. * **Identity holds across the whole chain:** keys, grants and credentials, with the least access each step needs. * **Confidentiality holds at every hop** ([section 4](#4-where-the-bytes-actually-go)): who can read plaintext, and where that changes. * **Failures are handled:** what each step does on failure, retries, duplicates and partial delivery, and how a person finds out. * **Limits are respected** ([section 6](#6-limits-and-what-beam-is-not)): sizes, rates, durations and price limits. * **The economics justify Beam** ([section 12](#12-economics-against-the-current-setup)). * **The owner authorized** spending and every irreversible step. *** ## 12. Economics against the current setup [#12-economics-against-the-current-setup] A recommendation without a baseline is incomplete. Compare the whole cost of each way of doing the same job, on the same workload: | Cost line | Current setup | With Beam | | ------------------------------------- | ---------------------------------------- | -------------------------------------------- | | Provider egress and requests | Yes | Yes: Beam does not remove them | | Beam's charges | No | Yes | | Tools and services | Today's | Those still needed | | Building and maintaining integrations | Today's scripts, relays and integrations | The glue the design needs | | People's time | Manual steps, monitoring, hand-offs | What remains | | Delay | How long people and jobs wait today | Measured in the proof | | Failure recovery | Reruns and repairs | Retries and resumes, and what remains manual | **Provider charges.** Beam does not remove the providers' egress and request charges. A fan-out reads the source once per destination. A Room publication from a bucket member reads each part of the source once for all its recipients; retries can read parts again. **Beam's charges.** A credit costs $0.50, and every charge rounds up to the next 0.01 credit. These are the published prices, and they can change: check [Billing](/docs/billing#prices) when you quote them, and have the owner approve each estimate before anything is spent. Before a transfer starts, Beam estimates its cost and refuses it with HTTP `402` when the key cannot pay. | Item | Credits | Dollars | | ------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------- | | Transfer or fan-out | 0.2 per transfer, plus 0.02 per GB delivered to each destination | $0.10, plus $0.01 per GB | | Room | 1 each time it is started | $0.50 | | Room file | 0.2, plus 0.02 per GB for each member that receives all of it | $0.10, plus $0.01 per GB per member | | Room messages and streams | Free | Free | | Studio workflow runs | Free; the transfers they start are charged | Free | | Onchain receipt | 1 each, plus gas for a contract request | $0.50 | | Data sale | The seller's organization pays for the sale Room and the delivery; the buyer pays Beam nothing | | Each transfer carries the 0.2 credit, so a 1 MB object sent on its own costs 0.21 credit. An example of Beam's charge alone: 200 GB to three destinations every week, as one fan-out, delivers 600 GB: 0.2 + 12 = 12.2 credits, or $6.10 a week. The providers' charges for reading the source three times and writing three copies come on top. **Where Beam can pay for itself**, each to be measured: * **Elapsed time.** Parallel delivery can shorten a transfer when the object, the endpoints and the network allow it. * **People's time.** Scripts, staging servers, relays and point-to-point integrations that no longer need maintaining; manual hand-offs that become workflow steps. * **Fewer source reads.** A Room publication from a bucket reads the source once for every recipient. * **Capabilities without an easy equivalent.** Trading data with a party you do not trust, with payment tied to the committed bytes; end-to-end encrypted exchange between the agents of many parties, with per-channel grants and no relay the owner has to run; an onchain record that contracts can read. * **Recovery.** Workflow retries, resumable sales, durable webhook delivery. Do not invent provider rates, throughput figures or savings. Ask the owner for their bills and timings, and where a number is missing, say so and name who can supply it. If Beam costs more and improves nothing the owner values, recommend the current setup. *** ## 13. Proof of concept [#13-proof-of-concept] 1. **Measure the baseline.** Run the current process on the same data: time from start until the last destination can use the data, cost lines, people's time and failures. 2. **Agree the success criteria before running,** in numbers. For example: "every destination complete and checked within 40 minutes, for no more than the current cost, with no manual step." 3. **Keep the scope small but representative:** the real endpoints, real sizes and real participants. Estimate Beam's charges and the provider charges first, and have the owner approve them. 4. **Run it more than once,** at least three times, and record the client versions; the transfer, run, publication or sale ids; terminal states; size or checksum checks at every destination; timings; credits used, from the console or the [Account Management API](/docs/management-api); and provider charges. 5. **Decide:** adopt, adjust or keep the current setup, and report the result either way. Typical smallest proofs: * One large object to three destinations in a single fan-out, against the client's real endpoints, checking each destination. * One bucket-to-bucket transfer across two providers they already use. * One Room with a bucket, two machines and one partner joining from an invitation, checking grants and the protection of each publication. * One webhook member delivering a channel's messages to the client's service, with durable delivery on and a reply published back. * One live channel with a real encoder and two viewers, for the required duration. * One recurring job in Studio, replacing a script somebody maintains by hand. * One small data sale between the two parties, with the card checked before funding and `verify-claims` after the key is revealed. *** ## 14. Decision tree [#14-decision-tree] ```text Is there a measurable problem: time, cost, people's effort, or a missing capability? +-- no ------------------------------> Keep the current setup +-- the current setup already solves it as well for less --> Keep it Bytes need to move? +-- Finite size known or derivable before planning? +-- yes, one destination ------> Transfer +-- yes, several destinations --> Fan-out, or a Room publication from a bucket +-- no, open-ended producer ----> Assess a live channel below Ongoing exchange needs shared membership and permissions? +-----------------------------------> Multicast Room (roles, grants, invitations) +-- an HTTPS service as a member ---> Webhook member, run by a trusted host Data is live or continuous? +-- between agents ------------------> Room stream / datagram channel +-- audio/video with an encoder -----> Room media (WHIP in, WHEP out) Check duration, delivery behavior and reconnect needs for every path. Two parties trade a dataset without trusting each other? +-----------------------------------> Data sale (CLI), checked with a card, samples and questions before funding A smart contract needs to know a transfer finished? +-----------------------------------> Onchain transfer receipt Something private must be reachable from outside? +-----------------------------------> Not something Beam does The process around movement needs steps, retries, triggers or scheduling? +-----------------------------------> Studio workflow An AI agent should drive it? +-- Studio operations ---------------> Studio MCP server +-- transfers and Rooms for a user --> Beam agent skill or Hermes plugin +-- data sales ----------------------> The CLI's beam sale commands Several of these at once? +-----------------------------------> Combine where each adds value, naming the glue (sections 5 and 9) ``` The tree suggests a starting point. Apply the provider, interface and security constraints in sections 3 to 6, and the feasibility check, before recommending a design. *** ## 15. Shape of a good answer [#15-shape-of-a-good-answer] When asked how Beam could help, answer in this shape. Keep it short enough to be read and specific enough to be acted on. **Verdict**: a good fit, a possible fit to test, or a poor fit with the better alternative. **Existing process**: how data moves today and how the systems reach each other, in the owner's words and numbers. **Design**: the capabilities and interfaces used, the glue the owner runs, and a simple flow diagram showing what Beam coordinates, where payload travels, and which components are trusted with plaintext or credentials. Record the client versions used for validation. **Why it helps**: the specific reason, such as parallel delivery, fewer copies or source reads, reusable membership, payment tied to delivery, or automated steps. **Cost against the current setup**: the comparison of [section 12](#12-economics-against-the-current-setup), from measurements or clearly labeled estimates. **What must be confirmed**: open questions, and who can answer each. **Smallest proof**: one test, with the baseline and the success criteria agreed in advance ([section 13](#13-proof-of-concept)). *** ## 16. Reference map [#16-reference-map] | Surface | Where | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Documentation, human-readable | [Beam docs](/docs/intro) | | Documentation, agent-readable | [Index](/llms.txt), [full corpus](/llms-full.txt), and any page's URL with `.md` appended | | Capabilities as data | [Capability registry](/capabilities.json) and its [JSON Schema](/capabilities.schema.json) | | Console: organizations, credits, API keys, transfers, onchain receipts | [Console](https://console.b1m.ai) | | Transfer status, read-only HTTP API | `https://beamcore.b1m.ai`, see [API reference](/docs/api-reference) | | Organization, API-key and billing management API | `https://api.b1m.ai`, see [Account Management API](/docs/management-api) | | Room invitation check | `https://coordinator.b1m.ai/v1/room-invitations/inspect` | | Authentication | `https://auth.b1m.ai` | | Action registry | `https://api.b1m.ai/registry` | | Data sale escrow | Bittensor EVM mainnet, see [Agent Data Sales](/docs/data-sales) | | Receipts contract | Bittensor EVM mainnet, see [Bittensor EVM](/docs/integrations/bittensor-evm) | | CLI and Studio installers | `https://cdn.b1m.ai`; follow the [CLI](/docs/cli) or [Studio](/docs/studio) installation guide | Pages worth fetching as Markdown when you need detail: [intro](/docs/intro), [architecture](/docs/architecture), [clients](/docs/clients), [developer-quickstart](/docs/developer-quickstart), [sdk](/docs/sdk), [cli](/docs/cli), [room-webhooks](/docs/room-webhooks), [data-sales](/docs/data-sales), [studio](/docs/studio), [transfers](/docs/transfers), [connectors](/docs/connectors), [integrations/bittensor-evm](/docs/integrations/bittensor-evm), [billing](/docs/billing), [management-api](/docs/management-api), [api-reference](/docs/api-reference). # Overview (/docs/api) These pages cover the BeamCore endpoints a client calls over HTTP: checking a key and reading transfers, plus the supported delayed and realtime telemetry and audit APIs. Transfers are created with an SDK or Beam Studio, not over HTTP. Paid telemetry uses an organization key with `telemetry:read` and prepaid credits. Standard, history and detail responses cost 0.001, 0.002 and 0.004 credit ($0.50, $1 and $2 per 1,000 at $0.50 per credit); successful empty pages count, errors and `304` responses do not. Responses are metered exactly and charged in aggregate: whole hundredths of a credit as they accrue, and the remainder rounded up once per month. Epoch lists and their orchestrator pages use the history tier. Observations publish one subnet epoch after capture, with a 60-minute fallback when the chain clock is unavailable. Each read is pinned to a published generation: keep cursor filters to page the same version, and continue within an hour. Responses carry an `ETag`; send `If-None-Match` to revalidate, and an unchanged payload answers `304` without a charge. Realtime telemetry mirrors every paid route under `/v1/telemetry/realtime/` with current evidence, including transfers in progress; work awaiting verification is reported separately. Epoch reads return complete sets of closed epochs only. It needs the separate `telemetry:realtime:read` grant, which `telemetry:read` never implies, and costs twice the snapshot price: 0.002, 0.004 and 0.008 credit ($1, $2 and $4 per 1,000). Realtime has its own quota with the same limits, a realtime cursor continues for 9 minutes, and `X-Beam-Telemetry-Lag-Ms` reports how far the data a read returns trails committed evidence. While projections are not ready or not current, realtime reads answer `503` with `Retry-After`. ```bash curl 'https://api.b1m.ai/v1/telemetry/epochs?limit=20' -H 'X-Api-Key: YOUR_ORGANIZATION_KEY' curl 'https://api.b1m.ai/v1/telemetry/epochs/123/orchestrators?limit=100' -H 'X-Api-Key: YOUR_ORGANIZATION_KEY' ``` Use the returned epoch number and `nextCursor` in subsequent reads. Free audit routes expose only the requested subject's published proof; they do not provide fleet browsing. Each page has a request panel that builds a sample in cURL, JavaScript, Go, Python, Java, C#, and Rust. The query parameters and response fields are described in [API Reference](/docs/api-reference#endpoints). **Samples omit the key itself until you enter one.** They mirror the request panel above them, so an authenticated operation shows the header with an empty value — `-H "X-Api-Key: "` — and copying it as-is returns `401 authentication required`. Enter a key in the panel and the samples fill it in across every language, or paste your own value into the header. Authenticated operations use the `X-Api-Key` request header. Enter only a test or scoped key in an interactive client; this documentation never stores or embeds API keys. # API Reference (/docs/api-reference) The BeamCore HTTP API at `https://beamcore.b1m.ai` reads your organization's transfers from any language. It authenticates with an API key (`b1m_…`) in the `X-Api-Key` header. It does not create transfers. Create them with an [SDK](/docs/sdk) or [Beam Studio](/docs/studio), then read their status here. Administering the account — creating, rotating and revoking those keys, and reading credits and usage — is a separate API on a separate host. See the [Account Management API](/docs/management-api). New to Beam? Start with the [Developer Quickstart](/docs/developer-quickstart) to create an API key and send your first transfer. ## Base URL [#base-url] ```text https://beamcore.b1m.ai ``` ## Authentication [#authentication] Send your API key in the `X-Api-Key` header: ```http X-Api-Key: b1m_... ``` A request without a valid key is refused with `401`. The transfer endpoints also need a key that may read or create transfers (`transfers:read` or `transfers:create`, such as the Console's read-only preset); any other key is refused with `403`. ## Endpoints [#endpoints] | Method | Path | Returns | | ------ | ---------------------------------- | ------------------------------------------------------------------------------- | | `GET` | `/transfers` | Your organization's transfers, newest first. | | `GET` | `/transfers/{transfer_id}` | One of your organization's transfers. | | `GET` | `/transfers/{transfer_id}/receipt` | The fields an onchain receipt records for one of your organization's transfers. | | `GET` | `/auth/me` | Confirms that the key authenticates. | ### List transfers [#list-transfers] ```bash curl "https://beamcore.b1m.ai/transfers?status=completed&limit=10" \ -H "X-Api-Key: $BEAM_API_KEY" ``` | Query parameter | Default | | | ----------------- | ------------ | -------------------------------------------------------------------------------------------------------------- | | `limit` | `20` | Transfers per page, at most 100. | | `offset` | `0` | Transfers to skip. | | `status` | — | Only transfers in this [status](/docs/transfers#transfer-statuses), such as `completed`. | | `order_by` | `created_at` | `created_at` or `completed_at`, newest first. With `completed_at`, transfers that have not finished come last. | | `completed_after` | — | An ISO 8601 timestamp: only transfers that finished after it. | ```json { "transfers": [ { "id": "0b7c4f1e-6d52-4a8e-9a0f-2f1c9e5d7a31", "transfer_key": "…", "status": "completed", "total_bytes": 1073741824, "bytes_transferred": 1073741824, "error_message": null, "metadata": {}, "prism_excluded": false, "prism_exclusion_reason": null, "created_at": "2026-09-29T10:15:02.000Z", "started_at": "2026-09-29T10:15:03.000Z", "completed_at": "2026-09-29T10:16:41.000Z" } ], "limit": 20, "offset": 0 } ``` `completed_at` is set when a transfer finishes, whether it succeeded or not. To pick up newly finished transfers, poll with `order_by=completed_at` and `completed_after` set to the latest `completed_at` you have seen. ### Get one transfer [#get-one-transfer] ```bash curl "https://beamcore.b1m.ai/transfers/$TRANSFER_ID" \ -H "X-Api-Key: $BEAM_API_KEY" ``` `transfer_id` is the ID the SDK returned when it created the transfer; the transfer's `transfer_key` works too. The response is one transfer object, as below. A transfer that does not exist, or belongs to another organization, returns `404` with `{"error": "transfer not found"}`. ### Get a transfer's receipt fields [#get-a-transfers-receipt-fields] ```bash curl "https://beamcore.b1m.ai/transfers/$TRANSFER_ID/receipt" \ -H "X-Api-Key: $BEAM_API_KEY" ``` Returns only the fields an onchain receipt records, about 340 bytes whatever the transfer's size. The full transfer object grows with the transfer: its `metadata` is over 100 KB for a 100 GB transfer. Readers with a response limit, such as a [Chainlink CRE](/docs/integrations/chainlink-cre) workflow, use this endpoint. ```json { "id": "0b7c4f1e-6d52-4a8e-9a0f-2f1c9e5d7a31", "status": "completed", "total_bytes": 1073741824, "bytes_transferred": 1073741824, "completed_at": "2026-09-29T10:16:41.000Z", "plan_fingerprint": "5f0c…", "coordinate_checksum": "9a41…" } ``` | Field | | | ------------------------------------------------------------------ | --------------------------------------------------------------------------- | | `id`, `status`, `total_bytes`, `bytes_transferred`, `completed_at` | As in the [transfer object](#the-transfer-object). | | `plan_fingerprint` | A hash of the transfer's plan, from its `metadata`, or `null`. | | `coordinate_checksum` | A hash of the transfer's chunk coordinates, from its `metadata`, or `null`. | `transfer_id` must be the transfer ID; `transfer_key` is not accepted here. A transfer that does not exist, or belongs to another organization, returns `404` with `{"error": "transfer not found"}`. ### The transfer object [#the-transfer-object] | Field | | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | `id` | The transfer ID. | | `transfer_key` | A second identifier for the transfer. | | `status` | See [Transfer statuses](/docs/transfers#transfer-statuses). | | `total_bytes` | The transfer's size, in bytes. | | `bytes_transferred` | Bytes delivered so far. | | `error_message` | Why the transfer failed, or `null`. | | `metadata` | The transfer's metadata. | | `prism_excluded` | `true` when the transfer does not count for PRISM, Beam's miner scoring. | | `prism_exclusion_reason` | Why it does not count: `not_eligible`, `review`, `storage_refused` or `incomplete`; `null` when it counts. | | `created_at`, `started_at`, `completed_at` | Timestamps. `started_at` and `completed_at` are `null` until the transfer starts and finishes. | Transfer responses do not include the name you gave a transfer: there is no name field, and `name` and `transfer_name` are removed from `metadata`. ### Check a key [#check-a-key] ```bash curl https://beamcore.b1m.ai/auth/me \ -H "X-Api-Key: $BEAM_API_KEY" ``` A valid key returns `200` with the prefix of the key you sent, in `current_key_prefix`, and the number of your organization's active keys, in `api_key_count`. It does not return your organization or the key's permissions; see those under **API Keys** in the [Console](https://console.b1m.ai). ## Request samples [#request-samples] The [endpoint pages](/docs/api) have a request panel for each of these endpoints, which builds a sample in cURL, JavaScript, Go, Python, Java, C#, and Rust. The tables above describe the parameters and response fields. # Architecture (/docs/architecture) Beam separates coordination from delivery. It has the five roles described in [What is Beam?](/docs/intro#core-roles): **clients** describe transfers, **BeamCore** coordinates them, **orchestrators** and their **workers** move the bytes, and **validators** reward delivery. This page describes how they connect. *** ## Network Topology [#network-topology] Coordination and data are separate. BeamCore assigns work but never carries payload: bytes move directly between the workers and your storage. Orchestrators and workers are paid in `$TAO` through metagraph weights set by validators, which is what keeps them competing for your transfers. *** ## Roles [#roles] | Role | Run by | Responsibility | | ---------------- | -------------------- | ------------------------------------------------------------------------ | | **Client** | You | Describes transfers and signs access to its own storage | | **BeamCore** | Beam | Accepts transfers, assigns chunks, tracks progress, and records delivery | | **Orchestrator** | Independent operator | Runs a pool of workers and competes for work | | **Worker** | Independent operator | Moves chunks between your source and destination | | **Validator** | Bittensor validator | Verifies delivery and sets the weights that share out rewards | *** ## How a client reaches Beam [#how-a-client-reaches-beam] Clients create transfers with an [SDK](/docs/sdk) or from a [Beam Studio](/docs/studio) workflow. The SDK prepares the transfer, signs chunk-scoped access to your storage in your own process, and hands the transfer to BeamCore. Your storage credentials never leave that process. Every client authenticates with an API key from the Console. To read the status of your transfers from any language, call the BeamCore HTTP API at `https://beamcore.b1m.ai`; see [API Reference](/docs/api-reference). It reads transfers; it does not create them. *** ## How work is delivered [#how-work-is-delivered] Beam assigns chunks to orchestrators that compete on measured delivery performance, and each orchestrator hands its chunks to workers in its pool. If a participant stalls or fails, Beam reassigns its chunks automatically; your transfer continues without action from you. *** ## Data Plane [#data-plane] Data never passes through BeamCore. Each worker reads its chunk from the source and writes it to the destination, using only the short-lived, chunk-scoped access the SDK signed. This keeps BeamCore lightweight and prevents it from becoming a bandwidth bottleneck. # Billing & Payments (/docs/billing) Beam usage is denominated in **credits**. Credits are bought in packs, or included in a plan, and are consumed as billable actions run, from the API, the SDKs, the CLI, Studio or MCP alike. This page covers what things cost and how a payment becomes credits. *** ## Prices [#prices] | What | Price | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Transfer | **0.2 credit** per transfer, plus **0.02 credit per GB** delivered ($0.10 per transfer plus $0.01 per GB, $10 per TB), rounded up per transfer to the next 0.01 credit. | | Room transfer | **0.2 credit** per transfer, plus **0.02 credit per GB** delivered, rounded up per transfer to the next 0.01 credit. The file counts once for each Room member that receives all of it. | | Studio workflow run | **Free**, its steps included. The transfers and Room transfers a run starts are charged as transfers. | | Room start | **1 credit** each time a Room is started | | Room streams and messages | **Free** | A credit costs $0.50. GB and TB are decimal: 1 GB is 1,000,000,000 bytes and 1 TB is 1,000 GB. A transfer is priced at 0.2 credit plus its exact size, then rounded up to the next hundredth of a credit, so a transfer that moves any data costs at least 0.21 credit ($0.105). For example: | Transfer size | Credits | USD | | --------------------------- | ------- | --------- | | 1 byte | 0.21 | $0.105 | | 1 GB | 0.22 | $0.11 | | 1 GiB (1,073,741,824 bytes) | 0.23 | $0.115 | | 20 GB | 0.6 | $0.30 | | 100 GB | 2.2 | $1.10 | | 1 TB | 20.2 | $10.10 | | 100 TB | 2,000.2 | $1,000.10 | Credits never go beyond two decimal places: balances, charges and usage are all shown to the hundredth of a credit. A transfer is charged at the price in effect when it ends. Existing reservations and settled charges retain their original amounts. Telemetry API and AI usage are priced separately. Before a transfer starts, Beam estimates its cost. If the estimate is more than your API key may spend, the transfer is refused before any data moves: the request fails with HTTP `402` and the code `insufficient_credits`, with the credits required and the credits available. What a key may spend is your plan's included credits left this period plus your organization's balance, within the key's own credit limit and monthly budget. Add credits, or turn on [auto top-up](#credit-consumption), and start it again. A Room transfer is estimated for the file size once for each Room member it is sent to, and is refused the same way. A transfer that was already running when your credits ran out, for example because other transfers or workflow runs spent them first, is still charged when it completes, so your balance can go below zero. New transfers are refused until you add credits. *** ## Credit packs [#credit-packs] Card payments in the Console buy credits in packs: | Pack | Credits | | ---- | ------- | | $10 | 20 | | $25 | 50 | | $50 | 100 | | $100 | 200 | [Auto top-up](#credit-consumption) buys one of these packs. TAO and Alpha Beam deposits are not packs: they are credited at the value received, as [described below](#how-a-deposit-is-priced). *** ## Ways to pay [#ways-to-pay] How you pay depends on the currency: | Currency | How you pay | Status | | ---------- | --------------------------------------- | --------------------- | | USD | Card, in the Console (Stripe) | **Available** | | TAO | Your organization's own deposit address | **Available** | | Alpha Beam | Your organization's own deposit address | **Available** | | USDC | — | Not currently offered | Beam subnet alpha exists only on the Bittensor chain, so Beam settles TAO and Alpha Beam deposits itself, from finalized blocks, rather than through a payment provider. A method is never selectable before it can actually settle, so no one picks a payment that would fail at checkout. *** ## Every payment is credited once [#every-payment-is-credited-once] Whichever way you pay, credits are granted **only** once the payment has settled, and each payment is credited exactly once. A notification delivered twice, a block read twice, or a page reloaded twice never grants credits twice. *** ## Referral rewards [#referral-rewards] Every account has a referral link, on **Settings → Referrals**. Share it, and anyone who creates their account through it is recorded as your referral. When a referral's organization has purchased **$500** of credits in total, that referral qualifies and earns you **+10% bonus credits on your next credit purchase**. The purchase is charged in full; the bonus arrives as extra credits beside it. * Qualifying spend is counted across every payment method from the point the referred account joined its organization, net of refunds. There is no deadline. * Each referral earns **one** reward. Rewards queue up, and exactly one is applied per purchase, so a purchase is never discounted twice. * Rewards do not expire, and they apply to automatic top-ups as well as purchases you make yourself. * The bonus appears in payment history as its own line, so you can always see what was granted and which referral paid it. * Your code never changes, so a link you have already shared keeps working. Your referrals page shows whether each referral has qualified, and nothing else about them. It does not report their spending, their name or their email — how much another organization buys is their business, not the referrer's. *** ## Paying by card [#paying-by-card] Stripe's payment form is mounted directly in the billing page — paying does not send you to another site. Card details are entered in Stripe-hosted fields and never reach Beam's servers. Credits are granted as soon as Stripe confirms the payment. *** ## Paying with TAO or Alpha Beam [#paying-with-tao-or-alpha-beam] Bittensor assets settle directly on chain. Every organization gets its **own** deposit address, generated the first time you open the crypto tab in Billing. Funds are never pooled with another customer's. Because the address identifies you, there is nothing else to get right: no memo, no exact amount to match, and no time limit. Send whatever you like, whenever you like. Beam's servers **hold no key that can spend from these addresses**: the Console can create your deposit address, but cannot move funds out of it. ### How a deposit is priced [#how-a-deposit-is-priced] Credits are granted at the value **received**, using the rate observed when the deposit confirmed — not a rate quoted earlier, because a deposit address has no checkout to quote at. * **TAO** is valued against its USD price. * **Alpha Beam** is valued through the subnet's own AMM reserves, then to USD. The subnet is its own price oracle; no third-party feed is involved for alpha. Credits are granted to the hundredth of a credit and always round **down**, so you are never credited more than you paid: $10.07 buys 20.14 credits, and the remaining fraction of a hundredth (under $0.005) stays as value received but ungranted. Each deposit is credited on its own; one worth less than 0.01 credit is recorded but grants nothing. The rate shown in the console is explicitly indicative and may differ from the one applied. If the price feed is unavailable, a deposit is held rather than credited at a guessed or stale rate. ### What "confirmed" means [#what-confirmed-means] Bittensor uses GRANDPA finality, which is absolute — a finalized block cannot be reorganised. Beam scans only finalized blocks and treats finality itself as the confirmation. There is no confirmation counter to wait through; detection typically takes under a minute. Each deposit is credited once. ### Sending alpha [#sending-alpha] Alpha moves as a **stake transfer** between coldkeys on the same subnet, which is what `btcli stake transfer` performs. It arrives as stake owned by your organization's deposit coldkey while remaining delegated to the hotkey you were using. A transfer between *different* subnets is not accepted as a deposit: its amount is denominated in another subnet's alpha and cannot be priced against ours. ### Refunds [#refunds] On-chain deposits are not refunded automatically. Contact support to request a refund. *** ## Plans [#plans] Plan subscriptions are card-only. Crypto buys credits, which are consumed as transfers run. *** ## Credit consumption [#credit-consumption] Credits are consumed as billable actions are charged (see [Prices](#prices)), and every grant and deduction is recorded in the organization's credit ledger. A plan's included credits are used before purchased credits. **Auto top-up is card-only.** It works by charging a saved payment method when the balance falls below a threshold, which requires a mandate that no crypto rail can provide. Once a card is saved, the threshold and pack can also be set over HTTP — see the [Account Management API](/docs/management-api). *** ## Payment history [#payment-history] **Billing → Payment history** is the record of what an organization has paid, over any month or year rather than a rolling window of recent days. It merges three things into one date-ordered list: * Credit purchases and on-chain deposits, from the credit ledger. * Refunds, bonuses and manual adjustments. * Plan and subscription invoices, read directly from Stripe. These never enter the credit ledger, so without them the totals would understate what a paid plan has cost. Each settled payment expands to its receipt: the amount, the method, who initiated it, and either the Stripe-hosted receipt or the Subscan link for the extrinsic that paid it. A deposit worth less than one credit is listed as **needs attention**, with the reason it granted nothing — it is recorded, so it is shown. Plan charges are the one part that depends on a live Stripe call. If Stripe cannot be reached, the page says so and still reports credit purchases and deposits rather than failing. ### Exports [#exports] Two formats, both scoped to the selected period: * **Export CSV** — one row per payment, for reconciliation. * **Statement** — a one-page summary with per-method subtotals and line items, laid out for printing or saving as a PDF. Payment history and usage are also readable over HTTP. See the [Account Management API](/docs/management-api). *** ## Usage breakdowns [#usage-breakdowns] **Usage** answers where credits went, for the same kind of period. Spend is broken down three ways: * **By project** — attributed to the project the API key belonged to when it spent. * **By API key** * **By action** — the billable action the credits were spent on, such as `transfer`, `room.transfer`, `workflow.run` or `room.start`. Each of these is a snapshot taken when the credits were spent, not a live lookup. Moving a key to another project, or deleting a project, does not rewrite what earlier periods reported. Usage recorded before project attribution existed is attributed to each key's current project, which the page states. A member whose access is scoped to particular projects sees only those projects' spend. The same breakdowns are available programmatically at `GET /v1/usage`, for pulling spend into your own reporting. See the [Account Management API](/docs/management-api). # Beam CLI (/docs/cli) The **Beam CLI** (`beam`) manages your Beam account, the machines connected to your organization, and Rooms from a terminal. The bundle installs two programs: the `beam` command, and the Beam agent that runs in the background on this machine so it can take part in Rooms. The Beam CLI does not create transfers. To run a transfer without writing code, or to build a pipeline, use [Beam Studio](/docs/studio). To build transfers into your code, use the [SDK](/docs/sdk): a transfer takes a few lines. *** ## Install [#install] The CLI ships as a compiled bundle from the release CDN, on macOS (`arm64`, `amd64`), Linux (`arm64`, `amd64`), and Windows (`amd64`). Each archive carries matching CLI and agent binaries, and the installer checks the archive's SHA-256 checksum before installing it. ```bash curl -fsSL https://cdn.b1m.ai/cli/install.sh | sh ``` This installs the `beam` command. On Windows, run the PowerShell installer instead of the shell one-liner: ```powershell irm https://cdn.b1m.ai/cli/install.ps1 | iex ``` A first interactive install launches `beam setup`, which can connect your Beam account, select an organization, name the machine, join a Room from an invitation, and install shell completion. For unattended installs, set `BEAM_SKIP_ONBOARDING=1` and run setup later. Keep the CLI and its agent current with `beam update`, or check without installing: ```bash beam update --check ``` *** ## Sign in [#sign-in] ```bash beam login beam whoami ``` `beam setup` is the guided path and is resumable. For automation it needs an explicit mode: ```bash beam setup --mode account --no-interactive ``` Modes are `account`, `room`, or `skip`. The mode is mandatory when non-interactive — setup will not guess. *** ## Contexts [#contexts] `beam` talks to the production authentication, API, and Registry services. Contexts let one installation hold several organizations or machines: ```bash beam context list beam context current beam context use ``` *** ## Checking your setup [#checking-your-setup] ```bash beam status beam doctor --fix ``` `beam status` reports what the CLI is connected to. `beam doctor` diagnoses a broken install and, with `--fix`, repairs what it can. `beam agent status` and `beam status` also report **Room control**: `healthy`, `connecting to the coordinator`, or `degraded since