#Configuration

Configure the Walbucket SDK to match your needs. All configuration is done when creating a new Walbucket instance.

#Required Fields

#apiKey (required)

Your API key for authentication. Get your API key from the Walbucket Developer Console:

  1. Go to the Developer Console (use the Console link in the navigation bar)
  2. Sign in with your wallet
  3. Navigate to the Developer section, then go to API Keys
  4. Click Create API Key to generate a new key
  5. Copy your API key and use it in your configuration
apiKey: "your-api-key";
typescript

Security Note: Always store your API key in environment variables and never commit it to version control. For client-side applications, use environment variables prefixed with NEXT_PUBLIC_ (Next.js) or similar build-time environment variable injection.

#Gas Strategy Fields (one required)

Depending on your gasStrategy, you need to provide either:

  • sponsorPrivateKey - Required if using gasStrategy: 'developer-sponsored' (default)
  • signAndExecuteTransaction + userAddress - Required if using gasStrategy: 'user-pays'

#Optional Fields

#network

Sui network to use. Package ID is automatically selected based on network.

network?: 'testnet' | 'mainnet' | 'devnet' | 'localnet'
typescript

Default: 'testnet'

#encryption

Enable Seal encryption for uploaded files.

encryption?: boolean
typescript

Default: true

#gasStrategy

Choose who pays gas fees for transactions.

gasStrategy?: 'developer-sponsored' | 'user-pays'
typescript

Default: 'developer-sponsored'

  • 'developer-sponsored' - Developer pays all gas fees (better UX, requires sponsorPrivateKey)
  • 'user-pays' - Users pay their own gas fees (more decentralized, requires userSigner)

#cacheTTL

Cache TTL in seconds for asset metadata.

cacheTTL?: number
typescript

Default: 3600 (1 hour)

#Advanced Configuration

These fields are usually auto-detected and don't need to be set:

  • packageId - Override auto-detected package ID
  • walrusPublisherUrl - Override auto-detected Walrus publisher URL
  • walrusAggregatorUrl - Override auto-detected Walrus aggregator URL
  • sealServerIds - Override auto-detected Seal server IDs

#Configuration Interface

interface WalbucketConfig {
  // Required
  apiKey: string;

  // Required based on gasStrategy choice
  sponsorPrivateKey?: string; // Required if gasStrategy is 'developer-sponsored'
  signAndExecuteTransaction?: SignAndExecuteTransaction; // Required if gasStrategy is 'user-pays'
  userAddress?: string; // Required if gasStrategy is 'user-pays'

  // Optional with smart defaults
  network?: "testnet" | "mainnet" | "devnet" | "localnet"; // Default: 'testnet'
  encryption?: boolean; // Default: true
  gasStrategy?: "developer-sponsored" | "user-pays"; // Default: 'developer-sponsored'

  // Auto-detected (usually don't need to set)
  packageId?: string; // Auto-detected from network
  walrusPublisherUrl?: string; // Auto-detected from network
  walrusAggregatorUrl?: string; // Auto-detected from network
  sealServerIds?: string[]; // Auto-detected from network
  cacheTTL?: number; // Default: 3600 seconds
  useGrpc?: boolean; // Default: true
}
typescript

#Examples

#Basic Configuration (Developer-Sponsored)

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

#Mainnet Configuration

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

#Without Encryption

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

#User-Pays Gas Strategy

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

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

#Custom Cache TTL

const walbucket = new Walbucket({
  apiKey: "your-api-key",
  network: "testnet",
  sponsorPrivateKey: "your-private-key",
  cacheTTL: 7200, // 2 hours
});
typescript

#Learn More