OpenOcean Node SDK

A TypeScript SDK for OpenOcean Aggregator API - the ultimate DEX aggregator supporting 40+ blockchain networks.

Features

• 🌐 Multi-Chain Support: 40+ EVM and Non-EVM chains including Ethereum, BSC, Polygon, Arbitrum, and more
• 💱 Best Rates: Find optimal swap routes across 100+ DEXs
• 🔒 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🚀 Easy to Use: Simple and intuitive API
• 📦 Lightweight: Minimal dependencies
• ⚡ Fast: Optimized for performance

Installation

npm install @unifi-io/openocean-sdk
# or
yarn add @unifi-io/openocean-sdk
# or
pnpm add @unifi-io/openocean-sdk

Quick Start

import { OpenOceanSDK, Chain } from '@unifi-io/openocean-sdk'

// Initialize the SDK
const sdk = new OpenOceanSDK()

// Get a quote for swapping tokens
const quote = await sdk.getQuote({
  chain: Chain.BSC,
  inTokenAddress: '0x55d398326f99059ff775485246999027b3197955', // USDT
  outTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d', // USDC
  amountDecimals: '1000000000000000000', // 1 token with 18 decimals
  gasPriceDecimals: '5000000000', // 5 Gwei
  slippage: '1', // 1% slippage
})

console.log('Output amount:', quote.data.outAmount)
console.log('Price impact:', quote.data.price_impact)

API Reference

SDK Initialization

import { OpenOceanSDK } from '@unifi-io/openocean-sdk'

// Use default API endpoint
const sdk = new OpenOceanSDK()

// Or specify a custom API endpoint
const sdk = new OpenOceanSDK('https://custom-api.example.com/v4')

Methods

getTokenList(chain)

Get the list of supported tokens for a specific chain.

const tokenList = await sdk.getTokenList(Chain.BSC)
// or use chain ID
const tokenList = await sdk.getTokenList(56)

Returns: GetTokenListResponse

getDexList(chain)

Get the list of available DEXs for a specific chain.

const dexList = await sdk.getDexList(Chain.BSC)

Returns: GetDexListResponse

getGasPrice(chain)

Get current gas prices for a specific chain.

const gasPrice = await sdk.getGasPrice(Chain.BSC)
console.log('Standard:', gasPrice.data.standard)
console.log('Fast:', gasPrice.data.fast)
console.log('Instant:', gasPrice.data.instant)

Returns: GetGasPriceResponse

getQuote(params)

Get a quote for token swap without transaction data.

const quote = await sdk.getQuote({
  chain: Chain.BSC,
  inTokenAddress: '0x55d398326f99059ff775485246999027b3197955',
  outTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
  amountDecimals: '1000000000000000000',
  gasPriceDecimals: '5000000000',
  slippage: '1',
  // Optional parameters
  disabledDexIds: '2,6', // Disable specific DEXs
  enabledDexIds: '1,3,5', // Or enable only specific DEXs
})

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | chain | ChainName \| number | ✅ | Chain name or chain ID | | inTokenAddress | string | ✅ | Input token address | | outTokenAddress | string | ✅ | Output token address | | amountDecimals | string | ✅ | Token amount with decimals (e.g., 1000000 for 1 USDT with 6 decimals) | | gasPriceDecimals | string | ✅ | Gas price with decimals | | slippage | string | ❌ | Slippage tolerance (0.05 to 50), default: 1 | | disabledDexIds | string | ❌ | Comma-separated DEX IDs to disable | | enabledDexIds | string | ❌ | Comma-separated DEX IDs to enable (higher priority) |

Returns: GetQuoteResponse

getSwapQuote(params)

Get a quote with executable transaction data.

const swapQuote = await sdk.getSwapQuote({
  chain: Chain.BSC,
  inTokenAddress: '0x55d398326f99059ff775485246999027b3197955',
  outTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
  amountDecimals: '1000000000000000000',
  gasPriceDecimals: '5000000000',
  slippage: '1',
  account: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', // Your wallet address
  referrer: '0x...', // Optional referrer address
})

// Use the transaction data
const tx = await wallet.sendTransaction({
  to: swapQuote.data.to,
  data: swapQuote.data.data,
  value: swapQuote.data.value,
  gasPrice: swapQuote.data.gasPrice,
})

Parameters: Same as getQuote() plus:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account | string | ✅ | User wallet address | | referrer | string | ❌ | Referrer address | | referrerFee | string | ❌ | Referrer fee in basis points |

Returns: GetSwapQuoteResponse

Static Methods

OpenOceanSDK.getSupportedChains()

Get all supported chains.

const chains = OpenOceanSDK.getSupportedChains()

OpenOceanSDK.getEVMChains()

Get only EVM chains.

const evmChains = OpenOceanSDK.getEVMChains()

OpenOceanSDK.getSwapAPIChains()

Get chains that support Swap API.

const swapChains = OpenOceanSDK.getSwapAPIChains()

OpenOceanSDK.getGaslessAPIChains()

