> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sageprotocol.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

>  

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](http://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:

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm i @sageprotocol/sdk
  ```

  ```bash yarn theme={null}
  yarn add @sageprotocol/sdk
  ```

  ```bash npm theme={null}
  npm i @sageprotocol/sdk
  ```
</CodeGroup>

## 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:

```typescript theme={null}
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.

<Accordion title="Direct Javacript Integration Example" icon="rectangle-code" iconType="sharp-solid">
  ```javascript theme={null}
  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();
  ```
</Accordion>

## 5. Create Your First User

Create a new Sage user using React hooks (temporarily requires invite code):

```typescript theme={null}
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;
```

<Accordion title="Direct Javacript Integration Example" icon="rectangle-code" iconType="sharp-solid">
  ```typescript theme={null}
  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);
  }
  ```
</Accordion>

## 6. Verify Successful Setup (React Hook)

After creating a user, verify your setup by creating a basic post:

```typescript theme={null}
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;
```

<Accordion title="Direct Javacript Integration Example" icon="rectangle-code" iconType="sharp-solid">
  ```javascript theme={null}
  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);
  }
  ```
</Accordion>

## 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.