HawkFi SDK

A comprehensive TypeScript SDK for interacting with HawkFi's blockchain APIs and DeFi protocols on Solana. This SDK provides a unified interface for managing liquidity positions, executing transactions, and interacting with multiple DeFi protocols including Meteora, Orca, Raydium, and Jupiter.

🚀 Features

• Multi-Protocol Support: Full integration with Meteora DLMM, Orca Whirlpools, Raydium V2, and Jupiter
• Transaction Management: Comprehensive transaction generation, signing, and execution
• Position Management: Create, deposit, withdraw, and close liquidity positions
• Automation: Automated workflows for compounding, rebalancing, and limit orders
• Account Management: PDA generation, token account handling, and caching
• Health Monitoring: API health checks and system status monitoring
• Portfolio Management: User portfolio tracking and position analytics

📦 Installation

npm install @hawksightco/hawk-sdk

or

yarn add @hawksightco/hawk-sdk

🏗️ Architecture

The SDK is built around a modular architecture with the following key components:

Core Classes

HawkAPI - Main Entry Point

The central orchestrator that provides access to all SDK functionality:

import { HawkAPI } from '@hawksightco/hawk-sdk';

const hawkAPI = new HawkAPI('https://api2.hawksight.co');

TxGenerator - Transaction Management

Handles creation and management of blockchain transactions for all supported protocols.

Client - HTTP Client

Wrapper around the Swagger client for API communication with error handling.

Protocol Modules

• Meteora: DLMM position management, automation, fast generation
• Orca: Whirlpools position management, reward claiming
• Raydium: V2 position management, NFT handling
• Jupiter: Token swaps, routing optimization

🔧 Quick Start

Basic Setup

import { HawkAPI } from '@hawksightco/hawk-sdk';
import { Connection, PublicKey } from '@solana/web3.js';

// Initialize connection and SDK
const connection = new Connection('https://api.mainnet-beta.solana.com');
const hawkAPI = new HawkAPI('https://api2.hawksight.co');

// Check API health
const health = await hawkAPI.health.check();
console.log('API Health:', health);

Get User Portfolio

const portfolio = await hawkAPI.general.getPortfolio({
  wallet: 'user_wallet_address'
});

console.log('User Portfolio:', portfolio);

Create a Meteora Position

import { BN } from 'bn.js';

const position = await hawkAPI.txGenerator.meteora.createPositionAndDeposit({
  connection,
  params: {
    position: new PublicKey('position_address'),
    pool: new PublicKey('pool_address'),
    userWallet: new PublicKey('user_wallet'),
    totalXAmount: new BN(1000000), // 1 token with 6 decimals
    totalYAmount: new BN(1000000), // 1 token with 6 decimals
    binRange: { lowerRange: 100, upperRange: 200 },
    distribution: 'SPOT',
    slippage: 0.01 // 1%
  }
});

console.log('Position Created:', position);

Execute Batch Transactions

const result = await hawkAPI.batchExecute({
  connection,
  payer: new PublicKey('payer_address'),
  instructions: [...], // Array of instructions
  signers: [...], // Array of signers
  lookupTableAddresses: [...] // Address lookup tables
});

console.log('Batch Execution Result:', result);

📚 API Reference

HawkAPI Class

Constructor

new HawkAPI(url?: string, options?: HawkApiOptions)

Properties

• health: Health check utilities
• general: General API operations
• generalUtility: General utility endpoints
• util: Utility functions
• txGenerator: Transaction generation
• txGeneratorAutomation: Automated transaction workflows
• search: Token search functionality
• ix: Simple instruction generator
• jupAlts: Jupiter alternatives
• jupiterSwap: Jupiter swap functionality
• pda: Simple PDA generator

Methods

• anchor(connection): Get Anchor program instance
• mintCache(connection): Get mint cache instance
• tokenCache(connection): Get token cache instance
• combine(params): Combine multiple transactions
• batchExecute(params): Execute batch transactions
• atomicity(params): Execute atomic transactions
• logging(flag): Enable/disable logging
• raydiumSDK(connection): Get Raydium SDK instance

Transaction Generation

Meteora Operations

