kinok-ref-sdk
Advanced tools
This SDK is designed to assist developers when interacting with the main functions of the protocol. Main functions that can be defined as:
This SDK is designed to assist developers when interacting with the main functions of the protocol. Main functions that can be defined as:
yarn: yarn add @ref-finance/ref-sdk
npm: npm install @ref-finance/ref-sdk
Ref SDK identifies env variable NEAR_ENV or REACT_APP_REF_SDK_ENV to get global configuration.
export function getConfig(
env: string | undefined = ENV ||
process.env.NEAR_ENV ||
process.env.REACT_APP_REF_SDK_ENV
) {
ENV = env;
switch (env) {
case 'mainnet':
return {
networkId: 'mainnet',
nodeUrl: 'https://rpc.mainnet.near.org',
walletUrl: 'https://wallet.near.org',
WRAP_NEAR_CONTRACT_ID: 'wrap.near',
REF_FI_CONTRACT_ID: 'v2.ref-finance.near',
REF_TOKEN_ID: 'token.v2.ref-finance.near',
indexerUrl: 'https://indexer.ref.finance',
explorerUrl: 'https://testnet.nearblocks.io',
REF_DCL_SWAP_CONTRACT_ID: 'dclv2.ref-labs.near',
};
case 'testnet':
return {
networkId: 'testnet',
nodeUrl: 'https://rpc.testnet.near.org',
walletUrl: 'https://wallet.testnet.near.org',
indexerUrl: 'https://testnet-indexer.ref-finance.com',
WRAP_NEAR_CONTRACT_ID: 'wrap.testnet',
REF_FI_CONTRACT_ID: 'ref-finance-101.testnet',
REF_TOKEN_ID: 'ref.fakes.testnet',
explorerUrl: 'https://testnet.nearblocks.io',
REF_DCL_SWAP_CONTRACT_ID: 'dclv2.ref-dev.testnet',
};
default:
return {
networkId: 'mainnet',
nodeUrl: 'https://rpc.mainnet.near.org',
walletUrl: 'https://wallet.near.org',
REF_FI_CONTRACT_ID: 'v2.ref-finance.near',
WRAP_NEAR_CONTRACT_ID: 'wrap.near',
REF_TOKEN_ID: 'token.v2.ref-finance.near',
indexerUrl: 'https://indexer.ref.finance',
explorerUrl: 'https://nearblocks.io',
REF_DCL_SWAP_CONTRACT_ID: 'dclv2.ref-labs.near',
};
}
}
Also, the SDK provides init_env to switch application environment. there is an optional parameter indexerUrl that you can use to replace the one in the SDK with your own deployed indexer service. We'd better call it at the entrance of the application, then the entire application environment switch takes effect. If you're not sure where to call, you can call in more than one place.
Example
init_env('testnet');
init_env('mainnet');
init_env('testnet', 'https://xx-xx.xx-xxx.com');
init_env('mainnet', 'https://xx-xx.xx-xxx.com');
Get token metadata.
Parameters
id: string;
Example
const WrapNear = await ftGetTokenMetadata('wrap.testnet');
Response
{
decimals: 24;
icon: null;
id: 'wrap.testnet';
name: 'Wrapped NEAR fungible token';
reference: null;
reference_hash: null;
spec: 'ft-1.0.0';
symbol: 'wNEAR';
}
Get tokens metadata and set token id as index.
Will fetch token matadata if the token not included in the allTokens.
Parameters
(tokenIds: string[], allTokens: Record<string, TokenMetadata>)
Example
const tokensMetadata = await ftGetTokensMetadata([
'ref.fakes.testnet',
'wrap.testnet',
],{});
Response
{
"ref.fakes.testnet":{
decimals: 18
icon: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='16 24 248 248' style='background: %23000'%3E%3Cpath d='M164,164v52h52Zm-45-45,20.4,20.4,20.6-20.6V81H119Zm0,18.39V216h41V137.19l-20.6,20.6ZM166.5,81H164v33.81l26.16-26.17A40.29,40.29,0,0,0,166.5,81ZM72,153.19V216h43V133.4l-11.6-11.61Zm0-18.38,31.4-31.4L115,115V81H72ZM207,121.5h0a40.29,40.29,0,0,0-7.64-23.66L164,133.19V162h2.5A40.5,40.5,0,0,0,207,121.5Z' fill='%23fff'/%3E%3Cpath d='M189 72l27 27V72h-27z' fill='%2300c08b'/%3E%3C/svg%3E%0A"
id: "ref.fakes.testnet"
name: "Ref Finance Token"
reference: null
reference_hash: null
spec: "ft-1.0.0"
symbol: "REF"
},
"wrap.testnet":{
decimals: 24
icon: null
id: "wrap.testnet"
name: "Wrapped NEAR fungible token"
reference: null
reference_hash: null
spec: "ft-1.0.0"
symbol: "wNEAR"
}
}
Fetch all existing pools, including vanilla/simple pools, stable pools and rated pools (designed for yield-bearing tokens).
Parameters
perPage?：number
Example
const { ratedPools, unRatedPools, simplePools } = await fetchAllPools();
const { ratedPools, unRatedPools, simplePools } = await fetchAllPools(200);
Response
{
ratedPools:[{
fee: 5,
id: 568,
pool_kind: "RATED_SWAP",
shareSupply: "80676034815429711745720012070",
supplies:{
"meta-v2.pool.testnet": "1298314415249170366960739764"
"wrap.testnet": "80182803630538035347294614770"
},
token0_ref_price: undefined,
tokenIds: ["meta-v2.pool.testnet", "wrap.testnet"],
tvl: undefined
},...]
unRatedPools:[...],
simplePools:[...],
}
We define unRatedPools and ratedPools as stablePool. You can use this function to get details of stable pools.
Parameters
stablePools: Pool[]
Example
const stablePools: Pool[] = unRatedPools.concat(ratedPools);
const stablePoolsDetail: StablePool[] = await getStablePools(stablePools);
Response
[
{
amounts: ['1298314415249170366960739764', '80182803630538035347294614770'],
amp: 240,
c_amounts:["1298314415249170366960739764","80182803630538035347294614770"],
decimals:[24,24],
id: 568,
pool_kind: "RATED_SWAP",
rates:["1972101024157559347385372","1000000000000000000000000"],
shares_total_supply: "80676034815429711745720012070",
token_account_ids:["meta-v2.pool.testnet","wrap.testnet"],
total_fee:5
},
...
]
Input pool id array to get according pools detail
Parameters
ids: number[]
Example
const pools = await getPoolByIds([1, 2, 20])
Response
[
{
"id": 1,
"tokenIds": [
"nusdt.ft-fin.testnet",
"nusdc.ft-fin.testnet"
],
"supplies": {
"nusdt.ft-fin.testnet": "194177",
"nusdc.ft-fin.testnet": "54127"
},
"fee": 20,
"shareSupply": "1004672374319452764166320",
"pool_kind": "SIMPLE_POOL"
},
{
"id": 2,
"tokenIds": [
"wrap.testnet",
"rft.tokenfactory.testnet"
],
"supplies": {
"wrap.testnet": "511569006838329327251856820",
"rft.tokenfactory.testnet": "860281941972"
},
"fee": 20,
"shareSupply": "935312501418615016412773941",
"pool_kind": "SIMPLE_POOL"
},
{
"id": 20,
"tokenIds": [
"usdc.fakes.testnet",
"nusdc.ft-fin.testnet"
],
"supplies": {
"usdc.fakes.testnet": "129199395436",
"nusdc.ft-fin.testnet": "26747"
},
"fee": 20,
"shareSupply": "7084500646929369809446253",
"pool_kind": "SIMPLE_POOL"
}
]
Get token output amount and corresponding route.
As there is a memory limitation on Ledger, note that we set enableSmartRouting option for developers.
This function integrates a smart routing algorithm, designed to deliver the best output token amount.
Parameters
interface SwapParams {
tokenIn: TokenMetadata;
tokenOut: TokenMetadata;
amountIn: string;
simplePools: Pool[];
options?: SwapOptions;
}
interface SwapOptions {
enableSmartRouting?: boolean;
stablePools?: Pool[];
stablePoolsDetail?: StablePool[];
}
Example (enableSmartRouting == false)
// enableSmartRouting as FALSE, swap from Ref to wNear, with amount 1
const tokenIn = await ftGetTokenMetadata('ref.fakes.testnet');
const tokenOut = await ftGetTokenMetadata('wrap.testnet');
const swapTodos: EstimateSwapView[] = await estimateSwap({
tokenIn,
tokenOut,
amountIn: '1',
simplePools,
});
Response (enableSmartRouting == false)
// enableSmartRouting as FALSE, swap from Ref to wNear, with amount 1
[
{
estimate: '0.7338604246699393',
inputToken: 'ref.fakes.testnet',
outputToken: 'wrap.testnet',
pool: {
fee: 30,
id: 38,
partialAmountIn: '1000000000000000000',
pool_kind: 'SIMPLE_POOL',
shareSupply: '1000587315520795219676332',
supplies: {
'ref.fakes.testnet': '7789776060978885018',
'wrap.testnet': '6467670222256390319335181',
},
token0_ref_price: undefined,
tokenIds: (2)[('ref.fakes.testnet', 'wrap.testnet')],
tvl: undefined,
},
},
];
Example (enableSmartRouting == true)
// enableSmartRouting as TRUE, swap from Ref to wNear, with amount 1
const tokenIn = await ftGetTokenMetadata('ref.fakes.testnet');
const tokenOut = await ftGetTokenMetadata('wrap.testnet');
const options: SwapOptions = {
enableSmartRouting: true,
stablePools,
stablePoolsDetail,
};
const swapTodos: EstimateSwapView[] = await estimateSwap({
tokenIn,
tokenOut,
amountIn: '1',
simplePools,
options,
});
Response (enableSmartRouting == true)
// enableSmartRouting as true, swap from Ref to wNear, with amount 1
[
{
estimate: "0.000225321544275095902371355566972009167",
inputToken: "ref.fakes.testnet",
outputToken: "nusdt.ft-fin.testnet",
pool:{
id: 341,
partialAmountIn: "836859596261755688",
tokenIds: ["ref.fakes.testnet","nusdt.ft-fin.testnet"],
...
},
...
},{
estimate: "0.5203255327171591155634413370660973429264",
inputToken: "nusdt.ft-fin.testnet",
outputToken: "wrap.testnet",
pool:{
id: 1625,
tokenIds: ["nusdt.ft-fin.testnet","wrap.testnet"],
...
},
...
},{
estimate: "5.3206339674140066489000963525772735539612",
inputToken: "ref.fakes.testnet",
outputToken: "usdn.testnet",
pool:{
id: 376,
tokenIds: ["usdn.testnet","ref.fakes.testnet"],
partialAmountIn: "163140403738244312",
...
},
...
},{
estimate: "0.2036473132202839680683206178037243543302",
inputToken: "usdn.testnet",
outputToken: "wrap.testnet",
pool:{
id: 385,
tokenIds: ["usdn.testnet","wrap.testnet"],
...
},
...
}
]
Get token output amount from swapTodos.
Parameters
(swapTodos: EstimateSwapView[], outputToken: string)
Example
const swapTodos: EstimateSwapView[] = await estimateSwap({
tokenIn,
tokenOut,
amountIn: '1',
simplePools,
options,
});
const amountOut:string = getExpectedOutputFromSwapTodos(swapTodos, tokenOut.id);
Response
"0.723972845937443"
Get token output amount from one single pool. Method can be used for simple and stable pools.
Parameters
{
tokenIn: TokenMetadata;
tokenOut: TokenMetadata;
amountIn: string;
pool: Pool;
// please input stablePoolDetail if you want estimate output on stable pool or the pool will be recognized as simple pool
stablePoolDetail?: StablePool;
}
Example (on simple pool)
// estimate on simple Pool
const estimate = await getPoolEstimate({
tokenIn,
tokenOut,
amountIn: '1',
pool,
});
Response (on simple pool)
// estimate on simple pool, swap from Ref to wNear, with amount 1
{
estimate: "0.7338604246699393",
inputToken: "ref.fakes.testnet",
outputToken: "wrap.testnet",
pool:{
fee: 30,
id: 38,
partialAmountIn: "1000000000000000000",
pool_kind: "SIMPLE_POOL",
shareSupply: "1000587315520795219676332",
supplies: {"ref.fakes.testnet": '7789776060978885018', "wrap.testnet": '6467670222256390319335181'},
token0_ref_price: undefined,
tokenIds: (2) ['ref.fakes.testnet', 'wrap.testnet'],
tvl: undefined
}
}
Example (on stable pool)
// estimate on stable pool
const estimate = await getPoolEstimate({
tokenIn,
tokenOut,
amountIn: '1',
pool: stablePool,
stablePoolDetail: stablePoolDetail,
});
Response (on stable pool)
// estimate on stable pool, swap from stNear to wNear, with amount 1
{
estimate: "2.4898866773442284",
inputToken: "meta-v2.pool.testnet",
noFeeAmountOut: "2.491132243465961",
outputToken: "wrap.testnet",
pool:{
amounts:["1298314415249170366960739764","80182803630538035347294614770"],
amp: 240,
c_amounts:["1298314415249170366960739764","80182803630538035347294614770"],
decimals:[24,24],
id: 568,
pool_kind: "RATED_SWAP",
rates:["1972204647926836788049038","1000000000000000000000000"],
shares_total_supply: "80676034815429711745720012070",
token_account_ids:["meta-v2.pool.testnet", "wrap.testnet"],
total_fee: 5,
}
}
Set up transactions through swap routes. Please ensure that the AccountId has an active balance storage in the token-in contract, otherwise the transaction will fail and the user will lose the token input amount.
Parameters
{
tokenIn: TokenMetadata;
tokenOut: TokenMetadata;
amountIn: string;
slippageTolerance: number;
swapTodos: EstimateSwapView[];
AccountId: string;
referralId?: string;
}
Example
const transactionsRef: Transaction[] = await instantSwap({
tokenIn,
tokenOut,
amountIn: '1',
swapTodos,
slippageTolerance = 0.01,
AccountId: 'your-account-id.testnet',
referralId: 'ref-fee.testnet'
});
Response
[
{
functionCalls: [
{
amount: '0.000000000000000000000001',
args: {
amount: '1000000000000000000',
msg:
'{"force":0,"referral_id":"ref-fee.testnet" ,"actions":[{"pool_id":38,"token_in":"ref.fakes.testnet","token_out":"wrap.testnet","amount_in":"1000000000000000000","min_amount_out":"730191122546589600000000"}]}',
receiver_id: 'ref-finance-101.testnet',
},
gas: '180000000000000',
methodName: 'ft_transfer_call',
},
],
receiverId: 'ref.fakes.testnet',
},
];
In the local env, developers can add credentials by near login .
This function utilizes credentials stored in the local env to sign transactions.
Parameters
{
transactionsRef: Transaction[];
AccountId: string;
keyPath: string;
}
Example
const signedTransactions:nearTransactions.SignedTransaction[] = await getSignedTransactionsByMemoryKey({
transactionsRef;
AccountId: "your-account-id.testnet",
keyPath: "/.near-credentials/testnet/your-account-id.testnet.json"
})
Response
[
SignedTransaction {
transaction: Transaction {
signerId: 'your-account-id.testnet',
publicKey: [PublicKey],
nonce: 91940092000042,
receiverId: 'ref.fakes.testnet',
actions: [Array],
blockHash: <Buffer 45 e5 fd 36 87 3b 10 59 81 d9 a7 b5 20 c7 29 33 f7 27 48 59 06 90 ca 8a 17 03 5c 25 f2 76 ab 7c>
},
signature: Signature { keyType: 0, data: [Uint8Array] }
}
]
This function utilizes credentials stored in the local env to send transactions.
Parameters
{
signedTransactions: nearTransactions.SignedTransaction[];
}
Example
sendTransactionsByMemoryKey({
signedTransactions,
});
Response
[
{
receipts_outcome: [
[Object], [Object],
[Object], [Object],
[Object], [Object],
[Object], [Object],
[Object], [Object]
],
status: { SuccessValue: 'xxxxxx' },
transaction: {
actions: [Array],
hash: 'xxxxxxxx',
nonce: 91940092000042,
public_key: 'ed25519:xxxxxxxx',
receiver_id: 'ref.fakes.testnet',
signature: 'ed25519:xxxxxxxxxxxxx',
signer_id: 'your-account-id.testnet'
},
transaction_outcome: {
block_hash: '3QXEF941UvsHzXrMhwbchk7wmy3qmPNs3w9gkfvW84QK',
id: 'xxxxxxxx',
outcome: [Object],
proof: []
}
}
]
The Ref Swap Widget is a useful tool, allowing any third party service to access Ref's liquidity. Users of ecosystem dapps have the ability to swap via the Widget, without the need to go to Ref app, thus improving the user experience.
Here are some use cases:
Using the Ref Swap Widget, with a few customizations, developers can integrate the Swap funtion directly into their dapps. Both mobile and/or website version are available.
For the default theme, developers can chose between the light mode and dark mode.
More themes can be selected: Click here to check them on figma.
To integrate the Ref Swap Widget, please follow this guide.
A QuickStart of Ref Swap component.
export interface SwapWidgetProps {
theme?: Theme;
defaultTokenList?: string[];
onSwap: (transactionsRef: Transaction[]) => void;
onDisConnect: () => void;
width: string;
height?: string;
enableSmartRouting?: boolean;
className?: string;
darkMode?: boolean;
connection: {
AccountId: string;
isSignedIn: boolean;
};
defaultTokenIn?: string;
defaultTokenOut?: string;
referralId?:string;
transactionState?: {
state: 'success' | 'fail' | null;
tx?: string;
detail?: string;
};
onConnect: () => void;
}
export interface Theme {
container: string; // container background
buttonBg: string; // button background
primary: string; // primary theme color
secondary: string; // secondary theme color
borderRadius: string; // border radius
fontFamily: string; // font family
hover: string; // hovering color
active: string; // active color
secondaryBg: string; // secondary background color
borderColor: string; // border color
iconDefault: string; // default icon color
iconHover: string; // icon hovering color
refIcon?: string; // ref icon color, default to be black
}
export const defaultTheme: Theme = {
container: '#FFFFFF',
buttonBg: '#00C6A2',
primary: '#000000',
secondary: '#7E8A93',
borderRadius: '4px',
fontFamily: 'sans-serif',
hover: 'rgba(126, 138, 147, 0.2)',
active: 'rgba(126, 138, 147, 0.2)',
secondaryBg: '#F7F7F7',
borderColor: 'rgba(126, 138, 147, 0.2)',
iconDefault: '#7E8A93',
iconHover: '#B7C9D6',
};
export const defaultDarkModeTheme: Theme = {
container: '#26343E',
buttonBg: '#00C6A2',
primary: '#FFFFFF',
secondary: '#7E8A93',
borderRadius: '4px',
fontFamily: 'sans-serif',
hover: 'rgba(126, 138, 147, 0.2)',
active: 'rgba(126, 138, 147, 0.2)',
secondaryBg: 'rgba(0, 0, 0, 0.2)',
borderColor: 'rgba(126, 138, 147, 0.2)',
iconDefault: '#7E8A93',
iconHover: '#B7C9D6',
refIcon: 'white',
};
// an example of combining SwapWidget with wallet-selector
import * as React from 'react';
import { SwapWidget } from '@ref-finance/ref-sdk';
// please check on wallet-selector example about how to set WalletSelectorContext
import { useWalletSelector } from './WalletSelectorContext';
import { WalletSelectorTransactions, NotLoginError } from '@ref-finance/ref-sdk';
export const Widget = ()=>{
const { modal, selector, accountId } = useWalletSelector();
const [swapState, setSwapState] = React.useState<'success' | 'fail' | null>(
null
);
const [tx, setTx] = React.useState<string | undefined>(undefined);
React.useEffect(() => {
const errorCode = new URLSearchParams(window.location.search).get(
'errorCode'
);
const transactions = new URLSearchParams(window.location.search).get(
'transactionHashes'
);
const lastTX = transactions?.split(',').pop();
setTx(lastTX);
setSwapState(!!errorCode ? 'fail' : !!lastTX ? 'success' : null);
window.history.replaceState(
{},
'',
window.location.origin + window.location.pathname
);
}, []);
const onSwap = async (transactionsRef: Transaction[]) => {
const wallet = await selector.wallet();
if (!accountId) throw NotLoginError;
wallet.signAndSendTransactions(
WalletSelectorTransactions(transactionsRef, accountId)
);
};
const onConnect = () => {
modal.show();
};
const onDisConnect = async () => {
const wallet = await selector.wallet();
return await wallet.signOut();
};
return (
<SwapWidget
onSwap={onSwap}
onDisConnect={onDisConnect}
width={'400px'}
connection={{
AccountId: accountId || '',
isSignedIn: !!accountId,
}}
transactionState={{
state: swapState,
setState: setSwapState,
tx,
detail: '(success details show here)',
}}
enableSmartRouting={true}
onConnect={onConnect}
defaultTokenIn={'wrap.testnet'}
defaultTokenOut={'ref.fakes.testnet'}
/>
);
}
The SDK provides more flexibility/options.
The default Swap version can serve as a reference. Click here to check on figma.
For more details about the SDK, please refer to [here].
SDK integration tips:
The launch of concentrated liquidity AMM is an achievement for Ref Finance. In collaboration with Izumi Finance and Arctic, Ref is glad to introduce discretized concentrated liquidity and limit order two new key features to the NEAR ecosystem. Using REF SDK, developers can dig more opportunities and implement various trading strategies.Before introducing SDK details, let's have an overview of V2 exciting features.
Discretized concentrated liquidity can improve as much as 4000x higher capital efficiency for liquidity providers(LPs).
When adding liquidity, LPs are can allocate their capital to a certain price range thus providing greater amounts of liquidity at this range. The fees earned are decided by the volumes swapped in the price range. Logically, if you want to earn more, you should set the price range most desired by the market.
Here are the advantages of using Ref V2 concentrated liquidity for LPS.
Izumi's algorithm of constant sum formula on small price range fragment enables an enhanced limit order function that is different than Uniswap V3. The following remarkable improvements are noticeable.
Enhanced limit order will give more convenience for strategy trading like grid trading, arbitrage, day trading, etc.
With much thicker liquidity around the current price point, swap slippage has a notable decrease.
As mentioned above, we've compared our development features of this model in comparison to Uniswaps model, from Ethereum to NEAR, but far less costly. Ref V2 provides a more capital efficient, user-friendly experience with dynamic pricing, reduced fees, and cross-chain integrations.
The combination of concentrated liquidity, enhanced limit order and decreased swap slippage offers a good tool kit for trading in NEAR ecosystem. Enjoy it.
Get DCL pool id by tokenA, tokenB and fee.
Note: the fee should be in one of [100, 400, 2000, 10000], which means we charge [0.01%, 0.04%, 0.2%, 1%] separately.
Parameters
(tokenA:string, tokenB:string, fee:number)
Example
const tokenA = "usdt.fakes.testnet";
const tokenB = "wrap.testnet";
const fee = 2000
const pool_id = getDCLPoolId(tokenA, tokenB, fee)
Response
"usdt.fakes.testnet|wrap.testnet|2000"
List all DCL pools
Parameters
None
Example
const allDCLPools = await listDCLPools()
Response
[
{
pool_id: 'usdt.fakes.testnet|wrap.testnet|100',
token_x: 'usdt.fakes.testnet',
token_y: 'wrap.testnet',
fee: 100,
point_delta: 1,
current_point: 391459,
liquidity: '0',
liquidity_x: '0',
max_liquidity_per_point: '212676346402870037870835460372692',
volume_x_in: '0',
volume_y_in: '0',
volume_x_out: '0',
volume_y_out: '0',
total_liquidity: '0',
total_order_x: '1000000000000',
total_order_y: '0',
total_x: '1000000000000',
total_y: '0',
state: 'Running'
},
...
]
Get DCL pool by pool id
Parameters
(pool_id: string)
Example
const tokenA = "usdt.fakes.testnet";
const tokenB = "wrap.testnet";
const fee = 2000
const pool_id = getDCLPoolId(tokenA, tokenB, fee)
const pool = await getDCLPool(pool_id)
Response
{
pool_id: 'usdt.fakes.testnet|wrap.testnet|2000',
token_x: 'usdt.fakes.testnet',
token_y: 'wrap.testnet',
fee: 2000,
point_delta: 40,
current_point: 380120,
liquidity: '1110725876876975',
liquidity_x: '1110725876876975',
max_liquidity_per_point: '8506846501860915063707772491481918',
volume_x_in: '8754783773',
volume_y_in: '109748224827667685031216606',
volume_x_out: '1220525924',
volume_y_out: '1301582127053053120024924721',
total_liquidity: '9961756656973511',
total_order_x: '101475486843',
total_order_y: '31907047396923536842194449',
total_x: '125636676594',
total_y: '131645349254303605341104269',
state: 'Running'
}
quote output amount by pool_ids, input_amount, input_token, output_token
Parameters
{
pool_ids: string[];
input_token: TokenMetadata;
output_token: TokenMetadata;
input_amount: string;
tag?: string;
}
Example
const tokenA = "usdt.fakes.testnet";
const tokenB = "wrap.testnet";
const fee = 10000
const pool_ids = [getDCLPoolId(tokenA, tokenB, fee)];
const tokenAMetadata = await ftGetTokenMetadata(tokenA)
const tokenBMetadata = await ftGetTokenMetadata(tokenB)
const res = await quote({
pool_ids,
input_amount,
input_token: tokenAMetadata,
output_token: tokenBMetadata,
});
Response
{ amount: '203807761645099642566723', tag: null }
quote in put amount by output amount to price by pool_ids, input_amount, input_token, output_token
Parameters
{
pool_ids: string[];
input_token: TokenMetadata;
output_token: TokenMetadata;
input_amount: string;
tag?: string;
}
Example
const tokenA = "usdt.fakes.testnet";
const tokenB = "wrap.testnet";
const fee = 10000
const pool_ids = [getDCLPoolId(tokenA, tokenB, fee)];
const tokenAMetadata = await ftGetTokenMetadata(tokenA)
const tokenBMetadata = await ftGetTokenMetadata(tokenB)
const res = await quote_by_output({
pool_ids,
output_amount: "0.1",
input_token: tokenAMetadata,
output_token: tokenBMetadata,
});
Response
{ amount: '490370', tag: null }
This function integrates Swap, SwapByOutput and LimitOrderWithSwap apis.
Parameters
interface SwapInfo {
tokenA: TokenMetadata;
tokenB: TokenMetadata;
amountA: string;
}
interface DCLSwapProps {
swapInfo: SwapInfo;
Swap?: {
pool_ids: string[];
min_output_amount: string;
};
SwapByOutput?: {
pool_ids: string[];
output_amount: string;
};
LimitOrderWithSwap?: {
pool_id: string;
output_amount: string;
};
SwapByStopPoint?: {
pool_id: string;
stop_point: number;
skip_unwrap_near: boolean;
};
AccountId: string;
}
Example (Swap)
const tokenA = "usdt.fakes.testnet";
const tokenB = "wrap.testnet";
const fee = 2000
const pool_ids = [getDCLPoolId(tokenA, tokenB, fee)];
const tokenAMetadata = await ftGetTokenMetadata(tokenA)
const tokenBMetadata = await ftGetTokenMetadata(tokenB)
const res = await DCLSwap({
swapInfo: {
amountA: input_amount,
tokenA: tokenAMetadata,
tokenB: tokenBMetadata,
},
Swap: {
min_output_amount: "0",
pool_ids,
},
AccountId,
});
Response (Swap)
[
{
receiverId: "usdt.fakes.testnet",
functionCalls: [
{
methodName: "ft_transfer_call",
args: {
receiver_id: "dcl.ref-dev.testnet",
amount: "1000000",
msg: '{"Swap":{"pool_ids":["usdt.fakes.testnet|wrap.testnet|2000"],"output_token":"wrap.testnet","min_output_amount":"0"}}',
},
gas: "180000000000000",
amount: "0.000000000000000000000001",
},
],
},
];
Example (SwapByOutput)
const tokenA = "usdt.fakes.testnet";
const tokenB = "wrap.testnet";
const fee = 2000
const tokenAMetadata = await ftGetTokenMetadata(tokenA)
const tokenBMetadata = await ftGetTokenMetadata(tokenB)
const pool_ids = [getDCLPoolId(tokenA, tokenB, fee)];
const res = await DCLSwap({
swapInfo: {
amountA: input_amount,
tokenA: tokenAMetadata,
tokenB: tokenBMetadata,
},
SwapByOutput: {
pool_ids,
output_amount: "4.89454792",
},
AccountId,
});
Response (SwapByOutput)
[
{
receiverId: "usdt.fakes.testnet",
functionCalls: [
{
methodName: "ft_transfer_call",
args: {
receiver_id: "dcl.ref-dev.testnet",
amount: "900000",
msg: '{"SwapByOutput":{"pool_ids":["usdt.fakes.testnet|wrap.testnet|2000"],"output_token":"wrap.testnet","output_amount":"4894547920000000000000000"}}',
},
gas: "180000000000000",
amount: "0.000000000000000000000001",
},
],
},
];
Example (LimitOrderWithSwap)
const tokenA = "usdt.fakes.testnet";
const tokenB = "wrap.testnet";
const fee = 2000
const pool_ids = [getDCLPoolId(tokenA, tokenB, fee)];
const tokenAMetadata = await ftGetTokenMetadata(tokenA)
const tokenBMetadata = await ftGetTokenMetadata(tokenB)
const res = await DCLSwap({
swapInfo: {
amountA: input_amount,
tokenA: tokenAMetadata,
tokenB: tokenBMetadata,
},
LimitOrderWithSwap: {
pool_id,
output_amount: "3217.929",
},
AccountId,
});
Response (LimitOrderWithSwap)
[
{
receiverId: "usdt.fakes.testnet",
functionCalls: [
{
methodName: "ft_transfer_call",
args: {
receiver_id: "dcl.ref-dev.testnet",
amount: "1000000",
msg: '{"LimitOrderWithSwap":{"pool_id":"usdt.fakes.testnet|wrap.testnet|2000","buy_token":"wrap.testnet","point":495240}}',
},
gas: "180000000000000",
amount: "0.000000000000000000000001",
},
],
},
];
Example (SwapByStopPoint)
const tokenA = "usdt.fakes.testnet";
const tokenB = "wrap.testnet";
const fee = 2000
const pool_ids = [getDCLPoolId(tokenA, tokenB, fee)];
const tokenAMetadata = await ftGetTokenMetadata(tokenA)
const tokenBMetadata = await ftGetTokenMetadata(tokenB)
const res = await DCLSwap({
swapInfo: {
amountA: input_amount,
tokenA: tokenAMetadata,
tokenB: tokenBMetadata,
},
SwapByStopPoint: {
pool_id: pool_id,
stop_point: 405920,
},
AccountId,
});
Response (SwapByStopPoint)
[
{
receiverId: "usdt.fakes.testnet",
functionCalls: [
{
methodName: "ft_transfer_call",
args: {
receiver_id: "dcl.ref-dev.testnet",
amount: "1000000",
msg: '{"SwapByStopPoint":{"pool_id":"usdt.fakes.testnet|wrap.testnet|2000","stop_point":495240}}',
},
gas: "180000000000000",
amount: "0.000000000000000000000001",
},
],
},
];
This function helps to swap on best price pool of at most 4 candidate pools based on tokenA, tokenB, amountA (input amount) and slippageTolerance.
Parameters
{
tokenA: TokenMetadata;
tokenB: TokenMetadata;
amountA: string;
slippageTolerance: number;
AccountId: string;
}
Example
const tokenA = "usdt.fakes.testnet";
const tokenB = "wrap.testnet";
const tokenAMetadata = await ftGetTokenMetadata(tokenA)
const tokenBMetadata = await ftGetTokenMetadata(tokenB)
const res = await DCLSwapByInputOnBestPool({
tokenA:tokenAMetadata,
tokenB:tokenBMetadata,
amountA: "1",
slippageTolerance: 0.1,
AccountId,
});
Response
[
{
receiverId: "usdt.fakes.testnet",
functionCalls: [
{
methodName: "ft_transfer_call",
args: {
receiver_id: "dcl.ref-dev.testnet",
amount: "1000000",
msg: '{"Swap":{"pool_ids":["usdt.fakes.testnet|wrap.testnet|10000"],"output_token":"wrap.testnet","min_output_amount":"203606350172806050000000"}}',
},
gas: "180000000000000",
amount: "0.000000000000000000000001",
},
],
},
];
interface UserOrderInfo {
order_id: string;
owner_id: string;
pool_id: string;
point: number;
sell_token: string;
created_at: string; // timestamp when this order created
original_amount: string; // original amount of sell_token
remain_amount: string; // remain amount to be swapped, 0 means a history order
cancel_amount: string; // amount after cancel an active order
original_deposit_amount: string; // the input amount of LimitOrderWithSwap through ft_transfer_call, maybe partially into instant Swap
swap_earn_amount: string; // earn token amount through swap before actual place order
buy_token: string;
unclaimed_amount: string;
bought_amount: string; // accumalated amount you get
}
Get your active orders
Parameters
(AccountId: string)
Example
const res = await list_active_orders(AccountId)
Response
[
{
order_id: "usdt.fakes.testnet|wrap.testnet|10000#93",
owner_id: "your-account-id.testnet",
pool_id: "usdt.fakes.testnet|wrap.testnet|10000",
point: 398600,
sell_token: "wrap.testnet",
buy_token: "usdt.fakes.testnet",
original_deposit_amount: "1000000000000000000000000",
swap_earn_amount: "0",
original_amount: "1000000000000000000000000",
cancel_amount: "0",
created_at: "1667292669983952215",
remain_amount: "1000000000000000000000000",
bought_amount: "0",
unclaimed_amount: "0",
},
];
Get your history orders
Parameters
(AccountId: string)
Example
const res = await list_history_orders(AccountId)
Response
[
{
order_id: "usdc.fakes.testnet|wrap.testnet|2000#47",
owner_id: "juaner.testnet",
pool_id: "usdc.fakes.testnet|wrap.testnet|2000",
point: 399120,
sell_token: "wrap.testnet",
buy_token: "usdc.fakes.testnet",
original_deposit_amount: "1000000000000000000000000",
swap_earn_amount: "0",
original_amount: "1000000000000000000000000",
cancel_amount: "1000000000000000000000000",
created_at: "1665928620632469264",
remain_amount: "0",
bought_amount: "0",
unclaimed_amount: null,
},
];
cancel an active order
Parameters
(order_id: string)
Example
const res = await cancel_order("usdt.fakes.testnet|wrap.testnet|10000#93")
Response
[
{
receiverId: "dcl.ref-dev.testnet",
functionCalls: [
{
methodName: "cancel_order",
args: {
order_id: "usdt.fakes.testnet|wrap.testnet|10000#93",
amount: "1000000000000000000000000",
},
gas: "180000000000000",
},
],
},
];
Claim your unclaimed_amount in the order.
Parameters
(order_id: string)
Example
const res = await claim_order("usdt.fakes.testnet|wrap.testnet|10000#93")
Response
[
{
receiverId: "dcl.ref-dev.testnet",
functionCalls: [
{
methodName: "cancel_order",
args: {
order_id: "usdt.fakes.testnet|wrap.testnet|10000#93",
amount: "0",
},
gas: "180000000000000",
},
],
},
];
Get order information by order_id
Parameters
(order_id: string)
Example
const res = await get_order("usdt.fakes.testnet|wrap.testnet|10000#93")
Response
{
order_id: 'usdt.fakes.testnet|wrap.testnet|10000#93',
owner_id: 'juaner.testnet',
pool_id: 'usdt.fakes.testnet|wrap.testnet|10000',
point: 398600,
sell_token: 'wrap.testnet',
buy_token: 'usdt.fakes.testnet',
original_deposit_amount: '1000000000000000000000000',
swap_earn_amount: '0',
original_amount: '1000000000000000000000000',
cancel_amount: '0',
created_at: '1667292669983952215',
remain_amount: '1000000000000000000000000',
bought_amount: '0',
unclaimed_amount: '0'
}
Get user assets.
Parameters
(AccountId: string)
Example
const res = await list_user_assets("your-account-id.testnet")
Response
{
'meta-v2.pool.testnet': '1000000000000000000000000',
'ref.fakes.testnet': '54795238623455655224444',
'usdc.fakes.testnet': '204436562555',
'eth.fakes.testnet': '112348196732799990900',
'usdt.fakes.testnet': '164044235810',
'wrap.testnet': '1004944616890200800000000'
}
Get point based on input price
Parameters
{
tokenA: TokenMetadata;
tokenB: TokenMetadata;
amountA: string;
amountB: string;
fee: number;
}
Example
const tokenA = await ftGetTokenMetadata("usdt.fakes.testnet");
const tokenB = await ftGetTokenMetadata("wrap.testnet");
const amountA = "0.9";
const amountB = "4.89454792";
const fee = 400;
const res = priceToPoint({
tokenA,
tokenB,
amountA,
amountB,
fee,
});
Response
431416
Get price from tokenA to tokenB based on point
Parameters
{
tokenA: TokenMetadata;
tokenB: TokenMetadata;
point: number;
}
Example
const tokenA = await ftGetTokenMetadata("usdt.fakes.testnet");
const tokenB = await ftGetTokenMetadata("wrap.testnet");
const res = pointToPrice({
tokenA,
tokenB,
point: 431416,
});
Response
5.43528191708623
FAQs
This SDK is designed to assist developers when interacting with the main functions of the protocol. Main functions that can be defined as:
The npm package kinok-ref-sdk receives a total of 1 weekly downloads. As such, kinok-ref-sdk popularity was classified as not popular.
We found that kinok-ref-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.