Pump404 SDK

A TypeScript SDK for interacting with the Pump404 protocol on ALG chain. Create tokens, execute swaps, and get price quotes with ease.

Features

• 🚀 Token Creation: Launch new ERC404 tokens with customizable parameters
• 🔄 Token Swaps: Buy and sell tokens seamlessly
• 💰 Price Quotes: Get real-time swap quotes before executing trades
• 🔐 Security First: Returns unsigned transactions for client-side signing
• 📦 Lightweight: Minimal dependencies, optimized bundle size
• 🎯 Type-Safe: Full TypeScript support with comprehensive type definitions
• ⚡ Simple API: Clean, intuitive interface for all operations

Installation

# Using npm
npm install @unifi-io/pump404-sdk

# Using yarn
yarn add @unifi-io/pump404-sdk

# Using pnpm
pnpm add @unifi-io/pump404-sdk

Quick Start

Initialize the SDK

import { Pump404SDK, ALG_NATIVE_TOKEN_ADDRESS } from '@unifi-io/pump404-sdk'
import { JsonRpcProvider } from 'ethers'

// Create provider
const provider = new JsonRpcProvider('https://rpc.alg2.algen.network')

// Initialize SDK
const sdk = new Pump404SDK(provider)

Get a Price Quote

// Get quote for buying tokens with native currency
const quote = await sdk.quote({
  tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
  tokenOut: '0x...', // Token address
  amount: BigInt('1000000000000000') // 0.001 ALG (in wei)
})

console.log('Expected output:', quote.toString(), 'tokens')

Execute a Token Swap

import { Wallet } from 'ethers'

// Create wallet
const wallet = new Wallet(privateKey, provider)

// Build swap transaction with 1% slippage
const tx = await sdk.swap({
  tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
  tokenOut: '0x...', // Token address
  amountIn: BigInt('1000000000000000'), // 0.001 ALG
  minAmountOut: quote * 99n / 100n, // 1% slippage protection
  recipient: wallet.address
})

// Sign and send transaction
const txResponse = await wallet.sendTransaction(tx)
await txResponse.wait()

Create a New Token

const tx = await sdk.createAndBuy({
  name: 'My Token',
  symbol: 'MTK',
  imageUrl: 'https://example.com/image.png',
  description: 'An amazing token',
  account: wallet.address,
  buyAmount: BigInt('100000000000000000') // 0.1 ALG initial buy
})

const txResponse = await wallet.sendTransaction(tx)
await txResponse.wait()

API Reference

Constructor

new Pump404SDK(provider: JsonRpcProvider)

Creates a new instance of the Pump404 SDK.

Parameters:

• provider: An ethers.js JsonRpcProvider instance connected to ALG network

Example:

const provider = new JsonRpcProvider('https://rpc.alg2.algen.network')
const sdk = new Pump404SDK(provider)

quote(params: QuoteParams): Promise<bigint>

Get a quote for a token swap without executing it.

Parameters:

interface QuoteParams {
  tokenIn: string    // Input token address (use ALG_NATIVE_TOKEN_ADDRESS for native token)
  tokenOut: string   // Output token address (use ALG_NATIVE_TOKEN_ADDRESS for native token)
  amount: bigint     // Amount of input token (in wei/smallest unit)
}

Returns:

• bigint: Expected output amount (in wei/smallest unit)

Example:

const quote = await sdk.quote({
  tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
  tokenOut: '0xTokenAddress',
  amount: BigInt('1000000000000000000') // 1 ALG
})

console.log('You will receive approximately:', quote.toString(), 'tokens')

swap(params: SwapParams): Promise<TransactionRequest>

Build an unsigned swap transaction.

Parameters:

interface SwapParams {
  tokenIn: string       // Input token address
  tokenOut: string      // Output token address
  amountIn: bigint      // Input amount (in wei/smallest unit)
  minAmountOut: bigint  // Minimum acceptable output amount (slippage protection)
  recipient: string     // Address to receive the output tokens
}

Returns:

interface TransactionRequest {
  to: string       // Contract address
  data: string     // Encoded transaction data
  value: string    // Native token amount to send (if buying with native token)
}

Example:

// Get quote first
const quote = await sdk.quote({
  tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
  tokenOut: tokenAddress,
  amount: BigInt('1000000000000000000')
})

// Build transaction with 1% slippage protection
const tx = await sdk.swap({
  tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
  tokenOut: tokenAddress,
  amountIn: BigInt('1000000000000000000'),
  minAmountOut: quote * 99n / 100n,
  recipient: wallet.address
})

