TypeScript SDK

Integrate Halo Protocol into your application. Query trust scores, manage circles, and interact with on-chain data programmatically.

Overview

The @halo-protocol/sdk package provides a TypeScript client for interacting with the Halo Protocol smart contract on Solana. It wraps all on-chain instructions, handles PDA derivation, and provides typed account fetchers and event listeners.

  • -Full TypeScript types for all accounts and instructions
  • -Automatic PDA derivation for circles, escrow, members, and trust scores
  • -Built-in transaction builders with compute budget optimization
  • -Works with any Solana wallet adapter
  • -Compatible with Node.js, browser, and React Native environments

Installation

Install the SDK using npm, yarn, or pnpm:

# npm
npm install @halo-protocol/sdk @solana/web3.js @coral-xyz/anchor
# yarn
yarn add @halo-protocol/sdk @solana/web3.js @coral-xyz/anchor
# pnpm
pnpm add @halo-protocol/sdk @solana/web3.js @coral-xyz/anchor

Quick Start

Initialize the client and fetch a trust score:

import { HaloClient } from "@halo-protocol/sdk";
import { Connection, PublicKey } from "@solana/web3.js";

// Initialize client
const connection = new Connection(
  "https://api.mainnet-beta.solana.com"
);
const halo = new HaloClient(connection);

// Fetch trust score for a wallet
const walletAddress = new PublicKey("YOUR_WALLET_ADDRESS");
const trustScore = await halo.getTrustScore(walletAddress);

console.log("Score:", trustScore.score);       // 0-1000
console.log("Tier:", trustScore.tier);         // Newcomer | Silver | Gold | Platinum
console.log("History:", trustScore.paymentHistory);
console.log("Completion:", trustScore.circleCompletion);

Create a Circle

Build and send a transaction to create a new lending circle:

import { HaloClient } from "@halo-protocol/sdk";
import { useWallet } from "@solana/wallet-adapter-react";

const wallet = useWallet();
const halo = new HaloClient(connection);

// Create a lending circle
const tx = await halo.createCircle({
  name: "Community Savers",
  contributionAmount: 10_000_000,  // 10 USDC (6 decimals)
  frequency: "monthly",
  maxMembers: 5,
  minTrustScore: 250,              // Silver tier minimum
  creator: wallet.publicKey,
});

// Sign and send
const signature = await wallet.sendTransaction(tx, connection);
console.log("Circle created:", signature);

Available Methods

getTrustScore(wallet)Fetch the trust score account for a wallet address.
getCircle(circleAddress)Fetch circle account data including members and state.
getCirclesForMember(wallet)List all circles a wallet is a member of.
createCircle(params)Build a transaction to create a new lending circle.
joinCircle(circleAddress, wallet)Build a transaction to join an existing circle.
contribute(circleAddress, wallet, amount)Build a transaction to make a round contribution.
distributePayout(circleAddress, authority)Build a transaction to distribute the round payout.
initializeTrustScore(wallet)Build a transaction to initialize a trust score account.

Full Documentation

For complete API documentation, advanced usage, error handling, and examples, visit the full docs.

View Full DocsGitHub