Trader SDK

The Trader SDK lets an approved OneSwap account trade its own wallet from a server-side application. It is separate from the integrator SDK: a trader key is bound to one existing wallet and cannot onboard users or withdraw funds.

Install

npm install @oneswap/trader-sdk

Get a trader key

A OneSwap administrator enables Trader SDK access and issues a key for the approved account and wallet. A trader cannot enable access, create a key, change its wallet binding, or enable three-token fees through the SDK. Contact OneSwap when you need a new or replacement key. The key, account, bound wallet, and requested pool must all remain approved. OneSwap can revoke access immediately.

A trader key can execute trades with real wallet funds. Keep it in a server-side secret manager. Never embed it in a website, browser extension, mobile app, repository, log, or analytics event. Ask OneSwap to revoke and replace an exposed key.

Create the client

import { TraderSDK } from '@oneswap/trader-sdk'

const trader = new TraderSDK({
  apiKey: process.env.ONESWAP_TRADER_KEY!,
  environment: 'mainnet',
})

The wallet is resolved from the administrator-issued key, so SDK methods do not accept a walletId. Self-custody wallets also require an active OneSwap user mandate; the trader key never contains or replaces the self-custody key.

Discover pools, tokens, and balances

const pools = await trader.pools()
const tokens = await trader.tokens()
const balances = await trader.balances()

const pool = pools.find((candidate) => candidate.id === 'rt-...')
if (!pool) throw new Error('Pool is unavailable to this trader')

A pool has an ordered pair of assets. xToY: true spends assetX and receives assetY; false reverses the direction.

Quote and swap

Quote immediately before a swap and use the quote to set the output floor:

const quote = await trader.quote({
  poolId: pool.id,
  amountIn: 100,
  xToY: true,
  feeMode: 'prepaid',
})

if (!quote.sufficientFunds) throw new Error('Insufficient spendable balance')

const result = await trader.swap({
  poolId: pool.id,
  amountIn: 100,
  xToY: true,
  minAmountOut: quote.amountOut * 0.99,
  feeMode: quote.feeMode,
  idempotencyKey: 'order-1042',
})

Use a unique idempotencyKey for each intended swap. Reuse it only when retrying that exact swap, so a timeout or process restart cannot execute the order twice.

Three-token network fees

When a OneSwap administrator has enabled the trader and configured a distinct fee instrument for a synchronous atomic pool, select it explicitly on both calls:

const tokenFeeQuote = await trader.quote({
  poolId: pool.id,
  amountIn: 100,
  xToY: true,
  feeMode: 'token',
})

if (tokenFeeQuote.sufficientFunds) {
  await trader.swap({
    poolId: pool.id,
    amountIn: 100,
    xToY: true,
    minAmountOut: tokenFeeQuote.amountOut * 0.99,
    feeMode: 'token',
    idempotencyKey: 'order-1043',
  })
}

For Trader SDK quotes, tokenFee.amount is derived from the live Canton traffic cost, including the extra fee-token allocation. OneSwap subtracts measured reward recovery, applies the best applicable global, pool, account, or wallet network-fee promotion, and then converts CC → USDCx → the configured fee token at live prices. The quote reports the final amount and authoritative fee-token balance checks. A trader with a 100% promotion receives amount: 0 and promotionalWaiver: true; settlement omits the fee allocation. A trader without that promotion pays the converted amount shown in the final quote. When charged, the swap input, output, and fee-token allocation settle atomically.

Use the same pool, direction, amount, and feeMode for the quote and swap. Do not reuse a prepaid quote for a token-fee swap or switch fee modes after calculating minAmountOut.

History and asynchronous intents

const history = await trader.history({ limit: 50 })

if (result.status === 'reserved' && result.intentId) {
  const status = await trader.intent(result.intentId)
  console.log(status.status)
}

Synchronous pools return their settlement result directly. For an asynchronous pool, poll the returned intent until it reaches a terminal state. Three-token settlement is available only on synchronous atomic pools.

Disable access

Contact OneSwap to revoke a key, disable Trader SDK access, or change three-token eligibility. Revoked access is rejected on subsequent SDK calls.

Getting Started

Guides

Reference

Install

Get a trader key

Create the client

Discover pools, tokens, and balances

Quote and swap

Three-token network fees

History and asynchronous intents

Disable access

​Install

​Get a trader key

​Create the client

​Discover pools, tokens, and balances

​Quote and swap

​Three-token network fees

​History and asynchronous intents

​Disable access

Install

Get a trader key

Create the client

Discover pools, tokens, and balances

Quote and swap

Three-token network fees

History and asynchronous intents

Disable access