// Sign and send
const txResponse = await wallet.sendTransaction(tx)
const receipt = await txResponse.wait()
console.log('Swap successful:', receipt.hash)

createAndBuy(params: CreateAndBuyParams): Promise<TransactionRequest>

Create a new ERC404 token with optional initial purchase.

Parameters:

interface CreateAndBuyParams {
  name: string          // Token name
  symbol: string        // Token symbol
  imageUrl: string      // Image URL for both NFT and logo
  description?: string  // Token description (optional)
  account: string       // Your wallet address (royalty receiver)
  buyAmount?: bigint    // Amount of native token to spend on initial purchase (optional)
}

Returns:

interface TransactionRequest {
  to: string       // LaunchHub contract address
  data: string     // Encoded transaction data
  value: string    // Native token amount (buyAmount)
}

Default Parameters: The SDK automatically sets the following default values:

• ipfsHash: '' (empty)
• single: true (single NFT mode)
• royalty: 0 (0% royalty)
• bondingCurveType: 0 (Linear curve)
• price: 0
• ratio: 100000
• totalSupply: 1000000000
• lockPercent: 20 (20% locked)
• platform: 'fusion'

Example:

const tx = await sdk.createAndBuy({
  name: 'My Awesome Token',
  symbol: 'MAT',
  imageUrl: 'https://example.com/image.png',
  description: 'The best token ever',
  account: wallet.address,
  buyAmount: BigInt('100000000000000000') // 0.1 ALG
})

const txResponse = await wallet.sendTransaction(tx)
const receipt = await txResponse.wait()
console.log('Token created:', receipt.hash)

isNativeToken(address: string): boolean

Check if an address is the native token (ALG) address.

Parameters:

• address: Token address to check

Returns:

• boolean: true if the address is a native token address, false otherwise

Example:

const isNative = sdk.isNativeToken(ALG_NATIVE_TOKEN_ADDRESS) // true
const isNative2 = sdk.isNativeToken('0x1234...') // false

Constants

Native Token Address

import { ALG_NATIVE_TOKEN_ADDRESS } from '@unifi-io/pump404-sdk'

// Native token address for ALG chain
// Value: '0x0000000000000000000000000000000000000000'

⚠️ Important: Always use ALG_NATIVE_TOKEN_ADDRESS for native token operations. The TradingHub contract specifically requires 0x0000000000000000000000000000000000000000 (not 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee).

Contract Addresses

import { 
  TRADING_HUB_ADDRESS,    // TradingHub contract address
  LAUNCH_HUB_ADDRESS,     // LaunchHub contract address
  DEFAULT_RPC_URL         // Default RPC endpoint
} from '@unifi-io/pump404-sdk'

Usage Examples

Buy Tokens with Native Currency

import { Pump404SDK, ALG_NATIVE_TOKEN_ADDRESS } from '@unifi-io/pump404-sdk'
import { JsonRpcProvider, Wallet } from 'ethers'

const provider = new JsonRpcProvider('https://rpc.alg2.algen.network')
const sdk = new Pump404SDK(provider)
const wallet = new Wallet(privateKey, provider)

// 1. Get quote
const tokenAddress = '0x...'
const nativeAmount = BigInt('1000000000000000000') // 1 ALG

const quote = await sdk.quote({
  tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
  tokenOut: tokenAddress,
  amount: nativeAmount
})

console.log('Expected tokens:', quote.toString())

// 2. Build transaction with 1% slippage
const tx = await sdk.swap({
  tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
  tokenOut: tokenAddress,
  amountIn: nativeAmount,
  minAmountOut: quote * 99n / 100n,
  recipient: wallet.address
})

// 3. Execute transaction
const txResponse = await wallet.sendTransaction(tx)
const receipt = await txResponse.wait()

console.log('Tokens purchased! Transaction:', receipt.hash)

Sell Tokens for Native Currency

// Note: You need to approve token spending first!
// const tokenContract = new Contract(tokenAddress, ERC20_ABI, wallet)
// await tokenContract.approve(TRADING_HUB_ADDRESS, tokenAmount)

const tokenAmount = BigInt('1000000000000000000') // 1 token

// 1. Get quote
const quote = await sdk.quote({
  tokenIn: tokenAddress,
  tokenOut: ALG_NATIVE_TOKEN_ADDRESS,
  amount: tokenAmount
})

console.log('Expected native token:', quote.toString())

