SDK Reference

import { configureApi, getSDKInfo, SDK_NAME, SDK_VERSION, api } from '@coin-communities/sdk';

function configureApi(options: ConfigureApiOptions): void

import { configureApi } from '@coin-communities/sdk';
 
configureApi({
  baseUrl: 'https://api.coin-communities.xyz',
  headers: { 'x-api-key': 'YOUR_API_KEY' },
});

function getSDKInfo(): SDKInfo

import { getSDKInfo } from '@coin-communities/sdk';
 
const info = getSDKInfo();
// { name: '@coin-communities/sdk', version: '0.0.8', platform: 'react' }

configureApi({
  baseUrl: 'https://api.coin-communities.xyz',
  headers: { 'x-api-key': process.env.CC_API_KEY },
});

configureApi({
  baseUrl: 'https://api.coin-communities.xyz',
  auth: () => sessionStorage.getItem('token') ?? '',
});

configureApi({
  baseUrl: 'https://api.coin-communities.xyz',
  headers: {
    'x-server-key': process.env.CC_SERVER_KEY,
    'x-server-secret': process.env.CC_SERVER_SECRET,
  },
});

type ConfigureApiOptions = Pick<Config, 'baseUrl' | 'fetch' | 'headers' | 'auth'>;

interface SDKInfo {
  name: string;
  version: string;
  platform: Platform;
}

type Platform = 'react' | 'react-native' | 'node';

const SDK_NAME: string

const SDK_VERSION: string

import { configureApi, api } from '@coin-communities/sdk';
 
configureApi({
  baseUrl: 'https://api.coin-communities.xyz',
  headers: { 'x-api-key': 'YOUR_KEY' },
});
 
const { data, error } = await api.getCommunity({
  path: { token_address: '7eYw...' },
});
 
if (error) {
  console.error('failed', error.message);
} else {
  console.log(data.community.tokenAddress);
}

// Path params
await api.getCommunity({ path: { token_address: '7eYw...' } });
 
// Query params
await api.getMessages({ path: { token_address: '7eYw...' }, query: { limit: 50 } });
 
// Body
await api.postMessage({
  path: { token_address: '7eYw...' },
  body: { content: 'gm', chainId: 'solana', walletAddress: 'YourWalletPubkey' },
});

// Resolved automatically when bundled for browser or React Native
import { CommunityRealtimeClient } from '@coin-communities/sdk';
// or explicit subpath
import { CommunityRealtimeClient } from '@coin-communities/sdk/react';
import { CommunityRealtimeClient } from '@coin-communities/sdk/react-native';

const client = CommunityRealtimeClient.getOrCreate({
  baseUrl: 'https://api.coin-communities.xyz',
  tokenAddress: '7eYw...',
  auth: {
    // Fetches a fresh single-use ticket on connect and every reconnect.
    getTicket: async () => {
      const { data } = await api.getWsTicket({ path: { token_address: '7eYw...' } });
      if (!data?.ticket) throw new Error('WebSocket ticket unavailable');
      return data.ticket;
    },
  },
});
 
const dispose = client.subscribe({
  onMessage:    (event) => console.log('message persisted', event),
  onModeration: (event) => console.log('moderation update', event),
  onLike:       (event) => console.log('like update', event),
  onGap:        () => console.log('reconnected — refetch via REST'),
  onConnect:    () => console.log('connected'),
  onDisconnect: () => console.log('disconnected'),
});
 
// Later:
dispose(); // unsubscribe this handler (connection shared with other subscribers)

import { useCommunityEvents } from '@coin-communities/sdk';
 
useCommunityEvents(tokenAddress, {
  auth: { getTicket: async () => /* return ws ticket string */ },
  onMessage:    (event) => { /* message persisted */ },
  onModeration: (event) => { /* spam/harmful flags changed */ },
  onLike:       (event) => { /* like update */ },
  onGap:        () => { /* reconnected — refetch via REST */ },
});

function useCommunityRealtime(
  tokenAddress: string,
  options?: UseCommunityRealtimeOptions,
): { lastEvent: RealtimeEvent | null; status: RealtimeStatus }

