SocialFi SDK for JavaScript, React and Python

import { CabalSpyID } from 'cabalspy-id';

const csid = new CabalSpyID({ apiKey: process.env.CABALSPY_API_KEY });

const me = await csid.me(); // instance, plan, rate limit, users with data

// The person who just signed in: look them up by the sub of their ID token
const profile = await csid.profile({ csid_id: claims.sub });
const wallet = profile.wallets.find((w) => w.chains.includes('solana'))!;

// Full trading profile for a period, same numbers as the CabalSpy API
const t = await csid.tracker({ blockchain: 'solana', address: wallet.address, period: '7d' });
console.log(t.period_stats.realized_pnl_usd);

// Your users ranked by PnL
const board = await csid.leaderboard({ blockchain: 'solana', period: '7d', sort: 'pnl_usd', limit: 25 });

from cabalspy_id import CabalSpyID

csid = CabalSpyID()  # reads CABALSPY_ID_API_KEY, then CABALSPY_API_KEY

me = csid.me()  # instance, plan, rate limit, users with data

# The person who just signed in: look them up by the sub of their ID token
profile = csid.profile(csid_id=claims["sub"])
wallet = next(w for w in profile["wallets"] if "solana" in w["chains"])

# Full trading profile for a period, same numbers as the CabalSpy API
t = csid.tracker(blockchain="solana", address=wallet["address"], period="7d")
print(t["period_stats"]["realized_pnl_usd"])

# Your users ranked by PnL
board = csid.leaderboard(blockchain="solana", period="7d", sort="pnl_usd", limit=25)

for await (const user of csid.iterUsers({ kol: true })) console.log(user.username);
for await (const trade of csid.iterHistory({ blockchain: 'solana', address })) console.log(trade.tx_signature);
for await (const entry of csid.iterLeaderboard({ blockchain: 'base', period: '30d' })) console.log(entry.rank);

for user in csid.iter_users(kol=True):
    print(user["username"])
for trade in csid.iter_history(blockchain="solana", address=address):
    print(trade["tx_signature"])
for entry in csid.iter_leaderboard(blockchain="base", period="30d"):
    print(entry["rank"])

import { NotFoundError, PlanUserLimitError, RateLimitError } from 'cabalspy-id';

try {
  await csid.profile({ csid_id: claims.sub });
} catch (err) {
  if (err instanceof PlanUserLimitError) return showUpgradeNotice(); // anon_ sub: no data until you upgrade
  if (err instanceof NotFoundError) return null;                     // not one of your users
  if (err instanceof RateLimitError) console.log(err.retryAfter);
  throw err;
}

from cabalspy_id import NotFoundError, PlanUserLimitError, RateLimitError

try:
    csid.profile(csid_id=claims["sub"])
except PlanUserLimitError:
    show_upgrade_notice()          # anon_ sub: no data until you upgrade
except NotFoundError:
    pass                           # not one of your users
except RateLimitError as err:
    print(err.retry_after)

const stream = csid.stream({ blockchain: 'solana' }); // omit blockchain for every chain

stream.on('trade', (t) => console.log(t.trader?.username, t.transaction_type, t.token_symbol, t.value_usd));
stream.on('error', (e) => console.error(e.code, e.message));
await stream.connect(); // resolves once the server confirmed the subscription

// or
for await (const trade of csid.stream()) console.log(trade);

# async only, needs: pip install "cabalspy-id[stream]"
from cabalspy_id import AsyncCabalSpyID

async with AsyncCabalSpyID() as csid:
    stream = csid.stream(blockchain="solana")  # omit blockchain for every chain

    @stream.on("trade")
    def on_trade(t):
        print(t["trader"]["username"], t["transaction_type"], t["token_symbol"], t["value_usd"])

    await stream.connect()        # returns once the server confirmed the subscription
    await stream.run_forever()    # until stream.close() or a fatal error

import { CabalSpyIDAuth, isLimited } from 'cabalspy-id';

const auth = new CabalSpyIDAuth({
  clientId: process.env.CSID_CLIENT_ID!,         // csid_...
  clientSecret: process.env.CSID_CLIENT_SECRET,  // csid_sk_... (omit for public clients)
  redirectUri: 'https://your.app/callback',      // registered in the dashboard
});

// GET /login
const login = await auth.createAuthorizationUrl({ scope: ['openid', 'profile', 'wallets', 'offline_access'] });
// keep login.state, login.nonce and login.codeVerifier (session or signed http-only cookie)
redirect(login.url);

