@3mate/walrus-sponsor-sdk

Official SDK for 3mate Walrus Sponsor — sponsored blob storage on the Walrus network.

Zero runtime dependencies. Works in Node.js 18+ and modern browsers.

Install

npm install @3mate/walrus-sponsor-sdk

Quick Start

import { WalrusSponsor } from "@3mate/walrus-sponsor-sdk";

const walrus = new WalrusSponsor({
  apiKey: "sbk_live_...",
  baseUrl: "https://your-backend.com",
});

// Upload a file (browser)
const file = document.querySelector<HTMLInputElement>("#file")!.files![0];
const result = await walrus.upload(file, {
  creatorAddress: "0x123...",
  epochs: 3,
});

console.log("View:", walrus.getBlobUrl(result.blobId));

API

Constructor

new WalrusSponsor({
  apiKey: string;         // Required — your API key (sbk_live_...)
  baseUrl: string;        // Required — your backend URL
  aggregatorUrl?: string; // Optional — defaults to mainnet aggregator
});

Methods

| Method | Description | |--------|-------------| | health() | Check if backend is live | | epoch() | Get current Walrus epoch info | | estimateCost(size, epochs?) | Estimate WAL storage cost | | upload(file, opts) | Upload a file via sponsored publisher | | listBlobs(opts?) | List blobs with optional filters | | getBlob(id) | Get single blob details | | getBlobUrl(blobId) | Build aggregator URL (no network call) |

Upload

// Browser — File or Blob
await walrus.upload(file, { creatorAddress: "0x..." });

// Node.js — Buffer
await walrus.upload(
  { data: buffer, filename: "photo.png", contentType: "image/png" },
  { creatorAddress: "0x...", epochs: 3 }
);

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | creatorAddress | string | — | Required. Sui address to own the blob | | epochs | number | 1 | Storage duration in epochs | | deletable | boolean | true | Whether the blob can be deleted |

List & Get Blobs

const { blobs, total } = await walrus.listBlobs({
  status: "active",
  creatorAddress: "0x...",
  limit: 10,
  offset: 0,
});

const blob = await walrus.getBlob("0x1234...");

Estimate Cost

const cost = await walrus.estimateCost(1024 * 1024, 3); // 1 MB, 3 epochs
console.log(cost.totalCost);   // WAL amount as string
console.log(cost.storageCost); // storage component
console.log(cost.writeCost);   // write component

Error Handling

import { WalrusSponsorError } from "@3mate/walrus-sponsor-sdk";

try {
  await walrus.upload(file, opts);
} catch (err) {
  if (err instanceof WalrusSponsorError) {
    console.error(err.message);    // Human-readable message
    console.error(err.statusCode); // 401, 402, 502, etc.
    console.error(err.details);    // Raw API error body
  }
}

| Status | Meaning | |--------|---------| | 401 | Invalid or missing API key | | 402 | Insufficient workspace balance | | 502 | Storage service unavailable |

License

MIT