TypeScript SDK

The official TypeScript SDK — zero dependencies, works in Node 18+ and any modern runtime with native fetch.

Installation

npm install @sova-intel/sdk
# or
pnpm add @sova-intel/sdk

Setup

API key

import { SovaIntelClient } from "@sova-intel/sdk";

const client = new SovaIntelClient({
  baseUrl: "https://api.sova-intel.com/api/v1",
  auth: {
    kind: "apikey",
    apiKey: process.env.SOVA_API_KEY!,
  },
});

X402 autonomous payment

import { SovaIntelClient } from "@sova-intel/sdk";

const client = new SovaIntelClient({
  baseUrl: "https://api.sova-intel.com/api/v1",
  auth: {
    kind: "x402",
    buildPayment: async (payTo, amountBaseUnits) => {
      // build USDC transferChecked tx, return base64 payment header
      // see Authentication page for full implementation
    },
  },
});

Examples

Get a wallet HUD (1cr)

const hud = await client.getWalletHud("7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU");

console.log(hud.behaviorCode);      // "SWING_TRADER"
console.log(hud.winRate);           // 0.67
console.log(hud.trimmedMeanPnl);    // 12.4
console.log(hud.dataQualityTier);   // "GOLD"
console.log(hud.isBot);             // false

The SDK handles cold wallet 202 fallback automatically — you always get back a WalletHud.

Full wallet profile (5cr)

const profile = await client.getWalletProfile("7xKXtg...");

console.log(profile.summary.realizedPnl);         // 142.87
console.log(profile.behavior?.tradingStyle);       // "swing"
console.log(profile.pnl?.allTime?.netPnlSol);     // 152.17

Per-token PnL table (3cr)

const tokens = await client.getWalletTokens("7xKXtg...", {
  pageSize: 50,
  sortBy: "realizedPnlSol",
  sortOrder: "DESC",
});

for (const token of tokens.data) {
  console.log(token.tokenAddress, token.realizedPnlSol, token.roi);
}

Batch HUD for multiple wallets (5cr flat)

const batch = await client.batchHud(["addr1", "addr2", "addr3"]);

for (const [address, hud] of Object.entries(batch.huds)) {
  console.log(address, hud.behaviorCode, hud.winRate);
}
console.log("No data:", batch.notFound);

Holder profiles — async (20cr)

The poll variant queues the job, polls until complete, and returns the result:

import type { HolderProfilesResult } from "@sova-intel/sdk";

const result = await client.pollHolderProfiles<HolderProfilesResult>(
  "So11111111111111111111111111111111111111112",
  20, // top N holders
);

for (const holder of result.profiles) {
  console.log(holder.rank, holder.walletAddress, holder.supplyPercent, holder.behaviorType);
}

Similarity analysis — async (20cr)

const result = await client.pollSimilarity(["addr1", "addr2", "addr3"]);
console.log(result);

Client Configuration

const client = new SovaIntelClient({
  baseUrl: "https://api.sova-intel.com/api/v1", // required
  auth: { ... },                                 // required
  pollIntervalMs: 5000,                          // default: 5000ms
  maxPollAttempts: 60,                           // default: 60 (~5 min)
});

Error Handling

import { SovaIntelClient, SovaHttpError, X402PaymentError } from "@sova-intel/sdk";

try {
  const hud = await client.getWalletHud(address);
} catch (err) {
  if (err instanceof X402PaymentError) {
    // Payment failed
    console.error("Payment error:", err.body);
  } else if (err instanceof SovaHttpError) {
    switch (err.status) {
      case 404: console.error("Wallet not found or result expired"); break;
      case 422: console.error("System/program wallet — skip"); break;
      case 500: console.error("Server error — retry with backoff"); break;
    }
  }
}

Exported Types

import type {
  WalletHud,
  WalletProfileResponse,
  WalletSummary,
  WalletBehavior,
  PnlAllTime,
  DataQualityTier,
  TokenPnlRow,
  TokenPnlResponse,
  TokenPnlParams,
  BatchHudResponse,
  HolderProfile,
  HolderProfilesResult,
  JobAcceptedResponse,
  JobStatus,
  SovaIntelClientConfig,
  Auth,
  ApiKeyAuth,
  X402Auth,
} from "@sova-intel/sdk";

Method Reference

Method	Endpoint	Credits
getWalletProfile(addr)	GET /intel/wallet/:addr	5
getWalletHud(addr)	GET /intel/wallet/:addr/hud	1
getWalletTokens(addr, params?)	GET /intel/wallet/:addr/tokens	3
batchHud(wallets[])	POST /intel/wallets/batch-hud	5
queueHolderProfiles(mint, topN?)	POST /intel/token/:mint/holders	20
pollHolderProfiles(mint, topN?)	same + auto-poll	20
queueSimilarity(wallets[])	POST /intel/wallets/similarity	20
pollSimilarity(wallets[])	same + auto-poll	20