JSPM

  • Created
  • Published
  • Downloads 1231
  • Score
    100M100P100Q99605F
  • License GNU

A unified SDK for interacting with intents-based protocols across multiple blockchains including Solana, Ethereum, and Sui

Package Exports

  • genius-intents
  • genius-intents/across
  • genius-intents/aftermath
  • genius-intents/cetus
  • genius-intents/debridge
  • genius-intents/direct-pool-info
  • genius-intents/direct-pool-meteora
  • genius-intents/direct-pool-pump-fun
  • genius-intents/direct-pool-raydium
  • genius-intents/direct-pool-whirlpools
  • genius-intents/dist/lib/dex/pair-discovery
  • genius-intents/dist/protocols/algebra
  • genius-intents/dist/protocols/v2-dex
  • genius-intents/dist/protocols/v3-dex
  • genius-intents/dist/protocols/ve33
  • genius-intents/four-meme
  • genius-intents/genius-bridge
  • genius-intents/jupiter
  • genius-intents/kyberswap
  • genius-intents/lfj
  • genius-intents/odos
  • genius-intents/okx
  • genius-intents/openocean
  • genius-intents/raydium
  • genius-intents/v2-dex
  • genius-intents/v3-dex
  • genius-intents/zeroX

Readme

Genius Intents SDK

A unified TypeScript SDK for interacting with multiple DeFi protocols and intent-based trading across various blockchains.

๐Ÿš€ Features

  • Multi-Protocol Support: Seamlessly interact with Jupiter, Raydium, Odos, OKX, Kyberswap, OpenOcean, and Aftermath
  • Cross-Chain Compatible: Support for Solana, Ethereum, and Sui networks
  • Intent-Based Trading: Execute complex trading strategies with simple intent definitions
  • TypeScript First: Full type safety and excellent developer experience
  • Unified API: Single interface for multiple DeFi protocols
  • Price Discovery: Get quotes and prices across multiple protocols simultaneously

๐Ÿ“ฆ Installation

npm install genius-intents
yarn add genius-intents

๐Ÿ Quick Start

import { IntentsProtocols, ChainIdEnum } from 'genius-intents';

// Initialize the SDK with configuration
const intentsSDK = new IntentsProtocols({
  method: 'best', // 'best' or 'race'
  debug: true,
  logger: console,
  solanaRpcUrl: 'https://api.mainnet-beta.solana.com',
  suiRpcUrl: 'https://sui-mainnet.blockvision.org/v1/YOUR_API_KEY',
  okxApiKey: 'your-okx-api-key',
  okxSecretKey: 'your-okx-secret-key',
  okxPassphrase: 'your-okx-passphrase',
  okxProjectId: 'your-okx-project-id',
  zeroXApiKey: 'your-0x-api-key',
  kyberswapClientId: 'your-kyberswap-client-id',
  timeout: 30000,
  maxConcurrency: 10
});

// Get price quotes across multiple protocols
const priceParams = {
  networkIn: ChainIdEnum.BASE,
  networkOut: ChainIdEnum.BASE,
  tokenIn: '0x940181a94A35A4569E4529A3CDfB74e38FD98631',
  tokenOut: '0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b',
  amountIn: '1000000000000000000', // 1 token (18 decimals)
  slippage: 1, // 1%
  from: '0x5B1a738cfF4c6064C9C211C611f171a1567D2b9b'
};

const prices = await intentsSDK.fetchPrice(priceParams);
console.log('Best price:', prices.result);

// Execute a trade quote
const quoteParams = {
  networkIn: ChainIdEnum.BASE,
  networkOut: ChainIdEnum.BASE,
  tokenIn: '0x940181a94A35A4569E4529A3CDfB74e38FD98631',
  tokenOut: '0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b',
  amountIn: '1000000000000000000',
  slippage: 1,
  from: '0x5B1a738cfF4c6064C9C211C611f171a1567D2b9b',
  receiver: '0x5B1a738cfF4c6064C9C211C611f171a1567D2b9b'
};

const quote = await intentsSDK.fetchQuote(quoteParams);
console.log('Quote:', quote.result);

๐Ÿ”ง Advanced Usage

Using Individual Protocol Services

