@oneswap/sdk

Official TypeScript SDK for the OneSwap API. Typed methods for pools, tokens, quotes, direct-party registration, swaps, liquidity, positions, history, and fee earnings — with built-in awaitable swap lifecycle. Works in Node.js and browsers.

Install

npm install @oneswap/sdk

Quick Start

import { OneSwap } from '@oneswap/sdk'

const client = new OneSwap({ apiKey: 'os_live_...' })

// Get a quote
const quote = await client.quotes.get({
  from: 'Amulet',
  to: 'USDCx',
  amount: '100',
})
console.log(`Output: ${quote.outputAmount} ${quote.outputToken}`)
console.log(`Traffic: ${quote.trafficFeeInInput ?? '0'} ${quote.inputToken}`)

// Register the user party with your API key
const wallet = await client.wallets.create({ walletAddress: 'alice::12205a8c...' })

// Create a swap and wait for completion
const intent = await client.swaps.create({
  fromToken: 'Amulet',
  toToken: 'USDCx',
  amount: '100',
  walletAddress: 'alice::12205a8c...',
})

console.log(`Deposit to: ${intent.depositAddress}`)

// Listen for status changes
intent.on('processing', () => console.log('Deposit detected'))
intent.on('completed', (status) => console.log(`Swap done: ${status.actualOutput}`))

// Await final result
const result = await intent.wait()
console.log(`Received: ${result.actualOutput} ${result.outputToken}`)

walletAddress is the user's actual Canton party ID. Deposits go directly to the pool party, and swap output returns directly to the same party unless you provide outputAddress.

API Reference

new OneSwap(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key | | baseUrl | string | https://api.oneswap.cc | API base URL | | timeout | number | 30000 | Request timeout (ms) |

Pools

| Method | Returns | Description | |--------|---------|-------------| | client.pools.list() | PoolListResponse | List all pools | | client.pools.get(poolId) | PoolDetail | Get pool details | | client.pools.getStats(poolId) | PoolStats | Get pool APR/volume/TVL |

Tokens

| Method | Returns | Description | |--------|---------|-------------| | client.tokens.list() | TokenListResponse | List available tokens |

Quotes

| Method | Returns | Description | |--------|---------|-------------| | client.quotes.get({ from, to, amount }) | Quote | Get swap quote. outputAmount already reflects any traffic-fee deduction. |

Wallets

| Method | Returns | Description | |--------|---------|-------------| | client.wallets.create({ walletAddress }) | Wallet | Register a direct Canton party for this developer | | client.wallets.list() | WalletListResponse | List registered parties | | client.wallets.get(walletAddress) | Wallet | Get registered party details | | client.wallets.getBalances(walletAddress) | WalletBalancesResponse | Get live on-chain balances for a registered party |

Swaps

| Method | Returns | Description | |--------|---------|-------------| | client.swaps.create(params) | SwapIntent | Create swap intent | | client.swaps.getStatus(intentId) | SwapStatusResponse | Get swap status | | client.swaps.list(params?) | SwapListResponse | List swaps |

SwapIntent (with event emitter):

• .wait(opts?) — Polls until terminal state. Resolves with SwapStatusResponse.
• .on(event, handler) / .once(event, handler) — Listen for status changes.
• Events: pending, processing, sending_output, completed, slippage_failed, insufficient_liquidity, insufficient_amount, output_failed, expired, cancelled

Liquidity

| Method | Returns | Description | |--------|---------|-------------| | client.liquidity.create(params) | LpIntent | Create LP intent | | client.liquidity.getStatus(intentId) | LpStatusResponse | Get LP status | | client.liquidity.list(params?) | LpListResponse | List LP intents |

LpIntent (with event emitter):

• .wait(opts?) — Polls until terminal state. Resolves with LpStatusResponse.
• .on(event, handler) / .once(event, handler) — Listen for status changes.
• Events: pending, partial, processing, completed, refunded, failed, expired, cancelled

Positions

| Method | Returns | Description | |--------|---------|-------------| | client.positions.list(walletAddress) | PositionsResponse | List LP positions for a registered party | | client.positions.getEarnings(walletAddress, poolId) | LpEarnings | Get projected LP earnings and current withdrawable amounts |

History

| Method | Returns | Description | |--------|---------|-------------| | client.history.list(params?) | HistoryResponse | Get swap and LP history |

Fees

| Method | Returns | Description | |--------|---------|-------------| | client.fees.getEarnings() | FeeEarningsResponse | Get accumulated fee earnings | | client.fees.getEarningsHistory(params?) | FeeEarningsHistoryResponse | Get fee event history | | client.fees.getCollections(params?) | FeeCollectionsResponse | Get fee collection history |

Track

| Method | Returns | Description | |--------|---------|-------------| | client.track(partyId) | TrackResponse | Get all swaps/LP by party |

Error Handling

All errors extend OneSwapError so you can catch them uniformly:

import {
  OneSwap,
  AuthError,
  ValidationError,
  SlippageError,
  InsufficientLiquidityError,
  InsufficientAmountError,
  OutputFailedError,
  LpRefundedError,
  LpFailedError,
  ExpiredError,
  TimeoutError,
  NetworkError,
} from '@oneswap/sdk'

try {
  const intent = await client.swaps.create({ ... })
  const result = await intent.wait()
} catch (err) {
  if (err instanceof SlippageError) {
    console.log('Slippage exceeded, swap refunded')
  } else if (err instanceof InsufficientLiquidityError) {
    console.log('Not enough liquidity in pool')
  } else if (err instanceof InsufficientAmountError) {
    console.log('Amount too low to cover traffic cost')
  } else if (err instanceof OutputFailedError) {
    console.log('Output transfer failed - contact support')
  } else if (err instanceof LpRefundedError) {
    console.log('LP intent refunded - refresh the pool ratio and retry')
  } else if (err instanceof LpFailedError) {
    console.log('LP intent failed - investigate before retrying')
  } else if (err instanceof ExpiredError) {
    console.log('Intent expired before deposit')
  } else if (err instanceof TimeoutError) {
    console.log('Request timed out')
  } else if (err instanceof NetworkError) {
    console.log('Network connectivity issue')
  } else if (err instanceof AuthError) {
    console.log('Invalid API key')
  } else if (err instanceof ValidationError) {
    console.log('Invalid params:', err.message)
  }
}

Wait Options

const result = await intent.wait({
  pollInterval: 5000,  // Poll every 5s (default: 3s)
  timeout: 600000,     // Timeout after 10min (default: 35min)
})

License

MIT