Quickstart

This walks you through one complete swap: quote it, create it, hand your user a deposit party, and wait for the output to be returned to them.

Install the SDK

npm install @oneswap/sdk

Create an API key

Create an SDK key from your OneSwap account (self-serve) — swap.oneswap.cc for mainnet, devnet.oneswap.cc for devnet. The key looks like sk_live_ followed by 48 hex characters and is shown once at creation — store it somewhere safe. See API keys for the full flow.Keep the key on your server only. It is your integrator credential; never ship it to a browser or to an end-user.

Initialize the client

import { OneSwap } from '@oneswap/sdk'

const oneswap = new OneSwap({ apiKey: 'sk_live_...' })

The client sends your key on every request as the x-sdk-key header. It talks to mainnet by default; pass environment: 'devnet' to use the devnet backend — the SDK resolves the URL itself, so you never set one:

const oneswap = new OneSwap({
  apiKey: 'sk_live_...',
  environment: 'devnet', // 'mainnet' (default) | 'devnet'
})

Quote the swap

Before creating anything, ask what the swap would return. The SDK finds the pool that trades the pair and derives the direction for you:

const quote = await oneswap.quotes.get({
  from: 'CBTC',   // token the user pays with
  to: 'HTEST',    // token the user receives
  amount: 0.01,   // amount of `from` to swap
})

console.log(quote.amountOut)      // expected output, before it moves
console.log(quote.priceImpactPct) // price impact of this trade size
console.log(quote.poolId)         // the pool the pair resolved to

If no pool trades the pair directly, this throws NoDirectPoolError — route through an intermediate asset (usually CC) as two separate swaps.

Create the swap

const swap = await oneswap.swaps.createSwap({
  userRef: 'user-1042', // your stable id for this end-user
  inSymbol: 'CBTC',      // token the user deposits
  amountIn: 0.01,        // amount of inSymbol to swap
  outSymbol: 'HTEST',    // token to return to the user
  poolId: quote.poolId,  // settle against the pool that produced the quote
})

console.log(swap.id)           // 'esc_...'
console.log(swap.status)       // 'awaiting_deposit'
console.log(swap.depositParty) // the Canton party the user must fund
console.log(swap.deadline)     // ISO timestamp — deposit before this

Only one open swap is allowed per userRef at a time.

Show the user the deposit party

Tell your end-user to send amountIn of inSymbol (here, 0.01 CBTC) to swap.depositParty before swap.deadline (60 minutes from creation).The deposit must land within 1% of amountIn, or it is refunded. OneSwap never guesses intent from a wrong amount.

Wait for completion

const done = await oneswap.swaps.waitForSwap(swap.id)

if (done.status === 'returned') {
  // Success — output was paid back to the party that funded the swap
  console.log(`Returned ${done.amountOut} ${done.outSymbol} to ${done.senderParty}`)
} else {
  // refunded | expired | failed
  console.log(`Swap ended as ${done.status}`, done.error)
}

waitForSwap resolves once the swap reaches a terminal status (returned, refunded, expired, or failed), or when its local timeout is hit.

Complete example

import { OneSwap } from '@oneswap/sdk'

const oneswap = new OneSwap({ apiKey: 'sk_live_...' })

async function swapForUser() {
  // 1. Quote it first
  const quote = await oneswap.quotes.get({ from: 'CBTC', to: 'HTEST', amount: 0.01 })
  console.log(`Expecting ~${quote.amountOut} HTEST (impact ${quote.priceImpactPct}%)`)

  // 2. Create the swap
  const swap = await oneswap.swaps.createSwap({
    userRef: 'user-1042',
    inSymbol: 'CBTC',
    amountIn: 0.01,
    outSymbol: 'HTEST',
    poolId: quote.poolId,
  })

  // 3. Show your end-user where to send the deposit
  console.log(`Send ${swap.amountIn} ${swap.inSymbol} to ${swap.depositParty}`)
  console.log(`Deposit before ${swap.deadline}`)

  // 4. Wait for OneSwap to detect, swap, and return the output
  const done = await oneswap.swaps.waitForSwap(swap.id)

  if (done.status === 'returned') {
    console.log(`Done — returned ${done.amountOut} ${done.outSymbol} to ${done.senderParty}`)
  } else {
    console.log(`Swap ended as ${done.status}`, done.error)
  }
}

swapForUser()

Reading the market

The same client reads pools, tickers, and tokens — useful for building your own token pickers and price displays:

const tokens = await oneswap.tokens.list()   // what can be swapped
const pools = await oneswap.pools.list()     // every visible pool, with live reserves

// Live market data for the pool your quote resolved to
const ticker = await oneswap.pools.getTicker(quote.poolId)
console.log(`${ticker.pair}: $${ticker.price.usd} (${ticker.priceChange24h.pct ?? '—'}% 24h)`)
console.log(`24h volume: $${ticker.volume24h.usd} across ${ticker.volume24h.swaps} swaps`)

priceChange24h fields are null while the price history is warming up (the first 24h after a pool starts being tracked).

What’s next

Swaps guide

Lifecycle, tolerances, min-out, and reconciliation

API keys

Create, rotate, and revoke keys safely

Error handling

Typed errors, refunds, expiries, and robust polling

SDK methods

The full client surface

Getting Started

Guides

Reference

Complete example

Reading the market

What’s next

Swaps guide

API keys

Error handling

SDK methods

​Complete example

​Reading the market

​What’s next

Swaps guide

API keys

Error handling

SDK methods

Complete example

Reading the market

What’s next