import { Jupiter, Raydium, Okx } from 'genius-intents';

// Access service and all protocol-specific types
const jupiter = new Jupiter.JupiterService(jupiterConfig);
const raydium = new Raydium.RaydiumV2Service(jupiterConfig);

// Access protocol-specific types for advanced usage
type JupiterConfig = Jupiter.JupiterConfig;
type JupiterPriceResponse = Jupiter.JupiterPriceResponse;
type RaydiumQuoteResponse = Raydium.RaydiumV2QuoteResponse;

// Use protocol-specific types for type-safe development
const jupiterParams: Jupiter.JupiterPriceUrlParams = {
  inputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  outputMint: 'So11111111111111111111111111111111111111112',
  amount: '1000000',
  slippageBps: 50
};

Option 2: Individual Protocol Import (Tree-Shaking Friendly)

// Import only what you need for better tree shaking and smaller bundle size
import { JupiterService, type JupiterConfig, type JupiterPriceResponse } from 'genius-intents';
import { OkxService, type OKXConfig } from 'genius-intents';
import { RaydiumV2Service, type RaydiumV2QuoteResponse } from 'genius-intents';

const jupiter = new JupiterService({ solanaRpcUrl: 'https://api.mainnet-beta.solana.com' });
const okx = new OkxService({ 
  apiKey: 'your-okx-api-key',
  secretKey: 'your-okx-secret-key',
  passphrase: 'your-okx-passphrase',
  projectId: 'your-okx-project-id'
});
const raydium = new RaydiumV2Service({ solanaRpcUrl: 'https://api.mainnet-beta.solana.com' });

// This approach only includes the specific protocols you import in your bundle

