Skip to main content

​
1. Install

npm install @oneswap/sdk

​
2. Get your API key

Create your SDK API key from the wallet-authenticated OneSwap developer portal.
  • os_live_... keys identify your integration.
  • Authenticate your Canton wallet, call POST /api/sdk/wallet-login, then create keys on POST /api/sdk/keys.
  • SDK developer auth and SDK swap flows do not use site-access tokens or access codes.
  • Developer earnings, collections, and account analytics stay on the wallet-authenticated developer portal.
  • Legacy POST /api/sdk/register and POST /api/sdk/login are retired and return 410 Gone.

​
3. Initialize

import { OneSwap } from '@oneswap/sdk'

const apiKey = 'os_live_...'
const authClient = new OneSwap({ apiKey })
In SDK code, use Amulet when you mean CC (Amulet).

​
4. Verify the user’s wallet

Ask the user to sign the OneSwap challenge with the same wallet that will send the deposit. 
const partyId = 'alice::12205a8c...'

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,
})
If your app stores and refreshes the wallet token in browser state, you can pass walletToken as a function instead of a fixed string.

​
5. Get a quote

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

console.log(quote.outputAmount)
console.log(quote.rate)
console.log(quote.priceImpact)
console.log(quote.inputTokenAdmin)
console.log(quote.outputTokenAdmin)
console.log(quote.estimatedTrafficCost?.cc)
console.log(quote.trafficFeeInInput)
console.log(quote.inputAmountAfterTrafficFee)
quote.outputAmount is already calculated from quote.inputAmountAfterTrafficFee. The traffic recovery is separate from the 1% swap fee. If a token symbol exists under multiple admins, pass poolId or both token admin fields (fromAdmin and toAdmin) so OneSwap can resolve the exact pool pair.

​
6. Create a swap intent

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

console.log(swap.depositAddress) // pool swap party
console.log(swap.depositReference) // pass through when the wallet supports Canton reason/reference metadata
console.log(swap.expectedOutput)
console.log(swap.expiresAt)
The walletAddress field is optional, but if you send it, it must match the authenticated wallet token. Swap intents currently remain valid for 24 hours. Use swap.expiresAt from the response rather than hard-coding the timeout.

​
7. Send the deposit

The user sends tokens from partyId directly to swap.depositAddress and passes through swap.depositReference when the wallet supports Canton reason/reference metadata. Do not send from a different wallet or Canton party, or the swap will not complete.

​
8. Wait for completion

swap.on('processing', () => console.log('Deposit detected'))

const result = await swap.wait()
console.log(`Done! Got ${result.actualOutput} ${result.outputToken}`)
If slippage is exceeded, the swap is refunded automatically to the depositor party.

​
What’s next

Swaps Guide

Slippage, status polling, and failure states

Wallet Guide

Connect a wallet and manage wallet tokens

SDK Methods

Review the swaps-focused SDK surface