Concord SDK

TypeScript SDK for interacting with the Concord decentralized exchange platform.

Documentation

For complete API documentation, visit: import('@wcm-inc/sdk/docs') or open node_modules/@wcm-inc/sdk/docs/index.html in your browser after installation.

Documentation Access

The documentation is included in the published package and can be accessed in several ways:

1. Browser Access: Open node_modules/@wcm-inc/sdk/docs/index.html directly in your browser
2. Programmatic Access: Use import('@wcm-inc/sdk/docs') in your code
3. Development: Run pnpm doc in the source repository to regenerate documentation

Note: The pnpm doc command only works in the source repository, not in the installed package. The pre-generated documentation is bundled with the published package for immediate access.

Core Components

The SDK provides access to the following main entities:

Exchange

The main entry point for interacting with the Concord Protocol. Use this class to:

• Manage user accounts and deposits/withdrawals
• Access portfolio information
• Configure vault tokens and fee schedules
• Interact with lending and perpetual positions
• Create and manage order books

Order Books

The SDK supports three types of order books:

SpotOrderBook

Spot trading order book for immediate settlement of trades. Provides methods for:

• Placing and canceling spot orders
• Querying order book depth and best offers
• Listening to trade and order events

PerpOrderBook

Perpetual futures order book for leveraged trading. Supports:

• Long and short positions
• Funding rate calculations
• Position management and liquidations

LendOrderBook

Lending/borrowing order book for interest-bearing positions. Enables:

• Creating lend and borrow orders
• Managing lending positions
• Interest rate calculations

Portfolio

Portfolio management class for tracking user positions across all order books and tokens.

ERC20

Helper class for interacting with ERC20 tokens, including approvals and transfers.

Swap

The SDK provides specialized modules for efficient token swapping:

SwapAggregator

Intelligent routing and price optimization for token swaps. The aggregator:

• Discovers optimal swap routes (direct or two-hop via base currency)
• Compares prices across different paths
• Applies slippage protection automatically
• Executes swaps with automatic token approvals

Example:

const aggregator = new SwapAggregator({ exchange, swapRouter })

// Get best route for exact input
const route = await aggregator.getBestRouteForExactInput({
  tokenIn: euroAddress,
  tokenOut: goldAddress,
  amountIn: 1000,
  deadline: Date.now() + 300000,
  slippage: 0.5, // 0.5% slippage tolerance
})

// Execute the swap
const receipt = await aggregator.executeSwap({ route })

SwapRouter

Low-level contract wrapper for executing direct token swaps between a token and the exchange's base currency (nominally USD).

Important: SwapRouter does NOT perform routing or multi-hop swaps. All functions swap directly between a single token and the base currency only. For intelligent routing and multi-hop swaps (token → base → token), use SwapAggregator instead.

Provides:

• Uniswap V3 compatible interface (exactInputSingle, exactOutputSingle)
• Native exchange functions (swapByAmountInViaMinOut, swapByAmountOutViaMaxIn)
• Price querying without execution (getPriceByAmountIn, getPriceByAmountOut)

Example:

const exchange = new Exchange({ contractAddress: exchangeAddress, signer })
const swapRouter = new SwapRouter({ contractAddress: swapRouterAddress, exchange })

// Execute swap with exact input (Uniswap V3 compatible)
await swapRouter.exactInputSingle({
  tokenIn: euroAddress,
  tokenOut: goldAddress,
  amountIn: 1000,
  amountOutMin: 0.4,
  deadline: Date.now() + 300000,
})

// Query price without executing
const quote = await swapRouter.getPriceByAmountIn({
  tokenIn: euroAddress,
  tokenOut: goldAddress,
  amountIn: 1000,
  amountOutMin: 0,
  deadline: Date.now() + 300000,
})

Utilities

The SDK includes utility functions for common operations:

• scale() / unscale() - Convert between human-readable and on-chain token amounts
• encodePrice() / decodePrice() - Encode/decode prices for order books
• pack() / unpack() - Pack/unpack data for batch operations
• waitForTransaction() - Wait for transaction confirmation

Number Handling

All numeric operations use BigNumber from bignumber.js. Never use JavaScript's native number type for calculations to avoid precision loss.

Event Listening

The SDK provides event-driven architecture through the Listener class, allowing you to subscribe to real-time updates from the exchange and order books.

Quick Start Examples

Basic Token Swap

import { Exchange, SwapRouter, SwapAggregator } from '@composite/sdk'

// Initialize components
const exchange = new Exchange({ contractAddress: exchangeAddress, signer: wallet })
const swapRouter = new SwapRouter({ contractAddress: swapRouterAddress, exchange })
const aggregator = new SwapAggregator({ exchange, swapRouter })

// Find and execute best swap route
const route = await aggregator.getBestRouteForExactInput({
  tokenIn: usdcAddress,
  tokenOut: goldAddress,
  amountIn: 1000, // 1000 USDC
  deadline: Date.now() + 300000, // 5 minutes
  slippage: 0.5, // 0.5%
})

console.log(`Route type: ${route.type}`) // DIRECT or TWO_HOP
console.log(`Expected output: ${route.quote.amountOut}`)
console.log(`Price impact: ${route.quote.priceImpact}%`)

const receipt = await aggregator.executeSwap({ route })
console.log(`Swap completed: ${receipt.hash}`)

Direct Swap Execution

import { Exchange, SwapRouter } from '@composite/sdk'

const exchange = new Exchange({ contractAddress: exchangeAddress, signer: wallet })
const swapRouter = new SwapRouter({ contractAddress: swapRouterAddress, exchange })

// Low-level swap execution (native exchange function)
await swapRouter.swapByAmountInViaMinOut({
  tokenIn: usdAddress,
  tokenOut: goldAddress,
  amountIn: 1000,
  amountOutMin: 0.45,
  deadline: Date.now() + 300000,
})