Galactic SDK
Hydration SDK built on top of @polkadot{.js} (Pjs).
Table of contents:
Installation
Install with npm:
npm install @galacticcouncil/sdk
Troubleshooting
Version 8.x
⚠️ Important: In the 8.x release, we upgraded @polkadot/api to version 16.x.
See the changelog for details.
Version 2.x
As of v2.x .wasm files are no longer embedded in bundle but rather deferred to improve load performance & decrease module size (esm only).
For more details visit TROUBLESHOOTING.md
Usage
Use createSdkContext to quickly set up all components of the SDK — pool context, trading logic, client access, and transaction building — in a single call.
import { createSdkContext } from '@galacticcouncil/sdk';
import { ApiPromise, WsProvider } from '@polkadot/api';
const ws = 'wss://hydration-rpc.n.dwellir.com';
const wsProvider = new WsProvider(ws, 2_500, {}, 60_000, 102400, 10 * 60_000);
const api = await ApiPromise.create({
provider: wsProvider,
});
const sdk = await createSdkContext(api);
// Don't forget to cleanup resources when DONE
sdk.destroy();
api.disconnect();
It handles all necessary setup under the hood. Just plug in your ApiPromise, and you're ready to interact with registry, accounts, pools, router, and more.
⚠️ Note: Make sure to keep only single instance of context per session.
Components
api
aave: AaveUtils— Aave-related utilities.router: TradeRouter— Off-chain optimization of trades across pools for best price execution.scheduler: TradeScheduler— Trade orders scheduling.
client
asset: AssetClient— Registry metadata and lookup.balance: BalanceClient— Account balance tracking.evm: EvmClient— Interacts with EVM.
ctx
pool: PoolService— Internal stateful pool context. Initialized with support for:- Aave
- Omnipool
- Stableswap
- XYK pools
- LBP pools
tx
TxBuilderFactory— Factory for generating submittable transaction using fluent APIs.
destroy()
Gracefully cleans up SDK resources. Always call before exiting to avoid memory leaks or stale subscriptions.
API Reference
AaveUtils
| Method | Description |
|---|---|
getSummary(user: string): AaveSummary | Returns market summary. |
getHealthFactor(user: string): number | Calculate HF. |
getHealthFactorAfterWithdraw(user: string, reserve:string, withdrawAmount: string): number | Calculate HF after withdraw. |
getHealthFactorAfterSupply(user: string, reserve:string, supplyAmount: string): number | Calculate HF after supply. |
getMaxWithdraw(user: string, reserve:string): Amount | Get max possible safe withdraw. |
➡️ For type definitions visit types.ts
TradeRouter
| Method | Description |
|---|---|
getPools(): PoolBase[] | Returns the current list of available pools. |
getAllPaths(tokenIn: string, tokenOut: string): Hop[][] | Computes possible routes between two assets. |
getAllAssets(): PoolBase[] | Lists all assets that are tradeable through the router. |
getAssetPairs(token: string): Asset[] | Lists all assets given token is tradeable with. |
getBestSell(tokenIn: string, tokenOut: string, amountIn: bigint | string): Trade | Find the best sell trade for given input amount. |
getBestBuy(tokenIn: string, tokenOut: string, amountOut: bigint | string): Trade | Find the best buy trade for given output amount. |
getBuy(tokenIn: string, tokenOut: string, amountOut: bigint | string, route?: Hop[]): Trade | Calculate a buy using a specific route (optional). |
getSell(tokenIn: string, tokenOut: string, amountIn: bigint | string, route?: Hop[]): Trade | Calculate a sell using a specific route (optional). |
getBestSpotPrice(tokenIn: string, tokenOut: string): Amount | Get the current spot price between two tokens. |
getMostLiquidRoute(tokenIn: string, tokenOut: string): Hop[] | Find the route with the highest liquidity between two tokens. |
➡️ For type definitions visit types.ts
TradeScheduler
| Method | Description |
|---|---|
getDcaOrder(assetIn: string, assetOut: string, amountInTotal: string, duration: number): TradeDcaOrder | Calculate DCA order. |
getTwapBuyOrder(assetIn: string, assetOut: string, amountInTotal: string): TradeOrder | Calculate TWAP buy order. |
getTwapSellOrder(assetIn: string, assetOut: string, amountInTotal: string): TradeOrder | Calculate TWAP sell order. |
➡️ For type definitions visit types.ts
AssetClient
| Method | Description |
|---|---|
getOnChainAssets(includeInvalid?: boolean, external?: ExternalAsset[]): Promise<Asset[]> | Returns assets with metadata from registry. |
➡️ For type definitions visit types.ts
Examples
All examples assume SDK has been initialized, see
TradeRouter
Calculate sell of 1 DOT for HDX & build tx with 5% slippage (default to 1% if not specified)
const { api, tx } = sdk;
const trade = await api.router.getBestSell("5", "10", "10");
const tradeTx = await tx.trade(trade)
.withBeneficiary(BENEFICIARY)
.withSlippage(5)
.build();
console.log(trade.toHuman());
console.log('Transaction hash:', tradeTx.hex);
AssetClient
Get default on-chain data.
const { client } = sdk;
const assets = await client.asset.getOnChainAssets();
console.log(assets);
To demonstrate more full working examples on real chain see script section.
Run: $ npx tsx ./test/script/examples/<examplePackage>/<exampleName>.ts with valid example package & name.