Skip to main content

OneSwap SDK

OneSwap lets you add token swaps to any app on the Canton Network.
import { OneSwap } from '@oneswap/sdk'

const apiKey = 'os_live_...'
const partyId = 'alice::12205a8c...'

const authClient = new OneSwap({ apiKey })
const challenge = await authClient.walletAuth.requestChallenge(partyId)
const signature = await wallet.signMessage(challenge.message)

const verified = await authClient.walletAuth.verifyChallenge({
  partyId,
  nonce: challenge.nonce,
  signature,
  publicKey: wallet.publicKey,
})

const client = new OneSwap({
  apiKey,
  walletToken: verified.token,
})

// get a price quote
const quote = await client.quotes.get({
  from: 'Amulet',
  to: 'USDCx',
  amount: '100',
  receiverParty: partyId,
})

// create a swap intent
const swap = await client.swaps.create({
  fromToken: 'Amulet',
  toToken: 'USDCx',
  amount: '100',
  walletAddress: partyId,
})

// wait for it to complete
const result = await swap.wait()
console.log(`Received ${result.actualOutput} ${result.outputToken}`)
In SDK params and responses, use Amulet when you mean CC (Amulet).

What you get

  • Swap tokensCC (Amulet), USDCx, and other CIP-56 tokens
  • Direct-party flow — users deposit from their own Canton party directly to pool parties
  • Real-time quotes — prices, price impact, slippage protection, traffic-cost estimates
  • Event-driven — poll or listen for swap completion

How swaps work

  1. Your app authenticates the developer with an API key
  2. The end user signs a OneSwap challenge with their wallet
  3. OneSwap verifies the signature and returns a short-lived wallet token
  4. You call client.swaps.create() with that wallet token attached
  5. OneSwap returns the pool swap party as depositAddress plus a depositReference
  6. The user sends tokens directly from that same party to the pool party and passes through the reference when the wallet supports Canton reason/reference metadata
  7. OneSwap executes the swap automatically and returns output to the depositor party
That keeps the flow direct-party and non-custodial without trusting a raw party ID string from the browser. Current swap intents remain valid for 24 hours. Respect the returned expiresAt instead of assuming a shorter window. Create your os_live_... API key in the wallet-authenticated OneSwap developer portal. SDK developer auth and SDK swap flows do not use site-access tokens or access codes. Legacy POST /api/sdk/register and POST /api/sdk/login are retired and return 410 Gone.

Quickstart

Install, configure, and run your first swap

SDK Methods

Every method and parameter