JavaScript/TypeScript SDK (Web & Telegram Mini Apps)

The official @localcredit/sdk-js package makes integrating Localcredit into web apps or Telegram Mini Apps fast and secure. It handles authentication, proof signing, API calls, billing, and seamless redirects automatically.Installationbash

npm install @localcredit/sdk-js
# or
yarn add @localcredit/sdk-js

Setuptypescript

import { Localcredit } from '@localcredit/sdk-js';

// Initialize with your API key (from developer dashboard)
const lc = new Localcredit({
  apiKey: 'your_api_key_here',
  environment: 'production' // or 'test' for sandbox
});

1. Fetch User Scoretypescript

// Get the user's signed proof (wallet signature)
const userProof = await lc.requestProof(); 
// This opens a wallet modal (TON Connect for Mini Apps, WalletConnect for web)

// Query the score
try {
  const result = await lc.getScore(userProof);
  
  console.log('Score:', result.score);                 // 82
  console.log('Risk Tier:', result.riskTier);          // 'Low'
  console.log('Estimated Limit:', result.creditLimitUsd); // 5200
  console.log('Breakdown:', result.breakdown);
} catch (error) {
  if (error.code === 'NO_SCORE') {
    // User has no Localcredit profile yet
    await lc.redirectToOnboarding(); // seamless deep link
  }
}

2. Handle New Users (Redirect & Return)typescript

async function checkAndOnboard() {
  try {
    await lc.getScore(userProof);
  } catch (error) {
    if (error.code === 'PROOF_NOT_FOUND' || error.code === 'NO_SCORE') {
      // Redirect to official Mini App for onboarding
      await lc.redirectToOnboarding({
        returnUrl: window.location.href, // auto-return after signup
        appId: 'your_lending_app'       // optional tracking
      });
    }
  }
}

3. Report Loan Outcometypescript

await lc.reportOutcome({
  loanHash: '0x123abc...',
  outcome: 'repaid',           // 'repaid' | 'default' | 'partial'
  amountUsd: 2500,
  timestamp: Date.now(),
  details: { daysLate: 0 }
});

4. Manage Subscriptiontypescript

// Check current plan
const sub = await lc.getSubscription();

// Upgrade
await lc.createSubscription({
  plan: 'pro',                 // 'basic' | 'pro' | 'enterprise'
  stakeAmount: 10000           // $CREDIT
});

5. TON-Specific Features (Telegram Mini Apps)The SDK automatically detects TON environment and uses TON Connect.typescript

import { useTonConnectUI } from '@tonconnect/ui-react'; // optional direct control

// The SDK handles TON Connect internally, but you can pass a pre-connected wallet
const lc = new Localcredit({
  apiKey: 'your_key',
  tonConnectUI: tonConnectInstance // optional
});

Error Handlingtypescript

try {
  await lc.getScore(proof);
} catch (error) {
  console.error(error.code, error.message);
  // Common codes: INVALID_PROOF, INSUFFICIENT_FUNDS, RATE_LIMIT_EXCEEDED
}

Full TypeScript SupportAll methods are fully typed:typescript

interface ScoreResult {
  score: number;
  riskTier: 'Low' | 'Medium' | 'High';
  creditLimitUsd: number;
  breakdown: {
    repayment: number;
    consistency: number;
    identity: number;
    continuity: number;
    riskDeductions: number;
  };
}

The SDK abstracts away authentication, signatures, billing, and cross-environment differences so you can focus on building great user experiences.

Most integrations go live in under an hour.