#### Option 3: Individual Protocol Package Import (Recommended for Tree-Shaking)
```typescript
// Import individual protocols as separate packages for optimal tree-shaking
import { AcrossService, type AcrossConfig } from 'genius-intents/across';
import { JupiterService, type JupiterConfig } from 'genius-intents/jupiter';
import { OkxService, type OKXConfig } from 'genius-intents/okx';
import { RaydiumV2Service, type RaydiumV2QuoteResponse } from 'genius-intents/raydium';

// This approach ensures only the specific protocol code is included in your bundle
const across = new AcrossService(acrossConfig);
const jupiter = new JupiterService({ solanaRpcUrl: 'https://api.mainnet-beta.solana.com' });

Option 4: Deep Path Import (Alternative)

// You can also import from specific protocol paths if needed
import { JupiterService, type JupiterConfig } from 'genius-intents/protocols/jupiter';
import { OkxService, type OKXConfig } from 'genius-intents/protocols/okx';

Bundle Size Optimization

The SDK supports tree-shaking, allowing you to include only the protocols you need:

// โœ… Best: Individual protocol imports (smallest bundle)
import { AcrossService } from 'genius-intents/across';
import { JupiterService } from 'genius-intents/jupiter';

// โœ… Good: Namespace imports (medium bundle)
import { Jupiter } from 'genius-intents';

// โœ… Good: Direct imports from main package (medium bundle)
import { JupiterService, OkxService, RaydiumV2Service } from 'genius-intents';

// โŒ Avoid: Imports everything (largest bundle)
import * as GeniusIntents from 'genius-intents';

Available Individual Protocol Services:

  • JupiterService - Jupiter aggregator on Solana
  • RaydiumV2Service - Raydium V2 AMM on Solana
  • OkxService - OKX DEX aggregator
  • OdosService - Odos aggregator
  • KyberswapService - Kyberswap aggregator
  • OpenOceanService - OpenOcean aggregator
  • AftermathService - Aftermath aggregator on Sui
  • ZeroXService - 0x aggregator
  • DeBridgeService - DeBridge cross-chain bridge
  • GeniusBridgeService - Genius Bridge cross-chain bridge
  • AcrossService - Across Protocol bridge

Individual Protocol Usage Examples

Across Protocol

import { AcrossService, type AcrossConfig } from 'genius-intents/across';

const acrossConfig: AcrossConfig = {
  // Across-specific configuration
};

const across = new AcrossService(acrossConfig);
const quote = await across.getQuote({
  // quote parameters
});

Jupiter Protocol

import { JupiterService, type JupiterConfig } from 'genius-intents/jupiter';

const jupiterConfig: JupiterConfig = {
  solanaRpcUrl: 'https://api.mainnet-beta.solana.com'
};

const jupiter = new JupiterService(jupiterConfig);
const price = await jupiter.getPrice({
  inputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  outputMint: 'So11111111111111111111111111111111111111112',
  amount: '1000000',
  slippageBps: 50
});

OKX Protocol

import { OkxService, type OKXConfig } from 'genius-intents/okx';

const okxConfig: OKXConfig = {
  apiKey: 'your-okx-api-key',
  secretKey: 'your-okx-secret-key',
  passphrase: 'your-okx-passphrase',
  projectId: 'your-okx-project-id'
};

const okx = new OkxService(okxConfig);
const quote = await okx.getQuote({
  // quote parameters
});

Protocol Filtering

import { IntentsProtocols, ProtocolEnum } from 'genius-intents';

// Only use specific protocols
const intentsSDK = new IntentsProtocols({
  method: 'best',
  includeProtocols: [ProtocolEnum.JUPITER, ProtocolEnum.RAYDIUM_V2],
  solanaRpcUrl: 'https://api.mainnet-beta.solana.com'
});

// Exclude specific protocols
const intentsSDKExclude = new IntentsProtocols({
  method: 'race',
  excludeProtocols: [ProtocolEnum.RAYDIUM],
  timeout: 15000
});

Cross-Chain Operations

import { IntentsProtocols, ChainIdEnum } from 'genius-intents';

// Configure for multiple chains
const multiChainSDK = new IntentsProtocols({
  method: 'best',
  solanaRpcUrl: 'https://api.mainnet-beta.solana.com',
  suiRpcUrl: 'https://sui-mainnet.blockvision.org/v1/YOUR_API_KEY',
  okxApiKey: 'your-okx-api-key',
  okxSecretKey: 'your-okx-secret-key',
  okxPassphrase: 'your-okx-passphrase',
  okxProjectId: 'your-okx-project-id',
  zeroXApiKey: 'your-0x-api-key'
});

// Ethereum Base chain operations
const baseParams = {
  networkIn: ChainIdEnum.BASE,
  networkOut: ChainIdEnum.BASE,
  tokenIn: '0x940181a94A35A4569E4529A3CDfB74e38FD98631',
  tokenOut: '0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b',
  amountIn: '1000000000000000000',
  slippage: 1,
  from: '0x5B1a738cfF4c6064C9C211C611f171a1567D2b9b'
};

// Sui network operations  
const suiParams = {
  networkIn: ChainIdEnum.SUI_MAINNET,
  networkOut: ChainIdEnum.SUI_MAINNET,
  tokenIn: '0x2::sui::SUI',
  tokenOut: '0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf:๐Ÿช™:COIN',
  amountIn: '1000000000', // 1 SUI (9 decimals)
  slippage: 1,
  from: '0x...' // Sui address
};

๐Ÿ“š API Reference

IntentsProtocols

The main class for interacting with multiple protocols.

Constructor

new IntentsProtocols(config?: IntentsProtocolsConfig)

Configuration Options:

  • method?: 'race' | 'best' - Execution method ('race' returns fastest, 'best' returns optimal)
  • timeout?: number - Timeout in milliseconds for individual protocol requests (default: 30000)
  • maxConcurrency?: number - Maximum concurrent protocol requests (default: 10)
  • includeProtocols?: ProtocolEnum[] - Specific protocols to include
  • excludeProtocols?: ProtocolEnum[] - Specific protocols to exclude
  • logger?: ILogger - Custom logger instance
  • debug?: boolean - Enable debug logging

Protocol-Specific Configuration:

  • solanaRpcUrl?: string - Solana RPC endpoint
  • suiRpcUrl?: string - Sui RPC endpoint
  • okxApiKey?: string - OKX API key
  • okxSecretKey?: string - OKX secret key
  • okxPassphrase?: string - OKX passphrase
  • okxProjectId?: string - OKX project ID
  • zeroXApiKey?: string - 0x API key
  • kyberswapClientId?: string - Kyberswap client ID

Methods

fetchPrice(params: IntentPriceParams): Promise<IntentsProtocolsResults<PriceResponse>>

Get price quotes from multiple protocols.

Parameters:

  • networkIn: number - Input network chain ID
  • networkOut: number - Output network chain ID
  • tokenIn: string - Input token address
  • tokenOut: string - Output token address
  • amountIn: string - Amount to trade (in token's smallest unit)
  • slippage: number - Slippage tolerance as percentage (e.g., 1 for 1%)
  • from: string - User's wallet address
fetchQuote(params: IntentQuoteParams): Promise<IntentsProtocolsResults<QuoteResponse>>

Get detailed quotes including transaction data.

Parameters:

  • All parameters from IntentPriceParams plus:
  • receiver: string - Recipient address for the trade
  • priceResponse?: PriceResponse - Optional pre-fetched price response

Utility Methods

  • getInitializedProtocols(): ProtocolEnum[] - Get list of successfully initialized protocols
  • getProtocol(protocol: ProtocolEnum): IIntentProtocol | undefined - Get specific protocol instance
  • updateConfig(config: Partial<IntentsProtocolsConfig>): void - Update configuration

Supported Protocols

Protocol Namespace Chains Description
Jupiter Jupiter Solana Leading Solana DEX aggregator
Raydium V2 Raydium Solana Automated market maker
Odos Odos Multi-chain Multi-chain DEX aggregator
OKX Okx Multi-chain Centralized exchange DEX
Kyberswap Kyberswap Multi-chain Dynamic market maker
OpenOcean OpenOcean Multi-chain DEX aggregator
0x ZeroX Multi-chain DEX aggregator protocol
Aftermath Aftermath Sui Native Sui DEX
DeBridge DeBridge Multi-chain Cross-chain bridge
Genius Bridge GeniusBridge Multi-chain Custom bridge solution

Protocol Namespace Exports

Each protocol namespace exports:

  • Service Class: [Protocol]Service (e.g., Jupiter.JupiterService)
  • Configuration Types: Protocol-specific config interfaces
  • Request/Response Types: All API-related types
  • Internal Types: Advanced types for protocol-specific development
// Example: All available exports from Jupiter namespace
import {
  JupiterService,           // Service class
  type JupiterConfig,       // Configuration
  type JupiterPriceResponse,// Response types
  type JupiterSwapRoutePlan,// Internal types
  // ... and more
} from 'genius-intents';

const { JupiterService } = Jupiter; // Alternative access

Response Structure

Both fetchPrice() and fetchQuote() return an IntentsProtocolsResults object:

type IntentsProtocolsResults<T> = {
  result?: T;                    // Best/fastest result based on method
  allResults: Array<{            // All protocol results
    protocol: ProtocolEnum;
    response?: T;
    error?: Error;
    duration: number;
  }>;
  method: 'race' | 'best';       // Execution method used
  totalDuration: number;         // Total execution time
};

Supported Chains

The SDK supports multiple blockchain networks. Chain IDs are numeric values:

enum ChainIdEnum {
  SOLANA = 1399811149,
  AVALANCHE = 43114,
  SONIC = 146,
  BSC = 56,
  BASE = 8453,
  SUI = 101,
  ARBITRUM = 42161,
  OPTIMISM = 10,
  BLAST = 81457,
  POLYGON = 137,
  ETHEREUM = 1,
  APTOS = 999,
}

๐Ÿงช Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit          # Unit tests
npm run test:integration   # Integration tests
npm run test:protocols     # Protocol-specific tests

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

๐Ÿ› ๏ธ Development

# Install dependencies
npm install

# Build the project
npm run build

# Run linting
npm run lint

# Format code
npm run format

๐Ÿ“ Examples

Check out the /tests directory for comprehensive examples of how to use each protocol service.

๐Ÿค Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

๐Ÿ“„ License

This project is licensed under the ISC License - see the LICENSE file for details.

โš ๏ธ Disclaimer

This SDK is provided as-is. Always verify transactions and test thoroughly before using in production. DeFi protocols carry inherent risks including but not limited to smart contract risks, impermanent loss, and market volatility.

๐Ÿ“ž Support

For support, questions, or feature requests:

  • Open an issue on GitHub
  • Contact the development team

Built with โค๏ธ by the Shuttle Labs team