Setup & Configuration - Dialect Developer Documentation

Get the Dialect TypeScript SDK installed and configured in your environment. This guide covers installation, client setup, authentication, and environment configuration.

Installation

Install the core SDK and blockchain-specific packages for your needs:

npm
yarn
pnpm

# Core SDK (required)
npm install @dialectlabs/sdk

# Blockchain SDK for Solana
npm install @dialectlabs/blockchain-sdk-solana

# Core SDK (required)
yarn add @dialectlabs/sdk

# Blockchain SDK for Solana
yarn add @dialectlabs/blockchain-sdk-solana

# Core SDK (required)
pnpm add @dialectlabs/sdk

# Blockchain SDK for Solana
pnpm add @dialectlabs/blockchain-sdk-solana

App Registration

Before using the SDK, you need to register your app. You can do this either:

Via Dashboard: Follow our Dashboard registration guide to register
Via SDK: Register programmatically using the SDK tab in the registration guide

Wallet Credentials Setup

If you registered via SDK: Your DIALECT_SDK_CREDENTIALS should already be set up from the registration process. If you registered via Dashboard: You need to extract the private key from the wallet you used to register and format it as DIALECT_SDK_CREDENTIALS. Your app is tied to the specific keypair used during registration:

Export from your wallet app: Open Phantom, Solflare, etc. → Settings → Export Private Key → Copy the private key
Convert to array format: Use a tool like this to convert base58 private key to JSON array format [170,23,...,300]
Set in environment: Add the array format to your .env file as DIALECT_SDK_CREDENTIALS

You must use the same wallet that was used to register your app. The app registration is tied to that specific keypair and cannot be changed to a different wallet.

Secure Your Credentials: Keep your DIALECT_SDK_CREDENTIALS secure. This is your app’s private key and should never be exposed in client-side code or committed to version control.

SDK Client Setup

Basic SDK Initialization

import { Dialect, DialectCloudEnvironment, DialectSdk } from "@dialectlabs/sdk";
import {
  Solana,
  SolanaSdkFactory,
  NodeDialectSolanaWalletAdapter,
} from "@dialectlabs/blockchain-sdk-solana";

// Initialize SDK
const environment: DialectCloudEnvironment = "development";
const dialectSolanaSdk: DialectSdk<Solana> = Dialect.sdk(
  {
    environment,
  },
  SolanaSdkFactory.create({
    // IMPORTANT: must set environment variable DIALECT_SDK_CREDENTIALS
    // to your dapp's Solana messaging wallet keypair e.g. [170,23, . . . ,300]
    wallet: NodeDialectSolanaWalletAdapter.create(),
  })
);

// Load your dApp
const dapp = await dialectSolanaSdk.dapps.find();

if (!dapp) {
  throw new Error("Dapp not found. Please register your app first.");
}

console.log('✅ SDK initialized and dApp loaded!');

Environment-Specific Setup

// For production deployment, update the environment
const environment: DialectCloudEnvironment = "production"; // Change to "development" for testing

const dialectSolanaSdk = Dialect.sdk(
  {
    environment,
  },
  SolanaSdkFactory.create({
    // IMPORTANT: must set environment variable DIALECT_SDK_CREDENTIALS
    // to your dapp's Solana messaging wallet keypair e.g. [170,23, . . . ,300]
    wallet: NodeDialectSolanaWalletAdapter.create(),
  })
);

Troubleshooting

Common Issues

1. Invalid Credentials

Error: Invalid wallet credentials
# Solution: Check your DIALECT_SDK_CREDENTIALS format
echo $DIALECT_SDK_CREDENTIALS | jq . # Should be valid JSON array

2. Dapp Not Found

Error: Dapp not found
# Solution: Register your app first via dashboard or SDK

​Installation

​App Registration

​Wallet Credentials Setup

​SDK Client Setup

​Basic SDK Initialization

​Environment-Specific Setup

​Troubleshooting

​Common Issues

Installation

App Registration

Wallet Credentials Setup

SDK Client Setup

Basic SDK Initialization

Environment-Specific Setup

Troubleshooting

Common Issues