// GET /callback
const { tokens, claims } = await auth.handleCallback(request.url, stored);

if (isLimited(claims)) {
  // over your plan's user limit: anonymous sub "anon_...", no profile or wallet data
} else {
  const user = await auth.userinfo(tokens.access_token); // x profile, wallets, onchain
}

import os
from cabalspy_id import CabalSpyIDAuth, is_limited

auth = CabalSpyIDAuth(
    "csid_...",                                      # your instance's client_id
    client_secret=os.environ["CSID_CLIENT_SECRET"],  # csid_sk_... (omit for public clients)
    redirect_uri="https://your.app/callback",        # registered in the dashboard
)

# GET /login
req = auth.create_authorization_url(scope=["openid", "profile", "wallets", "offline_access"])
session["csid"] = req.to_dict()   # state, nonce, code_verifier, redirect_uri
return redirect(req.url)

# GET /callback
result = auth.handle_callback(request.url, **session.pop("csid"))

if is_limited(result.claims):
    ...  # over your plan's user limit: anonymous sub "anon_...", no profile or wallet data
else:
    user = auth.userinfo(result.tokens["access_token"])  # x profile, wallets, onchain

import { CabalSpyIDAuth, isLimited } from 'cabalspy-id';

const auth = new CabalSpyIDAuth({ clientId: 'csid_...' });
const claims = await auth.verifyIdToken(idToken); // ES256 via JWKS: iss, aud, azp, exp
if (isLimited(claims)) {
  // anonymous sub, no profile data
}

from cabalspy_id import CabalSpyIDAuth, is_limited

auth = CabalSpyIDAuth("csid_...")
claims = auth.verify_id_token(id_token_from_the_browser)
if is_limited(claims):
    ...  # anonymous sub, no profile data

const { can_post } = await csid.thesisEligibility({ blockchain: 'solana', mint, csid_id: claims.sub });
if (can_post) {
  const t = await csid.postThesis({ blockchain: 'solana', mint, body: 'Accumulating here.', stance: 'bull', csid_id: claims.sub });
}
const list = await csid.listTheses({ blockchain: 'solana', mint, sort: 'new' });

ok = csid.thesis_eligibility(blockchain="solana", mint=mint, csid_id=claims["sub"])
if ok["can_post"]:
    t = csid.post_thesis(blockchain="solana", mint=mint, body="Accumulating here.", stance="bull", csid_id=claims["sub"])
theses = csid.list_theses(blockchain="solana", mint=mint, sort="new")

const stream = csid.stream({ events: ['theses'], blockchain: 'solana', mint });
stream.on('thesis', (t) => console.log('new thesis', t.id));
await stream.connect();

stream = csid.stream(events=["theses"], blockchain="solana", mint=mint)  # AsyncCabalSpyID

@stream.on("thesis")
def on_thesis(t):
    print("new thesis", t["id"])

await stream.connect()

import { ThesisClient } from 'cabalspy-id';

const theses = new ThesisClient({ accessToken }); // from csid:login / useCabalSpyID()
const { items, token, summary } = await theses.list('solana', mint, { sort: 'top' });
const me = await theses.me('solana', mint);       // { can_post, can_reply, holder, paused, user }
if (me.can_post) await theses.post('solana', mint, { body: 'Strong community, still early.', stance: 'bull' });

const live = theses.live('solana', mint);
live.on('thesis', prepend).on('reply', addReply).on('reaction', updateCounts).on('removed', ({ id }) => drop(id));
await live.connect();

from cabalspy_id import ThesisClient

with ThesisClient(access_token=result.tokens["access_token"]) as theses:
    page = theses.list("solana", mint, sort="top")     # items, pagination, token, summary
    if theses.me("solana", mint)["can_post"]:
        theses.post("solana", mint, body="Strong community, still early.", stance="bull")

import { verifyWebhook } from 'cabalspy-id';

const event = await verifyWebhook({ payload: rawBody, headers: req.headers, secret: process.env.CSID_WEBHOOK_SECRET! });

switch (event.type) {
  case 'wallet.verified': /* event.data.sub, event.data.address */ break;
  case 'consent.revoked': /* delete the user's data */ break;
}

import os
from cabalspy_id import verify_webhook

event = verify_webhook(request.body, request.headers, os.environ["CSID_WEBHOOK_SECRET"])

if event["type"] == "consent.revoked":
    delete_user_data(event["data"]["sub"])