Skip to main content

​
Overview

createChipiServer provides a singleton ChipiServerSDK instance for server-side operations in Next.js. It ensures only one SDK instance exists across your application, with automatic config conflict detection. Import everything from @chipi-stack/nextjs/server: 
import {
  createChipiServer,
  getChipiServer,
  resetChipiServer,
} from "@chipi-stack/nextjs/server";

​
Setup

Create a shared server configuration file (e.g. lib/chipi-server.ts): 
import { createChipiServer } from "@chipi-stack/nextjs/server";

export const chipiServer = createChipiServer({
  apiPublicKey: process.env.CHIPI_PUBLIC_KEY!,
  apiSecretKey: process.env.CHIPI_SECRET_KEY!,
});
apiPublicKey and apiSecretKey are both required. The function throws immediately if either is missing. Keep apiSecretKey server-only — never expose it in client bundles or NEXT_PUBLIC_* environment variables.

​
Functions

​
createChipiServer(config)

Creates or returns the singleton ChipiServerSDK instance.
ParameterTypeRequiredDescription
apiPublicKeystringYesYour Chipi public API key
apiSecretKeystringYesYour Chipi secret API key
alphaUrlstringNoCustom API base URL (advanced)
nodeUrlstringNoCustom Starknet RPC node URL
Returns: ChipiServerSDK

​
Config Conflict Detection

If createChipiServer is called a second time with a different config, it throws an error instead of silently ignoring the new config. This prevents hard-to-debug issues where different parts of your app expect different configurations. 
// First call — creates the singleton
createChipiServer({ apiPublicKey: "pk_1", apiSecretKey: "sk_1" });

// Second call with same config — returns the existing instance (no-op)
createChipiServer({ apiPublicKey: "pk_1", apiSecretKey: "sk_1" });

// Second call with different config — throws an error
createChipiServer({ apiPublicKey: "pk_2", apiSecretKey: "sk_2" });
// Error: createChipiServer() was called with a different config than the
// existing singleton. Call resetChipiServer() first if you need to reconfigure.

​
getChipiServer()

Returns the existing singleton instance. Throws if createChipiServer has not been called yet. Returns: ChipiServerSDK 
import { getChipiServer } from "@chipi-stack/nextjs/server";

// In any server-side code after initial setup
const chipi = getChipiServer();

​
resetChipiServer()

Destroys the existing singleton instance so that a new one can be created with createChipiServer. Primarily useful for testing. 
import { resetChipiServer, createChipiServer } from "@chipi-stack/nextjs/server";

// In a test setup / teardown
resetChipiServer();
const freshInstance = createChipiServer({ /* new config */ });

​
Usage in Server Components

import { chipiServer } from "@/lib/chipi-server";

export default async function WalletPage({ params }: { params: { userId: string } }) {
  const wallet = await chipiServer.wallets.getWallet({
    externalUserId: params.userId,
  });

  return (
    <div>
      <h1>Wallet</h1>
      <p>Address: {wallet.accountAddress}</p>
      <p>Public Key: {wallet.publicKey}</p>
    </div>
  );
}

​
Usage in Route Handlers

import { chipiServer } from "@/lib/chipi-server";
import { NextResponse } from "next/server";

export async function POST(request: Request) {
  const { externalUserId } = await request.json();

  const wallet = await chipiServer.wallets.createWallet({
    externalUserId,
  });

  return NextResponse.json(wallet);
}

​
Usage in Server Actions

"use server";

import { chipiServer } from "@/lib/chipi-server";

export async function getWalletBalance(userId: string) {
  const balance = await chipiServer.wallets.getTokenBalance({
    externalUserId: userId,
    token: "USDC",
  });

  return balance;
}