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);

Meteora selected-token compounding

Use the automation generator to compound one pool fee token and retain the other:

await hawkAPI.txGeneratorAutomation.meteoraCompoundFromLargePositionIxs(
  connection,
  payer,
  {
    userWallet,
    position,
    compoundTokenX: true,
    compoundTokenY: false,
    distribution: 'SPOT-IMBALANCED',
  },
);

Both controls default to true, preserving existing compound behavior and return formats. Setting both to false generates claim-only transactions. Token X/Y refer to the pool's mint ordering. Unselected fees remain in the user PDA's ATA; this method does not swap them or transfer them to the wallet. Reward destinations continue to follow pdaTokenType.

Selected-token requests use explicit net fee budgets on every deposit chunk, including the last, and never sweep pre-existing account balances. If the selected token cannot be deposited at the current active bin, its fees are claimed and retained. An active-bin move before execution can still invalidate a deposit; callers must reconcile landed claim transactions before rebuilding a failed run.

Use meteoraCompoundFromLargePositionIxs at all position widths for these controls. The legacy meteoraCompoundIxs method rejects selected-token requests. Execution requires the existing meteora_dlmm_add_liquidity_2_automation instruction; deployed compatibility and transaction simulation must be checked before enabling hybrid automation in a consuming service.

For AA:AC hybrid with STA accumulation, explicitly opt in:

await hawkAPI.txGeneratorAutomation.meteoraCompoundFromLargePositionIxs(
  connection,
  payer,
  {
    userWallet,
    position,
    feeMode: 'hybrid',
    compoundTokenX: true,
    compoundTokenY: false,
    distribution: 'CURVE-IMBALANCED',
  },
);

In this mode selected fees compound using distribution, while unselected fees are claimed directly into the user PDA STA, net of harvest fees. Missing STAs are initialized before claiming. Both false accumulates both tokens in STA; both true compounds both using bounded net fee amounts. No fee swaps or whole-balance transfers are generated. Existing ATA/STA funds are not deposited. When a deposit is needed, setup also ensures both pool-token ATAs, including the zero-deposit side. Claim-only STA accumulation does not create those extra ATAs. Reward handling remains governed by pdaTokenType. Omit feeMode to preserve the earlier selected-token ATA retention behavior. This option applies to the compound generator, not the rebalance generators; consumers must explicitly wire their hybrid rebalance handling rather than assume it is enabled by this field.

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.