import { useCommunityRealtime } from '@coin-communities/sdk';
 
function ConnectionBadge({ tokenAddress }: { tokenAddress: string }) {
  const { status, lastEvent } = useCommunityRealtime(tokenAddress, {
    auth: async () => { /* return ws ticket */ },
  });
 
  return <span>{status === 'open' ? '🟢' : '🔴'} {lastEvent?.type}</span>;
}

function realtimeAuthFromApiClient(
  client: Client,
  tokenAddress: string,
): RealtimeGetTicketAuth

import { realtimeAuthFromApiClient, CommunityRealtimeClient } from '@coin-communities/sdk';
import { createClient } from '@hey-api/client-fetch';
 
const httpClient = createClient({ baseUrl: 'https://api.coin-communities.xyz' });
const auth = realtimeAuthFromApiClient(httpClient, '7eYw...');
 
const rtClient = CommunityRealtimeClient.getOrCreate({
  baseUrl: 'https://api.coin-communities.xyz',
  tokenAddress: '7eYw...',
  auth,
});

function bindCommunityEventsToQueryClient(
  queryClient: QueryClient,
  tokenAddress: string,
  options?: { baseUrl?: string; auth?: RealtimeAuth },
): () => void

import { bindCommunityEventsToQueryClient } from '@coin-communities/sdk';
import { QueryClient } from '@tanstack/react-query';
 
const qc = new QueryClient();
const unsubscribe = bindCommunityEventsToQueryClient(qc, '7eYw...', {
  baseUrl: 'https://api.coin-communities.xyz',
  auth: { getTicket: async () => (await api.getWsTicket({ path: { token_address: '7eYw...' } })).data?.ticket ?? '' },
});
 
// Later:
unsubscribe();

type RealtimeAuth = RealtimeGetTicketAuth | RealtimeStaticTicketAuth;

interface RealtimeGetTicketAuth {
  getTicket: () => Promise<string>;
}

interface RealtimeStaticTicketAuth {
  ticket: string;
}

interface RealtimeHandlers {
  onMessage?:    (e: CommunityMessageEvent) => void;
  onLike?:       (e: LikeUpdatePayload) => void;
  onModeration?: (e: ModerationUpdatePayload) => void;
  onGap?:        () => void;
  onConnect?:    () => void;
  onDisconnect?: () => void;
}

type RealtimeEvent =
  | { eventType: 'message_update'; data: CommunityMessageEvent }
  | { eventType: 'like_update';    data: LikeUpdatePayload }
  | { eventType: 'moderation_update'; data: ModerationUpdatePayload };

const RealtimeEventTypes = {
  MessageUpdate:    'message_update',
  LikeUpdate:       'like_update',
  ModerationUpdate: 'moderation_update',
} as const;

type RealtimeEventType = 'message_update' | 'like_update' | 'moderation_update';

type RealtimeStatus = 'connecting' | 'open' | 'closed';

interface CommunityMessageEvent {
  id: string;
  communityId: string;
  businessId: string;
  userId: string;
  username: string;
  userTwitterUrl: string;
  profileImageUrl: string | null;
  followerCount: number;
  content: string;
  mediaUrl: string | null;
  isSpam: boolean;
  isHarmful: boolean;
  createdAt: string;
  parentMessageId: string | null; // non-null when this is a reply
}

interface LikeUpdatePayload {
  messageId: string;
  liked: boolean; // true = like added; false = like removed
}

interface ModerationUpdatePayload {
  messageId: string;
  communityId: string;
  isSpam: boolean;
  isHarmful: boolean;
}

interface RealtimeClientOptions {
  baseUrl: string;
  tokenAddress: string;
  auth?: RealtimeAuth;
  reconnectBaseMs?: number;  // default 500ms
  reconnectCapMs?: number;   // default 30 000ms
  heartbeatIntervalMs?: number; // default 0 (disabled — see note below)
  heartbeatTimeoutMs?: number;  // default 10 000ms
}

type Community = {
  id: string;
  tokenAddress: string;
  createdAt: string;
};

