> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneswap.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Trader SDK

> Quote and trade a OneSwap wallet with an administrator-issued Trader SDK key.

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

```bash theme={null}
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.

<Warning>
  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.
</Warning>

## Create the client

```ts theme={null}
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

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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.

<Warning>
  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`.
</Warning>

## History and asynchronous intents

```ts theme={null}
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.