Metal Presales SDK

A secure, type-safe SDK for interacting with Metal L2 presales and tokens.

Installation

npm install metal-presale

Quick Start

Client-Side Usage

For browser/client-side applications:

import { MetalPresalesClient } from 'metal-presale/client'

const metal = new MetalPresalesClient({
  publicApiKey: process.env.NEXT_PUBLIC_METAL_PUBLIC_KEY!,
  apiBasePath: '/api/metal' // Your API route base path
})

// Public operations (no server required)
const holder = await metal.getHolder('user123')
const portfolio = await metal.getHolderWithPortfolio('user123')
const presale = await metal.getPresale('presale-id')

// Server-proxied operations (requires API routes)
await metal.createUser('user123')
await metal.buyPresale('user123', 'presale-id', 100)
await metal.buyTokens('user123', '0x...', 50)

Server-Side Usage

For server-side applications and API routes:

import { MetalPresalesServer } from 'metal-presale/server'

const metal = new MetalPresalesServer({
  publicApiKey: process.env.NEXT_PUBLIC_METAL_PUBLIC_KEY!,
  secretApiKey: process.env.METAL_SECRET_KEY!
})

// All operations available
const holder = await metal.getOrCreateHolder('user123')
const presales = await metal.getActivePresales()
await metal.buyPresale('user123', { presaleId: 'abc', usdcAmount: 100 })

Next.js API Routes (Recommended)

The easiest way to set up all API routes in Next.js:

1. Create app/api/metal/[...action]/route.ts:

export { GET, POST } from 'metal-presale/next'

That's it! This automatically creates all the required endpoints:

• POST /api/metal/users/create
• GET /api/metal/presales/active
• POST /api/metal/presales/buy
• POST /api/metal/tokens/buy
• POST /api/metal/tokens/sell
• POST /api/metal/tokens/quote-buy
• POST /api/metal/tokens/quote-sell

Environment Variables

# Required for both client and server
NEXT_PUBLIC_METAL_PUBLIC_KEY=your-public-key

# Required for server-side only
METAL_SECRET_KEY=your-secret-key

Core Features

🎯 Portfolio Management

Get holder data with calculated portfolio values:

const { holder, portfolio } = await metal.getHolderWithPortfolio(userId)

console.log(portfolio.buyingPower)  // USDC balance
console.log(portfolio.holdings)     // Value of non-USDC tokens
console.log(portfolio.vaulted)      // Value of locked tokens
console.log(portfolio.totalValue)   // Total portfolio value

🚀 Presale Operations

// Get only active presales
const activePresales = await metal.getActivePresales()

// Get presale with utility functions
import { getPresaleProgress, getPresaleTimeRemaining, formatTimeRemaining } from 'metal-presale'

const presale = await metal.getPresale(presaleId)
const progress = getPresaleProgress(presale)  // Returns 0-100
const timeLeft = getPresaleTimeRemaining(presale)  // Returns milliseconds
const timeString = formatTimeRemaining(timeLeft)  // "2 days remaining"

💰 Token Operations

// Get quotes before transactions
const buyQuote = await metal.quoteBuyTokens(userId, {
  tokenAddress: '0x...',
  usdcAmount: 100
})

const sellQuote = await metal.quoteSellTokens(userId, {
  tokenAddress: '0x...',
  tokenAmount: 50
})

// Execute transactions
const buyResult = await metal.buyTokens(userId, {
  tokenAddress: '0x...',
  usdcAmount: 100
})

const sellResult = await metal.sellTokens(userId, {
  tokenAddress: '0x...',
  tokenAmount: 50
})

Utility Functions

import {
  calculatePortfolioSummary,
  isPresaleActive,
  getPresaleProgress,
  getPresaleTimeRemaining,
  formatTimeRemaining,
  filterTokensByType,
  calculateTotalValue,
  findToken,
  sortTokensByValue,
  getUnlockedTokens
} from 'metal-presale'

// Use these utilities for common operations
const presaleTokens = filterTokensByType(holder.tokens, 'presale')
const totalPresaleValue = calculateTotalValue(presaleTokens)
const usdcToken = findToken(holder.tokens, 'USDC')
const sortedTokens = sortTokensByValue(holder.tokens)

TypeScript Support

The SDK is fully typed. All types are exported:

import type { 
  HolderResponse, 
  PortfolioSummary, 
  PresaleResponse,
  TokenLikeItem,
  BuyPresaleParams,
  BuyTokensParams,
  SellTokensParams,
  QuoteBuyTokensParams,
  QuoteSellTokensParams
} from 'metal-presale/client'

Security Best Practices

1. Never expose your secret key: The secret key should only be used server-side
2. Use the client SDK in browsers: It only includes public operations and API calls
3. Set up API routes: Use the built-in Next.js handlers for secure server operations
4. Validate inputs: Always validate user inputs in your API routes

Advanced Usage

Custom API Configuration

const metal = new MetalPresalesClient({
  publicApiKey: 'your-key',
  apiBasePath: '/custom/api/path' // Default: '/api/metal'
})

Error Handling

try {
  await metal.buyPresale('user123', 'presale-id', 100)
} catch (error) {
  if (error.message.includes('Insufficient balance')) {
    // Handle insufficient funds
  }
  // Handle other errors
}

Migration Guide

From Direct API Calls

Before:

// Manual portfolio calculations
const buyingPower = holder.tokens?.find(t => t.symbol === 'USDC')?.balance || 0
const holdings = holder.tokens
  ?.filter(t => t.symbol !== 'USDC')
  ?.reduce((sum, token) => sum + token.value, 0) || 0

After:

// Automatic portfolio calculations
const { portfolio } = await metal.getHolderWithPortfolio(userId)
// portfolio.buyingPower, portfolio.holdings already calculated

From Manual Presale Filtering

Before:

// Manual presale filtering
const presales = await fetch('/api/presales/list')
const activePresales = presales.filter(p => {
  // Complex logic to determine if active
})

After:

// Built-in active presale filtering
const activePresales = await metal.getActivePresales()