Setup
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | required | Your OneSwap SDK API key (os_live_...). |
walletToken | string | (() => string | Promise<string | undefined> | undefined) | none | Optional end-user wallet token, or a lazy getter, for wallet-authenticated SDK calls. |
timeout | number | 30000 | Request timeout in ms |
apiKey values through the wallet-authenticated OneSwap developer portal. Authenticate your wallet on POST /api/sdk/wallet-login, then create or rotate keys on POST /api/sdk/keys. SDK developer auth and SDK swap flows do not use site-access tokens or access codes.
In SDK params and responses, use Amulet when you mean CC (Amulet).
Pools
| Method | Description |
|---|---|
client.pools.list() | All pools with effective reserves, fee, and LP supply |
client.pools.get(poolId) | Pool detail with swapAddress and lpAddress |
client.pools.getStats(poolId, { days? }) | apr, apy, volume24h, fees24h, lpFees24h, tvl, swapCount24h, and APR metadata computed from fee events and effective reserves. Default lookback is 7 days. |
Tokens
| Method | Description |
|---|---|
client.tokens.list() | Available tokens with name and admin |
Quotes
| Method | Description |
|---|---|
client.quotes.get({ from, to, amount, receiverParty?, poolId?, fromAdmin?, toAdmin? }) | Price quote. Includes estimatedTrafficCost, trafficFeeInInput, and inputAmountAfterTrafficFee. outputAmount is based on the net input after traffic recovery. When token symbols are reused across issuers, pass poolId or both admin fields to disambiguate the pool pair. |
inputTokenAdmin and outputTokenAdmin so you can keep working with the exact instrument identity that was priced.
Swaps
| Method | Description |
|---|---|
client.swaps.create(params) | Create a wallet-authenticated swap intent |
client.swaps.getStatus(intentId) | Poll swap status for the authenticated wallet party |
client.swaps.cancel(intentId) | Cancel a pending swap intent for the authenticated wallet party |
Wallet auth
| Method | Description |
|---|---|
client.walletAuth.requestChallenge(partyId) | Create a signable OneSwap wallet-auth challenge |
client.walletAuth.verifyChallenge(params) | Verify the signed challenge and return a wallet token |
swaps.create params
| Param | Required | Description |
|---|---|---|
fromToken | yes | Input token |
toToken | yes | Output token |
amount | yes | Input amount |
slippageTolerance | no | 0.001–0.5, default 0.01 |
walletAddress | no | Optional sender party ID for UI clarity. If present, it must match the authenticated wallet token. |
poolId | no | Preferred disambiguator when the token pair can map to more than one pool. |
fromAdmin | no | Exact admin for the input token when token symbols are reused. |
toAdmin | no | Exact admin for the output token when token symbols are reused. |
outputAddress | no | Deprecated. Ignored by the SDK client because the current execution flow always pays back to the depositor party. |
SwapIntent object
Properties:intentId, poolId, depositAddress, swapAddress, depositReference, inputToken, inputTokenAdmin, outputToken, outputTokenAdmin, expectedAmount, expectedOutput, minOutput, slippageTolerance, outputAddress, expiresAt, instructions.
Notes:
depositAddressis the pool swap party, not the user’s own party.depositReferenceis recommended when your wallet flow supports Canton reason/reference metadata. Sender attribution does not depend on it for standard 1-step transfers.client.swaps.create(...)requires both a valid API key and a wallet-authenticated end-user token.- The deposit must be sent from the same signed-in wallet party used to create the swap intent.
- A different wallet or Canton party will not complete the swap intent.
- Current backend swap intents give you a 24-hour deposit window. Use
expiresAtfrom the response instead of hard-coding the timeout. outputAddressin the response is the resolved destination party. In the current flow it matches the depositor party.
| Method / Event | Description |
|---|---|
swap.cancel() | Cancel a pending swap intent |
swap.wait(opts?) | Await terminal state |
'matched' | A matching intent/deposit pair has been claimed |
'deposit_received' | The input deposit has been attributed to the swap |
'forwarded' | The swap has moved past deposit handling and into settlement |
'processing' | Deposit detected, swap executing |
'sending_output' | OneSwap is sending output back to the depositor party |
'completed' | Swap done |
'slippage_failed' | Refunded because price moved |
'price_impact_exceeded' | Refunded because price impact exceeded the server cap |
'insufficient_amount' | Refunded because input is below traffic cost |
'insufficient_liquidity' | Refunded because pool liquidity is insufficient |
'output_failed' | Output transfer failed and the input refund succeeded |
'no_output_holdings' | No output inventory was available on the swap party |
'failed' | Swap reached a generic terminal failure state |
'refund_failed' | Refund path failed and manual intervention is required |
'expired' | Timed out |
'cancelled' | Intent was cancelled before execution started |
Track
| Method | Description |
|---|---|
client.track(partyId) | Swap intents only for the wallet-authenticated Canton party under your API key. The partyId must match the authenticated wallet token. |