@hawksightco/hawk-sdk

中文文档
1.3.288发布于 2026/10/21MITTypeScriptCommonJS近 30 天下载 6236

Hawksight v2 SDK

原始使用文档
文档目录27 节
  1. 🚀 Features
  2. 📦 Installation
  3. 🏗️ Architecture
  4. Core Classes
  5. Protocol Modules
  6. 🔧 Quick Start
  7. Basic Setup
  8. Get User Portfolio
  9. Create a Meteora Position
  10. Execute Batch Transactions
  11. 📚 API Reference
  12. HawkAPI Class
  13. Transaction Generation
  14. Utility Functions
  15. 🧪 Testing
  16. 📦 Building
  17. 🔗 Dependencies
  18. Core Dependencies
  19. Development Dependencies
  20. 🏛️ Protocol Support
  21. 🔄 Version Management
  22. 🛠️ Development
  23. Adding New Protocols
  24. Error Handling
  25. 📚 Additional Resources
  26. 🤝 Contributing
  27. 📄 License

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

ProtocolFeaturesStatus
MeteoraDLMM positions, automation, fast generation✅ Full Support
OrcaWhirlpools, position management, rewards✅ Full Support
RaydiumV2 positions, NFT handling, automation✅ Full Support
JupiterToken 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

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

版本与发布记录

@hawksightco/hawk-sdk 共发布 622 个版本,首次发布于 2024/05/03;过去 12 个月发布了 129 个版本。

版本发布日期距今
1.3.288latest2026/10/2127 天前
1.3.2872026/10/171 个月前
1.3.2862026/10/171 个月前
1.3.2852026/10/071 个月前
1.3.2842026/10/071 个月前
1.3.2832026/09/221 个月前

关于 @hawksightco/hawk-sdk 的常见问题

@hawksightco/hawk-sdk 是什么?

Hawksight v2 SDK

如何安装 @hawksightco/hawk-sdk?

在项目目录运行 npm install @hawksightco/hawk-sdk,或使用 pnpm add / yarn add / bun add。

@hawksightco/hawk-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hawksightco/hawk-sdk 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@hawksightco/hawk-sdk 可以商用吗?

@hawksightco/hawk-sdk 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hawksightco/hawk-sdk 的下载量有多少?

根据 npm 官方下载统计,@hawksightco/hawk-sdk 在 2026/10/18 – 2026/11/16 这 30 天内被下载 6,236 次,日均约 208 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hawksightco/hawk-sdk 还在维护吗?

最新版本 1.3.288 发布于 2026/10/21(27 天前);至今共发布 622 个版本,其中过去 12 个月发布了 129 个;首次发布于 2024/05/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。