Get chains that support Gasless API.

const gaslessChains = OpenOceanSDK.getGaslessAPIChains()

OpenOceanSDK.getChainId(chainName)

Get chain ID by chain name.

const chainId = OpenOceanSDK.getChainId('bsc') // Returns: 56

OpenOceanSDK.getChainName(chainId)

Get chain name by chain ID.

const chainName = OpenOceanSDK.getChainName(56) // Returns: 'bsc'

OpenOceanSDK.getChainInfo(chainName)

Get chain information by name.

const info = OpenOceanSDK.getChainInfo('bsc')

OpenOceanSDK.getNativeTokenAddress(chain)

Get native token address for a chain.

const nativeToken = OpenOceanSDK.getNativeTokenAddress('bsc')

Chain Constants

Use the Chain constant object instead of hardcoding chain names:

import { Chain } from '@unifi-io/openocean-sdk'

// Available chains
Chain.ETH          // Ethereum
Chain.BSC          // BNB Chain
Chain.POLYGON      // Polygon
Chain.ARBITRUM     // Arbitrum
Chain.OPTIMISM     // Optimism
Chain.BASE         // Base
Chain.AVAX         // Avalanche
Chain.LINEA        // Linea
// ... and 30+ more chains

Supported Chains

EVM Chains with Swap API

• Ethereum (eth, Chain ID: 1)
• BNB Chain (bsc, Chain ID: 56)
• Base (base, Chain ID: 8453)
• Polygon (polygon, Chain ID: 137)
• Arbitrum (arbitrum, Chain ID: 42161)
• Linea (linea, Chain ID: 59144)
• Optimism (optimism, Chain ID: 10)
• Avalanche (avax, Chain ID: 43114)
• zkSync Era (zksync, Chain ID: 324)
• Scroll (scroll, Chain ID: 534352)
• Blast (blast, Chain ID: 81457)
• Mantle (mantle, Chain ID: 5000)
• And 25+ more...

Chains with Gasless API

Gasless swaps are available on: Ethereum, BSC, Base, Polygon, Arbitrum, and Linea.

Complete Example

import { OpenOceanSDK, Chain } from '@unifi-io/openocean-sdk'

async function swapTokens() {
  const sdk = new OpenOceanSDK()
  
  // Step 1: Get gas price
  const gasPrice = await sdk.getGasPrice(Chain.BSC)
  console.log('Current gas price:', gasPrice.data.fast)
  
  // Step 2: Get quote
  const quote = await sdk.getQuote({
    chain: Chain.BSC,
    inTokenAddress: '0x55d398326f99059ff775485246999027b3197955', // USDT
    outTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d', // USDC
    amountDecimals: '5000000000000000000', // 5 USDT
    gasPriceDecimals: gasPrice.data.fast,
    slippage: '1',
  })
  
  console.log('Input:', quote.data.inAmount, quote.data.inToken.symbol)
  console.log('Output:', quote.data.outAmount, quote.data.outToken.symbol)
  console.log('Price Impact:', quote.data.price_impact)
  console.log('Estimated Gas:', quote.data.estimatedGas)
  
  // Step 3: Get executable swap transaction
  const swapQuote = await sdk.getSwapQuote({
    chain: Chain.BSC,
    inTokenAddress: '0x55d398326f99059ff775485246999027b3197955',
    outTokenAddress: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
    amountDecimals: '5000000000000000000',
    gasPriceDecimals: gasPrice.data.fast,
    slippage: '1',
    account: '0xYourWalletAddress',
  })
  
  // Step 4: Send transaction (using ethers.js or web3.js)
  // const tx = await wallet.sendTransaction({
  //   to: swapQuote.data.to,
  //   data: swapQuote.data.data,
  //   value: swapQuote.data.value,
  //   gasPrice: swapQuote.data.gasPrice,
  // })
  
  console.log('Transaction data ready:', swapQuote.data.to)
}

swapTokens()

Error Handling

try {
  const quote = await sdk.getQuote({
    chain: Chain.BSC,
    inTokenAddress: '0x...',
    outTokenAddress: '0x...',
    amountDecimals: '1000000000000000000',
    gasPriceDecimals: '5000000000',
  })
} catch (error) {
  if (error instanceof Error) {
    console.error('Failed to get quote:', error.message)
  }
}

Development

# Install dependencies
yarn install

# Build the SDK
yarn build

# Run tests
yarn test

# Watch mode for tests
yarn test:watch

# Test with UI
yarn test:ui

TypeScript Support

This SDK is written in TypeScript and includes complete type definitions. All API responses and parameters are fully typed.

import type { 
  GetQuoteResponse, 
  GetSwapQuoteResponse,
  ChainInfo 
} from '@unifi-io/openocean-sdk'

API Documentation

For more details about the OpenOcean API, visit the official documentation.

License

MIT © Unifi.io

Links

• OpenOcean Website
• OpenOcean API Documentation
• GitHub Repository
• NPM Package

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.