Skip to main content
This guide will help you quickly set up and integrate the Sage SDK into your React application. Follow these steps to begin building decentralized social experiences with Sage.

​
1. Prerequisites

Ensure your environment meets these requirements:
  • Node.js and npm: Install Node.js (v18 or higher) and npm (nodejs.org).
  • Sui Wallet: Obtain a Sui blockchain wallet (e.g., Suiet, Phantom, Slush) for transaction signing.
  • Invite Codes (temporary requirement): Valid invite codes and invite keys are required for user creation and are provided by Sage.
  • Network Access: Choose your network environment:
    • mainnet: production environment
    • testnet: development and testing environment

​
2. Installation

Install the Sage SDK via your preferred package manager: 
pnpm i @sageprotocol/sdk

​
3. Choose Integration Method

The Sage SDK supports two integration methods:
  • React Integration: Use built-in React hooks and the SageProvider for state-managed React apps.
  • Direct JavaScript Integration: Directly use the SageClient class for explicit SDK management.

​
4. React Direct Integration Setup

Use built-in React hooks and the SageProvider to manage state in your React app: 
import { SageProvider } from '@sageprotocol/sdk/react';

const App = () => (
  <SageProvider
    appId="your-app-id"                    // Unique app context (required)
    channelRegistryId="your-registry-id"   // Channel registry ID (required)
    network="testnet"                      // 'mainnet' or 'testnet' (default: 'mainnet')
  >
    {/* Your app components here */}
  </SageProvider>
);

export default App;
Your React application must handle wallet connections for transaction signing. Ensure your users connect their Sui wallet, and your app can request and execute signatures properly. 
import { SageClient } from '@sageprotocol/sdk';

const sage = new SageClient({
  appId: 'your-app-id',                   // explicitly required unique app context
  channelRegistryId: 'your-registry-id',  // required channel registry ID
  network: 'testnet'                      // or 'mainnet' (default: 'mainnet')
});

await sage.initialize();

​
5. Create Your First User

Create a new Sage user using React hooks (temporarily requires invite code): 
import { useUser } from '@sageprotocol/sdk/react';
import { useWallet } from '@suiet/wallet-kit';

function CreateUserComponent() {
  const { create } = useUser();
  const { account, signAndExecuteTransaction } = useWallet();

  async function handleCreateUser() {
    const result = await create({
      amounts: [0, 0],                          // Required default amounts
      avatar: 0,                                // Optional avatar blob ID
      banner: 0,                                // Optional banner blob ID
      description: "Web3 and React enthusiast", // User bio (markdown supported)
      inviteCode: "your-invite-code",           // Required invite code
      inviteKey: "your-invite-key",             // Required invite key
      name: "john-doe",                         // Unique username
      self: account.address                     // Wallet address
    });

    if (result.ok) {
      await signAndExecuteTransaction({ transaction: result.transaction });
      console.log("User created successfully!");
    } else {
      console.error(result.err);
    }
  }

  return <button onClick={handleCreateUser}>Create User</button>;
}

export default CreateUserComponent;

const result = await sageClient.createUser({
  amounts: [0, 0],                           // required default amounts
  avatar: 0,                                 // optional avatar blob ID (default 0)
  banner: 0,                                 // optional banner blob ID (default 0)
  description: "Web3 enthusiast and developer",
  inviteCode: "WELCOME123",                  // required invite code
  inviteKey: "0x789.",                       // required invite key
  name: "john-doe",                          // globally unique username
  self: walletAddress                        // user's wallet address
});

if (result.ok) {
  await signAndExecuteTransaction({ transaction: result.transaction });
  console.log('User created successfully!');
} else {
  console.error('Error creating user:', result.err);
}

​
6. Verify Successful Setup (React Hook)

After creating a user, verify your setup by creating a basic post: 
import { useUser } from '@sageprotocol/sdk/react';
import { useWallet } from '@suiet/wallet-kit';

const CreatePostComponent = ({ ownedUserId, sharedUserId }) => {
  const { post } = useUser();
  const { account, signAndExecuteTransaction } = useWallet();

  const handleCreatePost = async () => {
    const result = await post({
      amounts: [0, 0],
      data: 'Excited to join the Sage community!', 
      description: 'My first decentralized post',
      ownedUserId,
      self: account.address,
      sharedUserId,
      title: 'Hello Sage!'
    });

    if (result.ok) {
      await signAndExecuteTransaction({ transaction: result.transaction });
      console.log("Post created successfully!");
    } else {
      console.error(result.err);
    }
  };

  return <button onClick={handleCreatePost}>Create Post</button>;
};

export default CreatePostComponent;

const postResult = await sageClient.postToUser({
  amounts: [0, 0],                                // Required protocol fees
  appId: 'your-app-id',                           // Required application ID
  network: 'testnet',                             // 'testnet' or 'mainnet'
  sharedUserId: 'target-user-shared-id',          // Target user's shared user object
  title: 'Hello Sage!',                           // Post headline/title (markdown supported)
  description: 'My first decentralized post',     // Summary description (markdown supported)
  data: 'Excited to join the Sage community!',    // Main post content (markdown supported)
  ownedUserId: 'your-owned-user-id',              // Poster's owned user object
  self: walletAddress                             // Poster's wallet address
});

if (postResult.ok) {
  await signAndExecuteTransaction({ transaction: postResult.transaction });
  console.log('Post created successfully!');
} else {
  console.error('Error creating post:', postResult.err);
}

​
7. Next Steps

You’re now set up and ready to explore the full capabilities of Sage SDK. Proceed to:
  • Key Concepts: Understand important SDK patterns and best practices.
  • Core Primitives: Explore the features for managing users, channels, and posts.
  • API Reference: See comprehensive SDK documentation for advanced usage.