For the complete documentation index, see llms.txt. This page is also available as Markdown.

Configure SDK

Learn how to configure the Sodax SDK for your application. The SDK supports Swaps (intent-based solver swaps), Money Market (cross-chain lending and borrowing), and many other cross-chain DeFi services. All feature configurations are optional—you can use just the features you need.

new Sodax(...) accepts SodaxOptions — a deep-partial override of the static SodaxDefaultConfig data shape plus client-side options (logger, global fee, and per-feature partnerFee options). The merged result is SodaxConfig (exposed as sodax.instanceConfig). All three live in @sodax/types and are re-exported from @sodax/sdk.

Basic Configuration

Default Configuration

Initialize the SDK with default Sonic mainnet configurations (no fees):

import { Sodax } from '@sodax/sdk';

const sodax = new Sodax();

The constructor signature is new Sodax(config?: SodaxOptions), where SodaxOptions = DeepPartial<SodaxDefaultConfig> & SodaxOptionalConfig — a deep-partial override of the SodaxDefaultConfig data contract plus the client-side options: the logger sink (see LOGGING.md), the global partner fee, per-feature partnerFee options, and swapsOptions (see Backend submit-tx 2-step). The logger, global fee, and swapsOptions are kept off the data contract: they are resolved once and never fetched from or overwritten by the backend config. When called with no arguments the SDK merges your overrides with the packaged static defaults (sodaxConfig) using a recursive deepMerge. Omitted keys keep their default values.

Dynamic Configuration

For the latest tokens and chains, call initialize() before usage. Without this call the SDK falls back to the static defaults bundled with the installed version:

const initResult = await sodax.initialize();
if (!initResult.ok) {
  console.error('Initialization failed:', initResult.error);
}

initialize() returns Promise<Result<void>>. On success, ConfigService is populated with up-to-date chain and token data fetched from the backend API. On failure the SDK continues to work with the packaged defaults — the error is informational only.

SodaxConfig overview

Top-level data keys (the SodaxDefaultConfig shape carried inside SodaxConfig):

Key
Type (summary)
Role

chains

Record<SpokeChainKey, SpokeChainConfig>

Per-spoke chain addresses, tokens, RPC settings, polling.

swaps

SwapsConfig

Per-chain solver-supported token lists, plus an optional per-feature partnerFee.

moneyMarket

MoneyMarketConfig

Lending pool addresses, reserve assets, supported tokens, plus an optional per-feature partnerFee.

bridge

BridgeConfig

Optional bridge per-feature partnerFee.

dex

DexConfig

Concentrated liquidity contract set and pool keys (Sonic hub).

leverageYield

LeverageYieldConfig

Registry of leverage-yield ERC-4626 vaults on the hub, plus an optional per-feature partnerFee.

hub

HubConfig

Hub chain (Sonic) metadata, contract addresses, and rpcUrl used by EvmHubProvider.

api

ApiConfig

Backend API config — flat BaseApiConfig ({ baseURL, timeout, headers }, shared by sodax.api.swaps) or CustomApiConfig to point swaps at its own endpoint.

solver

SolverConfig

Intents contract addresses and solver HTTP API endpoint.

relay

RelayConfig

Relayer HTTP endpoint and spoke-to-intent relay chain ID map.

The global partner fee is not a data key — it is a SodaxOptions client-side option (like logger). Set it via new Sodax({ fee }) and read the resolved value back on sodax.config.fee. It is the default applied to any feature whose own partnerFee is unset (see Partner Fees).

Partner Fees

Set a global fee once, override it per feature, or both. The effective fee for a feature is featureFee ?? fee — a feature's own partnerFee wins, otherwise the global fee applies. Services read the resolved value through ConfigService getters: SwapService reads config.swapPartnerFee, MoneyMarketService reads config.moneyMarketPartnerFee, BridgeService reads config.bridgePartnerFee, and LeverageYieldService reads config.leverageYieldPartnerFee. See Monetize SDK for usage details and per-request overrides.

Partner fee shapes

Partner fees are either percentage-based or amount-based (PartnerFee is a discriminated union—use one shape per fee object).

Custom configuration

Solver (solver)

Intent-based swaps use the top-level solver block (not nested under swaps). Defaults match solverConfig in @sodax/types.

getSolverConfig() takes no parameters and returns the same object as the exported solverConfig constant from @sodax/sdk.

Partner fees for swaps belong in swaps.partnerFee, not inside solver.

Swaps token lists (swaps.supportedTokens)