type TopCommunity = {
  tokenAddress: string;
  tokenSymbol: string;
  tokenImageUrl?: string | null;
  tokenHighResImageUrl?: string | null;
  chainId?: number | null;
  memberCount: number;
  postCount: number;
  totalLikes: number;
  latestPostAt: number; // Unix ms
};

type Message = {
  id: string;
  communityId: string;
  businessId: string;
  userId: string;
  tokenAddress: string;
  content: string;
  mediaUrl?: string | null;
  walletAddress?: string | null;
  username: string;
  displayName: string;
  userTwitterUrl: string;
  profileImageUrl?: string | null;
  followerCount: number;
  likeCount: number;
  liked: boolean;
  replyCount: number;
  parentMessageId?: string | null;
  isSpam: boolean;
  isHarmful: boolean;
  source?: string | null;
  deletedAt?: string | null;
  deletedReason?: string | null;
  createdAt: string;
};

type FeedItem = {
  id: string;
  communityId: string;
  tokenAddress: string;
  tokenSymbol?: string | null;
  tokenImageUrl?: string | null;
  content: string;
  mediaUrl?: string | null;
  username: string;
  displayName: string;
  profileImageUrl?: string | null;
  userTwitterUrl: string;
  walletAddress?: string | null;
  followerCount: number;
  likeCount: number;
  liked?: boolean | null;
  replyCount: number;
  source?: string | null;
  createdAt: string;
};

type User = {
  id: string;
  twitterId: string;
  username: string;
  profileImageUrl?: string | null;
  followerCount: number;
  followerCountSyncedAt?: string | null;
  nativeFollowerCount: number;
  nativeFollowingCount: number;
  createdAt: string;
};

type UserProfile = {
  id: string;
  username: string;
  profileImageUrl?: string | null;
  followerCount: number;
  nativeFollowerCount: number;
  nativeFollowingCount: number;
  createdAt: string;
};

type CommunityMember = {
  userId: string;
  username: string;
  displayName: string;
  profileImageUrl?: string | null;
  twitterUrl: string;
  followerCount: number;
  messageCount: number;
};

type WalletLink = {
  id: string;
  userId: string;
  businessId: string;
  address: string;
  chainType: ChainType;
  createdAt: string;
};

type Business = {
  id: string;
  name: string;
  rateLimitPerSecond: number;
  createdAt: string;
};

type BusinessUser = {
  id: string;
  businessId: string;
  email: string;
  emailVerified: boolean;
  role: string;
  createdAt: string;
};

type ApiKey = {
  id: string;
  businessId: string;
  createdBy: string;
  name: string;
  keyPrefix: string;
  keyHash: string;
  lastUsedAt?: string | null;
  revokedAt?: string | null;
  createdAt: string;
};

type ServerApiKey = {
  id: string;
  businessId: string;
  createdBy: string;
  name: string;
  keyPrefix: string;
  keyHash: string;
  lastUsedAt?: string | null;
  revokedAt?: string | null;
  createdAt: string;
};

type ApiKeyOrigin = {
  id: string;
  apiKeyId: string;
  origin: string;
  createdAt: string;
};

type WhitelistedCallback = {
  id: string;
  businessId: string;
  url: string;
  createdAt: string;
};

type MediaProvider = {
  id: string;
  name: string;
  logoUrl: string;
  searchUrl: string;
  domains: string[];
};

type ApiLogEvent = {
  apiKeyId: string;
  businessId: string;
  method: string;
  path: string;
  statusCode: number;
  latencyMs: number;
  createdAt: string;
};

type MessageLike = {
  messageId: string;
  userId: string;
  businessId: string;
  createdAt: string;
};

type WsTicketResponse = {
  ticket: string;
};

type ChainId = 'solana' | 'ethereum' | 'base' | 'bsc';

type ChainType = 'evm' | 'svm';

type MessageSortField = 'time' | 'likes';

type MessageSortOrder = 'desc' | 'asc';

type ReportReason =
  | 'spam'
  | 'harassment'
  | 'hate_speech'
  | 'inappropriate_content'
  | 'other';

type LinkKind = 'community' | 'post';

