The Sage Protocol SDK provides developers with a complete toolkit for building decentralized applications on Sui that leverage Sage’s social primitives and economic incentives. This SDK handles all the complexity of blockchain interactions, letting you focus on building engaging user experiences.

​
Installation

Install the SDK:

pnpm i @sageprotocol/sdk

​
Core Architecture

The Sage SDK offers two integration approaches:

Vanilla Client

Direct programmatic access to all Sage Protocol functions. Ideal for server-side applications, custom integrations, or when you need fine-grained control over transaction management.

React Wrapper

Provides React hooks and context providers that simplify state management and transaction handling in React applications. Built on top of the vanilla client with additional React-specific optimizations.

Both approaches support testnet and mainnet deployments, allowing you to develop and test before going to production.

​
Quick Start Example

Here’s a basic setup showing both approaches:

Vanilla Client Setup:

import { SageClient } from '@sageprotocol/sdk/client';

const sageClient = new SageClient({
  appId: '0x123...', // Your app's ID
  channelRegistryId: '0x456...', // Your app's channel registry
  network: 'testnet'
});

React Wrapper Setup:

import { SageProvider, useUser } from '@sageprotocol/sdk/react';

function App() {
  return (
    <SageProvider
      appId="0x123..."
      channelRegistryId="0x456..."
      network="testnet"
    >
      <UserProfile />
    </SageProvider>
  );
}

function UserProfile() {
  const { create } = useUser();
  
  ...
}

​
Prerequisites

1

Sui Wallet

Users need a Sui wallet to sign transactions.

Examples include Suiet, Phantom, Slush, and many more.

2

Network Selection

Choose testnet for development or mainnet for production.

3

Basic Sui Knowledge

Familiarity with Sui’s object model and transaction signing helps but isn’t required.

​
Key Concepts

​
Application Isolation

Content and channels are isolated per application, while user identities remain global across all Sage applications. This means users maintain consistent profiles and social graphs while experiencing app-specific content.

​
Transaction Patterns

All write operations return transactions that must be signed and executed by your users’ wallets. The SDK handles transaction construction while your application manages the signing flow:

const result = await sageClient.createUser({
  amounts: [0, 0],
  name: "john-doe",
  description: "Web3 enthusiast",
  self: walletAddress
});

if (result.ok) {
  await signAndExecuteTransaction({ transaction: result.transaction });
}

​
Error Handling

The SDK uses a consistent result pattern across all operations. Check the ok property before proceeding:

if (result.ok) {
  // Success: use result.transaction
} else {
  // Error: handle result.err
  console.error(result.err);
}

​
Use Cases

The Sage SDK enables various decentralized social applications:

  • Community Platforms: Reddit-style discussion forums with tokenized engagement
  • Social Networks: Twitter-like platforms with user-owned profiles and relationships
  • Creator Platforms: Medium-style publishing with direct creator-audience connections
  • Gaming Communities: Discord-like spaces with integrated reputation and rewards
  • Professional Networks: LinkedIn-style platforms with verifiable professional identities

​
What’s Next

This documentation covers the three core primitives you’ll work with:

  • Channels: Community spaces where users can post and interact
  • Posts: Content creation, commenting, and engagement
  • Users: Identity management, social connections, and profiles

Each section provides comprehensive examples and patterns for both vanilla client and React implementations.