// 2. Build and execute transaction
const tx = await sdk.swap({
  tokenIn: tokenAddress,
  tokenOut: ALG_NATIVE_TOKEN_ADDRESS,
  amountIn: tokenAmount,
  minAmountOut: quote * 99n / 100n,
  recipient: wallet.address
})

const txResponse = await wallet.sendTransaction(tx)
await txResponse.wait()

Handle Slippage Protection

/**
 * Calculate minimum output amount with slippage tolerance
 * @param amount - Quote amount
 * @param slippagePercent - Slippage tolerance (e.g., 1.0 for 1%)
 * @returns Minimum acceptable output amount
 */
function applySlippage(amount: bigint, slippagePercent: number): bigint {
  const slippageBps = BigInt(Math.floor(slippagePercent * 100))
  return amount * (10000n - slippageBps) / 10000n
}

const quote = await sdk.quote({ /* ... */ })

// Apply 0.5% slippage
const minAmountOut = applySlippage(quote, 0.5)

// Apply 2% slippage
const minAmountOut2 = applySlippage(quote, 2.0)

TypeScript Support

The SDK is written in TypeScript and provides full type definitions.

import type { 
  SwapParams,
  QuoteParams,
  TransactionRequest,
  CreateAndBuyParams
} from '@unifi-io/pump404-sdk'

// All types are fully typed
const swapParams: SwapParams = {
  tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
  tokenOut: '0x...',
  amountIn: 1000000000000000n,
  minAmountOut: 990000000000000n,
  recipient: '0x...'
}

Error Handling

try {
  const quote = await sdk.quote({
    tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
    tokenOut: tokenAddress,
    amount: BigInt('1000000000000000000')
  })
  
  const tx = await sdk.swap({
    tokenIn: ALG_NATIVE_TOKEN_ADDRESS,
    tokenOut: tokenAddress,
    amountIn: BigInt('1000000000000000000'),
    minAmountOut: quote * 99n / 100n,
    recipient: wallet.address
  })
  
  const txResponse = await wallet.sendTransaction(tx)
  await txResponse.wait()
  
} catch (error: any) {
  if (error.message.includes('insufficient funds')) {
    console.error('Insufficient balance')
  } else if (error.message.includes('insufficient allowance')) {
    console.error('Token approval needed')
  } else if (error.message.includes('Failed to calculate')) {
    console.error('Token may not exist or has insufficient liquidity')
  } else {
    console.error('Transaction failed:', error.message)
  }
}

Network Information

ALG Chain (Mainnet):

• Chain ID: 8921
• RPC URL: https://rpc.alg2.algen.network
• Native Token Address: 0x0000000000000000000000000000000000000000
• TradingHub Contract: 0xdf03A2Ea006ED7D72238CB6189a26944027cfF28
• LaunchHub Contract: 0x63Ed2acb2dc20c8F9f6E6Cb3D8D67b522Db66CAC

Important Notes

Native Token Address

⚠️ Critical: The ALG chain's TradingHub contract requires the native token address to be 0x0000000000000000000000000000000000000000.

DO NOT use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee - this will cause transactions to fail with the error: "TradingHub: token in or token out must be a token".

Always use the exported constant:

import { ALG_NATIVE_TOKEN_ADDRESS } from '@unifi-io/pump404-sdk'
// ALG_NATIVE_TOKEN_ADDRESS = '0x0000000000000000000000000000000000000000'

Token Approvals

When selling tokens (swapping tokens for native currency), you must approve the TradingHub contract to spend your tokens first:

import { Contract } from 'ethers'
import { TRADING_HUB_ADDRESS } from '@unifi-io/pump404-sdk'

// ERC20 approve function ABI
const ERC20_ABI = [
  'function approve(address spender, uint256 amount) returns (bool)'
]

const tokenContract = new Contract(tokenAddress, ERC20_ABI, wallet)
const approvalTx = await tokenContract.approve(TRADING_HUB_ADDRESS, amountToSell)
await approvalTx.wait()

// Now you can sell the tokens
const swapTx = await sdk.swap({ /* ... */ })
await wallet.sendTransaction(swapTx)

Development

Build

yarn build

Run Tests

yarn test

Watch Mode

yarn test:watch

Requirements

• Node.js >= 18
• ethers.js ^6.15.0

Contributing

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

License

MIT License - see the LICENSE file for details.

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Disclaimer

This SDK is provided as-is. Always verify transaction details before signing. Use at your own risk. Never share your private keys.