Getting Started

This walkthrough takes you from an empty Next.js project to a working SDK call in five steps.

Before you start

• Familiarity with TypeScript
• A basic understanding of Stacks (wallets, transactions)
• An API key issued by the protocol team - see API Keys

The SDK is headless: a typed client for the protocol API plus transaction-building helpers, with no React and no UI. It covers contract deployment and signing, minting, burning and transfer, revenue-split configuration, and a fully typed API client. The React surface - data-fetching hooks, authentication, the app shell, design tokens - ships from the companion @rising-tide/ui package. Bring your own brand, or adopt those.

1. Install the SDK

The headless SDK and the companion @rising-tide/ui package both ship as tarballs, versioned in lockstep (ui imports types from sdk). This walkthrough uses hooks from @rising-tide/ui, so add both to your project's package.json, using the real filenames of the tarballs you were handed - the Changelog records the current versions:

{
  "dependencies": {
    "@rising-tide/sdk": "file:./rising-tide-sdk-<version>.tgz",
    "@rising-tide/ui": "file:./rising-tide-ui-<version>.tgz"
  }
}

Then run npm install. If you only need the typed API client and no React surface, install @rising-tide/sdk alone.

2. Entry points

The SDK is headless - three tree-shakeable entry points, no React or UI:

The React surface lives in the companion @rising-tide/ui package (depends on the SDK):

See the UI package page for what each one carries.

3. Initialize the client

// lib/sdk/client.ts
import { RisingTideSDK } from "@rising-tide/sdk";

export const rtConfig = {
  baseUrl: process.env.NEXT_PUBLIC_RT_API_URL!,
  apiKey: process.env.NEXT_PUBLIC_API_KEY,
  timeout: 30000,
};

export const rtClient = new RisingTideSDK(rtConfig);

4. Fetch a smart product

Service methods resolve to an ApiResponse<T> - a { data, error } union - so destructure data:

const { data: product } = await rtClient.smartProducts.getById(123);
console.log(product?.status);           // "PUBLISHED"
console.log(product?.currentInstances); // 3

5. React Query hooks

The data hooks live in @rising-tide/ui/react. Wrap your tree in RisingTideProvider (also exported as RisingTideQueryProvider), passing the same config you built the client with:

import { RisingTideProvider } from "@rising-tide/ui/react";
import { rtConfig } from "@/lib/sdk/client";

export default function Providers({ children }) {
  return <RisingTideProvider config={rtConfig}>{children}</RisingTideProvider>;
}

Then in any component:

import { useSmartProduct } from "@rising-tide/ui/react";

function ProductCard({ id }: { id: number }) {
  // the query resolves to ApiResponse<SmartProduct>, so unwrap .data
  const { data: response } = useSmartProduct(id);
  return <div>{response?.data?.title}</div>;
}

To add authentication (Privy or BYOW) and a full user session on top of the query layer, use the consolidated RisingTideProviders from @rising-tide/ui/providers instead - one config-driven stack that wires Privy, the auth providers, and the query client in the required order. See Authentication.

Next steps

• Environments - configure testnet vs mainnet
• Authentication - add user login
• Concepts - understand smart products, instances, and revenue