@3mate/walrus-sponsor-sdk

Official SDK & CLI for Walrus Sponsor Service — 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

# For CLI usage (global)
npm install -g @3mate/walrus-sponsor-sdk

Quick Start

SDK (programmatic)

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

const client = new WalrusSponsor({
  apiKey: "sbk_live_...",
  // baseUrl defaults to https://walrus-sponsor.krill.tube
});

// Upload a file (Node.js)
const result = await client.upload("./photo.jpg", {
  creatorAddress: "0x123...",
  epochs: 5,
});

console.log("Blob ID:", result.blob_id);
console.log("View:", client.getBlobUrl(result.blob_id));

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

CLI

# Configure (API key stored in OS keychain — never plaintext on disk)
krilly config set-key sbk_live_abc123...

# Upload
krilly upload ./photo.jpg --creator 0x123... --epochs 5

# List blobs
krilly blobs --status active --pretty

# Get blob details
krilly blob 0xabc...

# Estimate cost
krilly cost --size 1048576 --epochs 3 --pretty

API Reference

Constructor

new WalrusSponsor({
  apiKey: string;              // Required — sbk_live_...
  baseUrl?: string;            // Default: https://walrus-sponsor.krill.tube
  aggregatorUrl?: string;      // Default: https://aggregator.walrus-mainnet.walrus.space
});

Methods

| Method | Description | Returns | |--------|-------------|---------| | health() | Check if service is live | { status, timestamp } | | epoch() | Get current Walrus epoch info | { currentEpoch, startTime, endTime } | | storageCost(size, epochs) | Estimate WAL storage cost | { total_cost, storage_cost, write_cost } | | upload(file, opts) | Upload file (sponsor pays WAL) | { blob_id, tx_digest, ... } | | blobs(opts?) | List blobs (filter by status/creator) | { blobs[], total } | | blob(id) | Get single blob detail | BlobDetail | | delete(blobId, systemObjId) | Delete blob, reclaim storage | { tx_digest, storage_returned } | | extend(opts) | Extend blob storage duration | { new_end_epoch, tx_digest } | | fund(blobId, coinId) | Add WAL funds to a blob | { tx_digest } | | register(opts) | Advanced: client-side upload step 1 | { blob_object_id, tx_digest } | | certify(opts) | Advanced: client-side upload step 2 | { sponsored_blob_id, tx_digest } | | getBlobUrl(blobId) | Get aggregator download URL | string |

Upload Options

client.upload(file, {
  creatorAddress: "0x...",  // Required — who owns the blob
  epochs: 5,               // Storage duration (default: 1)
  deletable: true,         // Allow deletion before expiry (default: true)
  filename: "photo.jpg",   // Optional filename override
  contentType: "image/jpeg", // Optional MIME type
});

The file parameter accepts:

• Node.js: string (file path), Buffer, Uint8Array, ReadableStream
• Browser: File, Blob

CLI Commands

Config

krilly config set-key <api_key>        # Save API key (OS keychain)
krilly config set-url <url>            # Set backend URL
krilly config set-aggregator <url>     # Set aggregator URL
krilly config show                     # Show current config

🔒 API keys are stored in your OS keychain (macOS Keychain / Linux libsecret). Falls back to AES-256-GCM encrypted file if keychain is unavailable.

Operations

krilly health
krilly epoch
krilly cost --size <bytes> --epochs <n>

krilly upload <file> --creator <address> [--epochs <n>] [--deletable]
krilly blobs [--status <s>] [--creator <addr>] [--limit <n>] [--offset <n>]
krilly blob <id>
krilly delete <id> --system-object <id>
krilly extend <id> --epochs <n> --system-object <id> --payment-coin <id>
krilly fund <id> --coin <id>

krilly url <blob_id>

Add --pretty to any command for formatted JSON output.

Error Handling

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

const client = new WalrusSponsor({ apiKey: "sbk_live_..." });

try {
  await client.upload("./file.txt", { creatorAddress: "0x..." });
} catch (err) {
  if (err instanceof WalrusSponsorError) {
    console.error(`API Error [${err.status}]: ${err.message}`);
    // err.code — e.g. "INSUFFICIENT_BALANCE", "RATE_LIMIT_EXCEEDED"
  }
}

Security

• API keys are never stored in plaintext on disk
• macOS: stored in Keychain (security CLI)
• Linux: stored in GNOME Keyring / KDE Wallet (secret-tool)
• Fallback: AES-256-GCM encrypted file at ~/.krilly/.vault
• Non-secret config (baseUrl) stored in ~/.krilly/config.json

License

MIT — 3mate Labs

AI Agent Integration

Krilly is designed to be agent-friendly. Give your AI agent decentralized storage in one line:

import { WalrusSponsor } from "krilly";

const walrus = new WalrusSponsor({
  apiKey: process.env.WALRUS_API_KEY, // set in agent environment
});

// Upload agent-generated content
const result = await walrus.upload(
  { data: Buffer.from(output), filename: "report.json", contentType: "application/json" },
  { creatorAddress: "0x...", epochs: 5 }
);

// Permanent, decentralized URL — no auth needed to read
const url = walrus.getBlobUrl(result.blob_id);

For Agent Frameworks

Each SDK method maps 1:1 to a tool/function call:

| Tool | Method | Description | |------|--------|-------------| | walrus_upload | upload(file, opts) | Store file on Walrus | | walrus_list | blobs(opts?) | List stored blobs | | walrus_get | blob(id) | Get blob metadata | | walrus_cost | estimateCost(size, epochs) | Estimate cost | | walrus_delete | delete(id, sysObj) | Delete blob | | walrus_extend | extend(opts) | Extend storage | | walrus_url | getBlobUrl(id) | Get download URL |

Works with LangChain, CrewAI, AutoGPT, OpenClaw, or any framework that supports npm packages.

CLI for Shell-Based Agents

export WALRUS_API_KEY=sbk_live_...
krilly config set-key $WALRUS_API_KEY
krilly upload ./data.json --creator 0x... --epochs 5
krilly blobs --pretty

See full docs: https://walrus-sponsor.krill.tube/docs/ai-agents