// Create position and deposit
await hawkAPI.txGenerator.meteora.createPositionAndDeposit(params);

// Deposit to existing position
await hawkAPI.txGenerator.meteora.deposit(params);

// Withdraw from position
await hawkAPI.txGenerator.meteora.withdraw(params);

// Close position
await hawkAPI.txGenerator.meteora.close(params);

// Claim rewards
await hawkAPI.txGenerator.meteora.claim(params);

// Compound rewards
await hawkAPI.txGenerator.meteora.compound(params);

// Rebalance position
await hawkAPI.txGenerator.meteora.rebalance(params);

Orca Operations

// Open position
await hawkAPI.txGenerator.orca.openPosition(params);

// Close position
await hawkAPI.txGenerator.orca.closePosition(params);

// Deposit to position
await hawkAPI.txGenerator.orca.deposit(params);

// Withdraw from position
await hawkAPI.txGenerator.orca.withdraw(params);

// Claim rewards
await hawkAPI.txGenerator.orca.claimRewards(params);

Raydium Operations

// Open position
await hawkAPI.txGenerator.raydium.openPosition(params);

// Close position
await hawkAPI.txGenerator.raydium.closePosition(params);

// Increase liquidity
await hawkAPI.txGenerator.raydium.increaseLiquidity(params);

// Decrease liquidity
await hawkAPI.txGenerator.raydium.decreaseLiquidity(params);

Utility Functions

PDA Generation

import { generateUserPda, generateAta, generateLimitToken } from '@hawksightco/hawk-sdk';

const userPda = generateUserPda(userWallet);
const ata = generateAta(owner, mint);
const limitToken = generateLimitToken(userPda, mint);

Transaction Utilities

import { createTxMetadata, resultOrError } from '@hawksightco/hawk-sdk';

const metadata = await createTxMetadata(generalUtility, connection, payer, data);

🧪 Testing

Run the test suite:

yarn test

The test suite includes:

• Unit tests for all major components
• Integration tests for protocol interactions
• Transaction generation tests
• Error handling tests

📦 Building

Build the TypeScript source to JavaScript:

yarn build

This creates the dist/ directory with compiled JavaScript files.

🔗 Dependencies

Core Dependencies

• @solana/web3.js - Solana blockchain interaction
• @coral-xyz/anchor - Solana program interaction
• @meteora-ag/dlmm - Meteora protocol SDK
• @orca-so/whirlpools-sdk - Orca protocol SDK
• @raydium-io/raydium-sdk-v2 - Raydium protocol SDK
• @hawksightco/swagger-client - Auto-generated API client

Development Dependencies

• typescript - TypeScript compilation
• jest - Testing framework
• @types/* - TypeScript type definitions

🏛️ Protocol Support

| Protocol | Features | Status | |----------|----------|--------| | Meteora | DLMM positions, automation, fast generation | ✅ Full Support | | Orca | Whirlpools, position management, rewards | ✅ Full Support | | Raydium | V2 positions, NFT handling, automation | ✅ Full Support | | Jupiter | Token swaps, routing, alternatives | ✅ Full Support |

🔄 Version Management

• Current Version: 1.3.9
• Dependencies: Use semantic versioning with appropriate ranges
  • ~ for patch-only updates (e.g., ~1.0.51)
  • ^ for minor updates (e.g., ^0.29.0)

🛠️ Development

Adding New Protocols

1. Create instruction generator in src/ixGenerator/
2. Add PDA generator in src/pdaGenerator/
3. Include IDL definitions in src/idl/
4. Add types in src/types.ts
5. Integrate with TxGenerator class
6. Add comprehensive tests

Error Handling

• Use AppError class for consistent error handling
• Include proper error messages and codes
• Handle network failures gracefully
• Provide meaningful error responses

📚 Additional Resources

• HawkFi Website
• API Documentation
• Solana Documentation
• Meteora Documentation
• Orca Documentation
• Raydium Documentation

🤝 Contributing

When contributing to this SDK:

1. Follow TypeScript best practices
2. Add comprehensive tests for new features
3. Update documentation for API changes
4. Ensure all tests pass before submitting
5. Use semantic commit messages

📄 License

MIT License - see LICENSE file for details.