type LinkResponse = {
  code: string;
  kind: LinkKind;
  tokenAddress: string;
  messageId?: string | null;
};

type PostMessageRequest = {
  content: string;                // required
  chainId: ChainId;               // required
  walletAddress: string;          // required — must be a linked wallet
  mediaUrl?: string | null;       // must be a URL from uploadCommunityMedia
  invalidateCache?: boolean | null; // force-refresh wallet-link and balance-eligibility cache before posting
};

type GetMessagesQuery = {
  before?: string | null;          // cursor (message id) for time-sorted pagination
  offset?: number | null;          // offset for likes-sorted pagination
  limit?: number | null;           // default 50, max 100
  sort?: MessageSortField | null;  // default 'time'
  order?: MessageSortOrder | null; // default 'desc'
  filterIsSpam?: boolean | null;   // exclude spam-classified messages
  filterIsHarm?: boolean | null;   // exclude harm-classified messages
};

type GetRepliesQuery = {
  before?: string | null;          // cursor (reply id) for pagination
  limit?: number | null;
  order?: MessageSortOrder | null; // default 'desc'
};

type ReportMessageRequest = {
  reason: ReportReason;  // required
  text?: string | null;  // required when reason is 'other'
};

type GetLogsParams = {
  apiKeyId?: string | null;    // filter to a specific API key
  method?: string | null;      // HTTP method e.g. 'GET'
  path?: string | null;        // request path prefix
  statusClass?: number | null; // 2 = 2xx, 4 = 4xx, 5 = 5xx
  startTime?: string | null;   // ISO-8601 lower bound
  endTime?: string | null;     // ISO-8601 upper bound
  limit?: number;
  offset?: number;             // default 0
};

type LinkWalletRequest = {
  address: string;      // required — wallet public address
  chainType: ChainType; // required
  signature: string;    // required — signature over the nonce from walletChallenge
};

type WalletChallengeRequest = {
  address: string;      // required
  chainType: ChainType; // required
};

type TwitterAuthUrlQuery = {
  redirectUrl: string; // required — must be whitelisted in your business dashboard
};

type TwitterChallengeExchangeRequest = {
  challengeCode: string; // single-use, short-lived
};

type UploadMediaRequest = {
  contentType: string; // e.g. 'image/jpeg'
  data: string;        // base64-encoded file content
};

type AddOriginRequest = {
  origin: string; // e.g. 'https://app.example.com' — no path, no trailing slash
};

type BatchGetCommunitiesRequest = {
  tokenAddresses: string[]; // required — list of on-chain token addresses
};

type PostMessageServerRequest = {
  content: string;                  // required
  chainId: ChainId;                 // required
  walletAddress: string;            // required — must be a linked wallet
  twitterId: string;                // required — user to attribute the post to
  invalidateCache?: boolean | null; // drop cached balance-eligibility before posting
};

type GetGlobalMessagesQuery = {
  before?: string | null;          // cursor (message id) for backward pagination
  since?: number | null;           // lookback: only messages at/after this unix-ms timestamp
  limit?: number | null;           // default 100, max 500
  order?: MessageSortOrder | null;
  includeReplies?: boolean | null; // include replies alongside root messages (default false)
  filterIsSpam?: boolean | null;
  filterIsHarm?: boolean | null;
};

type CreateLinkRequest = {
  kind: LinkKind;           // required
  tokenAddress: string;     // required — the community token address
  messageId?: string | null; // required when kind is 'post'
};

type PublicMessageResponse = {
  id: string;
  content: string;
  username: string;
  displayName: string;
  profileImageUrl?: string | null;
  likeCount: number;
  replyCount: number;
};

type BatchGetUsersByWalletRequest = {
  addresses: string[]; // required — wallet public addresses to look up
};

type BatchGetUsersByWalletResponse = {
  results: Record<string, BatchUserByWalletResult>;
};
 
type BatchUserByWalletResult =
  | {
      status: 'ok';
      user_id: string;
      twitter_id: string;
      username: string;
      display_name: string;
      profile_image_url?: string | null;
    }
  | { status: 'notFound' };