Beam SDK

The Beam SDK creates transfers and drives their lifecycle from your own code. It prepares a transfer, signs the routes workers will use, hands the work to the network, and reconciles the terminal status.

Provider credentials stay in your process. The SDK signs task-scoped routes locally, so your S3, R2, or Hippius keys are never sent to Beam or to a participant.

Packages

All of them reach the same network and spend the same organization credits, and every transfer they create appears together in the Console.

The Beam CLI (beam) is a separate tool: it manages your account, your machines, and Rooms, and does not create transfers.

Install

python -m pip install "beam-network-sdk[s3]"

The Python package signs object-storage access through an extra: s3 for Amazon S3 and S3-compatible storage, r2 for Cloudflare R2, or all. Hippius and plain HTTP transfers need no extra.

npm install @beam-network/sdk

go get github.com/Beam-Network/beam-sdk-public/sdks/go

beam-network-sdk = "0.5"

Authenticate

Every client needs a Beam API key from the Console. Pass it from the environment rather than committing it:

export BEAM_API_KEY=b1m_...

That is the only configuration a client needs: every SDK targets production and resolves its endpoints itself.

The lifecycle

Every language follows the same three steps:

1. Create — describe sources and destinations. The SDK reads the source object, prepares the transfer, and signs routes locally.
2. Distribute — hand the transfer to the network. Orchestrators assign workers, which move bytes directly between your endpoints.
3. Wait — block on a terminal status, or poll it yourself.

Creating a transfer distributes it by default, so in code the first two steps are one call. To prepare a transfer and hand it to the network later, opt out: distribute: false in TypeScript, distribute=False in Python, Distribute: beamnetworksdk.Bool(false) in Go.

Waiting has a timeout, 300 seconds by default in every SDK. Raise it for large files, as the snippets below do.

See How Transfers Work for what the network does during each step.

The snippets below copy an object between two buckets on an S3-compatible store — MinIO here, but Wasabi, Backblaze B2, DigitalOcean Spaces, and Hippius S3 work the same way — reading its endpoint and credentials from S3_ENDPOINT_URL, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY.

TypeScript

import { BeamClient, S3CompatibleProviderConfig } from "@beam-network/sdk";

const beam = new BeamClient({ apiKey: process.env.BEAM_API_KEY! });

const storage = {
  provider: "minio",
  endpoint_url: process.env.S3_ENDPOINT_URL!,
  access_key_id: process.env.S3_ACCESS_KEY_ID!,
  secret_access_key: process.env.S3_SECRET_ACCESS_KEY!,
};

const transfer = await beam.createTransfer({
  sources: [
    S3CompatibleProviderConfig.create({ ...storage, bucket: "source-bucket", key: "data/file.bin" }),
  ],
  destinations: [
    S3CompatibleProviderConfig.create({ ...storage, bucket: "destination-bucket", key: "data/file.bin" }),
  ],
  name: "first-transfer",
});

// Wait up to an hour.
const status = await beam.waitForTransfer(transfer.transfer_id, { timeoutMs: 3_600_000 });
console.log(status.status);

Go

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	beamnetworksdk "github.com/Beam-Network/beam-sdk-public/sdks/go"
)

func main() {
	ctx := context.Background()

	client := beamnetworksdk.NewClient(
		beamnetworksdk.WithAPIKey(os.Getenv("BEAM_API_KEY")),
	)
	defer client.Close()

	source, err := beamnetworksdk.NewS3CompatibleProviderSource(beamnetworksdk.S3CompatibleProviderSource{
		Provider:        "minio",
		EndpointURL:     os.Getenv("S3_ENDPOINT_URL"),
		Bucket:          "source-bucket",
		Key:             "data/file.bin",
		AccessKeyID:     os.Getenv("S3_ACCESS_KEY_ID"),
		SecretAccessKey: os.Getenv("S3_SECRET_ACCESS_KEY"),
	})
	if err != nil {
		log.Fatal(err)
	}
	destination, err := beamnetworksdk.NewS3CompatibleProviderDestination(beamnetworksdk.S3CompatibleProviderDestination{
		Provider:        "minio",
		EndpointURL:     os.Getenv("S3_ENDPOINT_URL"),
		Bucket:          "destination-bucket",
		Key:             "data/file.bin",
		AccessKeyID:     os.Getenv("S3_ACCESS_KEY_ID"),
		SecretAccessKey: os.Getenv("S3_SECRET_ACCESS_KEY"),
	})
	if err != nil {
		log.Fatal(err)
	}

	transfer, err := client.CreateProviderTransfer(ctx, beamnetworksdk.ProviderTransferOptions{
		Sources:      []beamnetworksdk.ProviderSource{source},
		Destinations: []beamnetworksdk.ProviderDestination{destination},
		Name:         "first-transfer",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Wait up to an hour; 0 keeps the default poll interval.
	status, err := client.WaitForTransfer(ctx, transfer.TransferID, time.Hour, 0)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(status.Status)
}

The Python equivalent is in the Developer Quickstart.

Storage providers

The S3-compatible config above covers any store with a custom endpoint. Amazon S3, Cloudflare R2, and Hippius have dedicated configs, and plain HTTPS endpoints need no provider at all. Every provider config keeps credentials in your process and mints task-scoped access for workers. The TypeScript and Python SDKs also read from Box and write into Box folders; see Box. Google Cloud Storage works through the S3-compatible config with an HMAC key; see Google Cloud Storage.

See Connectors for the fields each one needs and the bucket permissions the SDK requires.

Source code

Next steps

• Developer Quickstart — Send your first transfer.
• Connectors — Configure the storage you move data between.
• How Transfers Work — The lifecycle behind these calls.
• API Reference — Read your transfers over HTTP from any language.