npm package: @hawksightco/hawk-sdk
Description: Hawksight v2 SDK
Author: Hawksight
Latest version: 1.3.235

# 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

```bash
npm install @hawksightco/hawk-sdk
```

or

```bash
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:

```typescript
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

```typescript
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

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

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

### Create a Meteora Position

```typescript
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

```typescript
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
```typescript
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
```typescript
// 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
```typescript
// 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
```typescript
// 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
```typescript
import { generateUserPda, generateAta, generateLimitToken } from '@hawksightco/hawk-sdk';

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

#### Transaction Utilities
```typescript
import { createTxMetadata, resultOrError } from '@hawksightco/hawk-sdk';

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

## 🧪 Testing

Run the test suite:

```bash
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:

```bash
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](https://hawkfi.ag/)
- [API Documentation](https://api2.hawksight.co)
- [Solana Documentation](https://docs.solana.com/)
- [Meteora Documentation](https://docs.meteora.ag/)
- [Orca Documentation](https://docs.orca.so/)
- [Raydium Documentation](https://raydium.io/docs/)

## 🤝 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.