Skip to main content

​
Authentication

Pass your API key when initializing the client: 
import { OneSwap } from '@oneswap/sdk'

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

​
Pools

​
client.pools.list()

Returns all pools with token reserves, fee, and LP token supply.

​
client.pools.get(poolId)

Returns pool details including swapAddress and lpAddress.

​
client.pools.getStats(poolId)

Returns apr, apy, volume24h, fees24h, tvl, swapCount24h.

​
Tokens

​
client.tokens.list()

Returns available tokens with name and admin fields.

​
Quotes

​
client.quotes.get({ from, to, amount })

Returns inputAmount, outputAmount, rate, priceImpact, fee, poolId, expiresIn. Quotes expire in 30 seconds.

​
Wallets

​
client.wallets.create({ userId })

Creates a custodial Canton wallet for the given user ID.

​
client.wallets.list()

Returns all wallets for the authenticated developer.

​
client.wallets.get(userId)

Returns wallet details by user ID.

​
client.wallets.getBalances(userId)

Returns token balances for the custodial wallet.

​
Swaps

​
client.swaps.create(params)

Creates a swap intent. Returns a SwapIntent object (extends EventEmitter).
ParamRequiredDescription
fromTokenYesInput token symbol
toTokenYesOutput token symbol
amountYesInput amount
slippageToleranceNo0.001–0.5, default 0.01 (1%)
userIdNoUse custodial wallet
senderPartyNoCustom sender party address
outputAddressNoReceive output at different address
Returns intent with depositAddress, expectedOutput, minOutput, expiresAt, and instructions. 
const intent = await client.swaps.create({
  fromToken: 'Amulet',
  toToken: 'USDCx',
  amount: '100',
  slippageTolerance: 0.01
})

intent.on('matched', () => console.log('Deposit detected'))
intent.on('completed', (s) => console.log(`Got ${s.actualOutput}`))

const result = await intent.wait()

​
client.swaps.getStatus(intentId)

Status values: pending → matched → completed | slippage_failed | expired

​
client.swaps.list(params?)

Optional params: status, limit, offset.

​
Liquidity

​
client.liquidity.create(params)

Creates an LP intent. Returns an LpIntent object (extends EventEmitter).
ParamRequiredDescription
poolIdYesTarget pool
amountAYesToken A amount
amountBYesToken B amount
userIdNoUse custodial wallet
senderPartyNoCustom sender party
Returns intent with depositAddress, lpAddress, expiresAt, and instructions. 
const intent = await client.liquidity.create({
  poolId: 'Amulet-USDCx',
  amountA: '100',
  amountB: '150'
})

intent.on('partial', () => console.log('One token received'))
const result = await intent.wait()

​
client.liquidity.getStatus(intentId)

Status values: pending → partial → completed | expired

​
client.liquidity.list(params?)

Optional params: status, limit, offset.

​
Positions and earnings

​
client.positions.list(userId)

Returns LP positions with sharePercent, valueTokenA, valueTokenB.

​
client.positions.getEarnings(userId, poolId)

Returns apr, apy, estimated daily/monthly/yearly earnings.

​
History and tracking

​
client.history.list(params?)

Returns all swaps and LP intents for the authenticated developer. Optional params: limit, offset.

​
client.track(partyId)

Returns all swaps and LP intents associated with a Canton party ID.

​
Types

​
Quote

interface Quote {
  inputToken: string
  outputToken: string
  inputAmount: string
  outputAmount: string
  rate: string
  priceImpact: string
  fee: number
  poolId: string
  expiresIn: number
}

​
SwapIntent

interface SwapIntentResponse {
  intentId: string
  poolId: string
  depositAddress: string
  inputToken: string
  outputToken: string
  expectedAmount: string
  expectedOutput: string | null
  minOutput: string | null
  slippageTolerance: number
  expiresAt: string
  instructions: Record<string, string>
}

​
SwapStatus

interface SwapStatusResponse {
  intentId: string
  status: 'pending' | 'matched' | 'completed' | 'slippage_failed' | 'expired'
  inputToken: string
  outputToken: string
  expectedAmount: string
  actualOutput: string | null
  matchedAt: string | null
  createdAt: string
  expiresAt: string
}

​
LpIntent

interface LpIntentResponse {
  intentId: string
  poolId: string
  depositAddress: string
  lpAddress: string
  tokenA: string
  tokenB: string
  expectedAmountA: string
  expectedAmountB: string
  expiresAt: string
  instructions: Record<string, string>
}

​
Wallet

interface Wallet {
  walletId: string
  userId: string
  address: string
  createdAt: string
}

​
Pool

interface Pool {
  id: string
  tokenA: { name: string; reserve: string }
  tokenB: { name: string; reserve: string }
  fee: number
  lpTokens: string
}

interface PoolDetail extends Pool {
  swapAddress: string
  lpAddress: string
}

interface PoolStats {
  apr: number
  apy: number
  volume24h: string
  fees24h: string
  tvl: string
  swapCount24h: number
}

​
Error classes

import {
  OneSwapError,
  AuthError,        // 401
  ValidationError,  // 400
  NotFoundError,    // 404
  RateLimitError,   // 429
  SlippageError,    // swap failed slippage check
  ExpiredError,     // intent expired
  ServerError       // 500
} from '@oneswap/sdk'