#Quick Start

Get started with Walbucket SDK in just a few lines of code.

#Installation

Install the SDK using your preferred package manager:

pnpm add @walbucket/sdk
# or
npm install @walbucket/sdk
# or
yarn add @walbucket/sdk
bash

#Get Your API Key

Before you can use the SDK, you'll need an API key. Get your API key from the Walbucket Developer Console:

  1. Navigate to the Developer Console (use the Console link in the navigation bar)
  2. Sign in with your wallet
  3. Go to the Developer section, then navigate to API Keys
  4. Click Create API Key to generate a new key
  5. Copy your API key and store it securely

Note: Keep your API key secret. Never commit it to version control or expose it in client-side code. You can access the Developer Console anytime via the Console link in the top navigation.

#Initialize SDK

First, import and initialize the SDK with your API key:

#Developer-Sponsored (Default)

Developer pays gas fees - best user experience:

import { Walbucket } from "@walbucket/sdk";

// Initialize SDK with developer-sponsored gas
const walbucket = new Walbucket({
  apiKey: "your-api-key",
  network: "testnet",
  gasStrategy: "developer-sponsored", // default
  sponsorPrivateKey: "your-private-key",
});
typescript

#User-Pays (React + Wallet)

Users pay their own gas fees:

import {
  useSignAndExecuteTransaction,
  useCurrentAccount,
} from "@mysten/dapp-kit";
import { Walbucket } from "@walbucket/sdk";

function MyComponent() {
  const { mutateAsync: signAndExecuteTransaction } =
    useSignAndExecuteTransaction();
  const currentAccount = useCurrentAccount();

  const walbucket = new Walbucket({
    apiKey: "your-api-key",
    network: "testnet",
    gasStrategy: "user-pays",
    signAndExecuteTransaction,
    userAddress: currentAccount?.address,
  });
}
typescript

#Upload a File

Upload files with a simple method call:

const result = await walbucket.upload(file, {
  name: "my-image.jpg",
  folder: "products",
});

console.log(result.assetId); // Sui object ID
console.log(result.url); // Automatically generated file URL
typescript

The upload method accepts various file formats:

  • File (from file input)
  • Blob
  • Buffer
  • Uint8Array
  • File path string

#Retrieve a File

Retrieve files by their asset ID:

const retrieveResult = await walbucket.retrieve(result.assetId);
console.log("File data:", retrieveResult.data);
console.log("File URL:", retrieveResult.url);
console.log("Metadata:", retrieveResult.metadata);
typescript

#Delete a File

Delete files when you no longer need them:

await walbucket.delete(result.assetId);
typescript

#Complete Example

Here's a complete example that demonstrates the basic workflow:

import { Walbucket } from "@walbucket/sdk";

// Initialize
const walbucket = new Walbucket({
  apiKey: "your-api-key",
  network: "testnet",
  sponsorPrivateKey: "your-private-key",
});

// Upload
const uploadResult = await walbucket.upload(file, {
  name: "photo.jpg",
  folder: "gallery",
});

console.log("Uploaded!", uploadResult.url);

// Retrieve
const retrieveResult = await walbucket.retrieve(uploadResult.assetId);
console.log("File size:", retrieveResult.metadata.size);

// Delete (when needed)
await walbucket.delete(uploadResult.assetId);
typescript

#What's Next?