SwapsConfig includes supportedTokens: Record<SpokeChainKey, readonly XToken[]>. Normally you rely on the packaged lists. If you override them, remember that deepMerge replaces arrays wholesale—provide the full list for any chain you touch, or omit supportedTokens to keep defaults.

Backend submit-tx 2-step (swapsOptions.useBackendSubmitTx)

swapsOptions is a client-side runtime option on SodaxOptions (like logger) — it is NOT part of the backend-fetched SodaxConfig. Setting useBackendSubmitTx: true opts sodax.swaps.swap() into a backend-driven 2-step flow: after the intent tx is created + verified on the source chain, the SDK hands it to the backend swaps API (sodax.api.swaps.submitTx), which relays and post-executes server-side; the SDK polls submit-tx status and returns the same SwapResponse.

If the backend path does not reach executed for any reason (submission rejected, terminal failed/abandoned status, or poll timeout), swap() automatically falls back to the fully client-side relay + post-execution so the swap still completes — safely, because re-relaying / re-posting an already-processed swap is idempotent (no double-fill; verified by e2e-tests/e2e-relay.test.ts), and the backend poll + fallback share one timeout budget (total latency ≤ one timeout). Default is false. See SWAPS.md for the flow.

Money market (moneyMarket)

MoneyMarketConfig includes lendingPool, uiPoolDataProvider, poolAddressesProvider, bnUSD, bnUSDVault, bnUSDAToken, supportedTokens, supportedReserveAssets, and partnerFee. The packaged default is moneyMarketConfig.

Hub (hub)

The hub is a single HubConfig: chain metadata, hub contract addresses, and rpcUrl used when creating the hub JSON-RPC client. Override RPC or addresses with a partial under hub:

After construction, the merged hub is sodax.instanceConfig.hub (and sodax.hubProvider.chainConfig). sodax.config.getHubChainConfig() returns the static packaged hub snapshot, not the merged instance config—if you customize hub, treat instanceConfig.hub as the source of truth for your overrides.

Per-chain RPC and endpoints (chains)

There is no separate sharedConfig. Spoke RPC URLs and chain-specific settings live on each entry in chains[SpokeChainKey]. Partial objects are merged into the defaults for that key:

EVM spokes use rpcUrl on their spoke config; Stellar uses horizonRpcUrl and sorobanRpcUrl; Bitcoin includes radfi and related fields—mirror the shape of the default SpokeChainConfig for the chain you change.

Backend API (api)

ApiConfig controls baseURL, timeout, and headers for BackendApiService (used by ConfigService and initialize()). It is either a flat BaseApiConfig (shown below — shared by sodax.backendApi and the swaps client sodax.api.swaps) or a nested CustomApiConfig ({ baseApiConfig?, swapsApiConfig? }) to point the swaps API at its own endpoint.

Relayer (relay)

RelayConfig sets relayerApiEndpoint and relayChainIdMap (mapping each SpokeChainKey to the hub intent-relay bigint ID). Override only when pointing at a different relayer or custom map.

DEX (dex)

DexConfig holds concentrated-liquidity addresses and pool keys for Sonic. Most integrations keep the packaged dexConfig default.

Complete custom configuration

Combine the pieces that matter for your deployment:

Service Properties

After construction, the Sodax instance exposes the following read-only service properties:

Property
Type
Description

sodax.swaps

SwapService

Intent-based swaps via solver

sodax.moneyMarket

MoneyMarketService

Cross-chain lending and borrowing

sodax.bridge

BridgeService

Cross-chain token transfers

sodax.staking

StakingService

SODA token staking operations

sodax.dex

DexService

Concentrated liquidity / AMM

sodax.migration

MigrationService

ICX / bnUSD / BALN token migration

sodax.partners

PartnerService

Partner fee claiming and operations

sodax.recovery

RecoveryService

Withdraw stuck hub-wallet assets to a spoke chain

sodax.backendApi

BackendApiService

Raw backend API access

sodax.config

ConfigService

Chain/token config and lookup helpers

sodax.hubProvider

EvmHubProvider

Hub chain (Sonic) contract interactions

sodax.spoke

SpokeService

Spoke chain routing facade

sodax.instanceConfig

SodaxConfig

Resolved config after merging with defaults

Chain Keys

All chain constants live under ChainKeys.* — import them from @sodax/sdk:

SpokeChainKey is the union type of all ChainKeys values. Use it to type any parameter that accepts a chain identifier.

Additional Resources

Last updated