API
Note: the sample code uses Acala network assets as example.
Here we will list types and their representation in Typescript.
type CurrencyId {
TOKEN: string
}
Example:
const acaCurrencyId = { TOKEN: ‘ACA’ }
type TradingPair = [CurrencyId, CurrencyId]
Example:
const tradingPair = [{ TOKEN: ‘ACA’ }, { TOKEN: ‘AUSD’ }];
type TradingPairStatus = {
Enabled?: null,
NotEnabled?: null,
}
Indicates whether trading pair is enabled:
{ Enabled: null }
- enabled{ NotEnabled: null }
- not enabled
You can use
@acala-network/api
to get metadata description of available methods.
Setting up polkadot/api provider example: const provider = new WsProvider('<NODE_WS_ADDRESS>');
const api = new ApiPromise( options({ provider }) );
await api.isReady;
...
Full code snippet:
These functions just read information from the chain, and thus don’t require signing transactions with the private key. Read more about state queries here: State queries docs
Such parameters as tokens decimals, symbols, risk parameters and many more can be received from on-chain.
const properties = await api.rpc.system.properties();
const decimals = !result.tokenDecimals.isNone &&
result.tokenDecimals.value.toHuman();
const symbols = !result.tokenSymbol.isNone &&
result.tokenSymbol.value.toHuman();
...
Full code snippet:
Returns liquidity of the pool of currencies in Trading Pair
tokenA
and tokenB
.liquidityPool(tradingPair: TradingPair):
[Balance, Balance]
Arguments
Name | Type | Text |
---|---|---|
tradingPair | TradingPair | the tuple of CurrencyIds included in the desired liquidity pool |
Note: the order of CurrencyIds in the trading pair matters, if it’s wrong, two empty balance will be returned.
Example:
const liquidity = await api.query.dex.liquidityPool([
{ TOKEN: 'AUSD' },
{ TOKEN: 'ACA' },
]);
console.log(liquidity.map(t => t.toHuman()))
Full code snippet:
Provisioning Pool is the Pool in the stage of bootstrapping liquidity, when trading is yet allowed. You can read more about Bootstrap a Pools docs to find out more.
getProvisioningPoolBalance returns a tuple of balances for each of the tokens in the trading pair, depends on the amount of LP tokens that the account is holding
provisioningPool(tradingPair: TradingPair, accountId: string):
[Balance, Balance];
Name | Type | Text |
---|---|---|
tradingPair | TradingPair | the tuple of currency Ids in provisioning pair |
accountId | string | the account number balances for |
Example:
const liquidity = await api.query.dex.provisioningPool([
{ TOKEN: 'ACA' },
{ TOKEN: 'AUSD' }
],
't98jaBc3cdvZuQpBoiXpJW1uGsFhf9Gq6YDW4UmMtxdxZVL',
);
Full code snippet:
returns if a trading pair is enabled or not. Note that the order of tokens in trading pair is important
tradingPairStatuses(TradingPair): TradingPairStatus
Arguments
Name | Type | Text |
---|---|---|
tradingPair | TradingPair | the tuple of currency Ids in desired trading pair |
Example:
const status = await api.query.dex.tradingPairStatuses([
{ TOKEN: 'ACA' },
{ TOKEN: 'AUSD' }
]);
Full code snippet:
These transactions write data on-chain and require the private key to sign transactions.
There are different ways to create the signer to sign transactions, you can check them in polkadot api docs.
Here is an example deriving a
signer
from a seed phrase using Polkadot keyring:const keyring = new Keyring({
type: 'sr25519'
});
const signer = keyring.addFromMnemonic('<YOUR_SEED_PHRASE>');
Full code snippet:
swapWithExactSupply(path: CurrencyId[], supply_amount: number, min_target_amount: number): Extrinsic
Swaps an exact amount of token A
supply_amount
to a minimum amount of token B
min_target_amount
.The slippage of the deal =
supply_amount / min_target_amount
The current exchange ratio of the Liquidity Pool =
token_A_liquidity / token_B_liquidity
.Returns
Extrinsic
type that should be signed with the private key.Arguments
Name | Type | Text |
---|---|---|
path | CurrencyId[] | an array of CurrencyIds. The first currency in the path array will be exchanged for the last one. If tokens you want to swap don’t have one pool, the path should contain an intermediate token with which each of the tokens has a pool, and etc. |
supply_amount | number | exact supply that will be charged if the swap is successful |
min_target_amount | number | minimum amount to receive if the swap is successful. Changing this amount will define the slippage. |
Example
const path = [
{ TOKEN: "ACA", },
{ TOKEN: "AUSD", },
]
// minTargetAmount is "0x0" which means that slippage is 100%
const minTargetAmount = "0x0";
const supplyAmount = <AMOUNT_DENORMALISED>;
const extrinsic = api.tx.dex.swapWithExactSupply(
path,
supplyAmount,
minTargetAmount
);
const hash = await extrinsic.signAndSend(signer);
console.log('hash', hash.toHuman());
Notethe supply amount should be denormalised with ACA decimals for this example
Full code snippet:
swapWithExactTarget(path: CurrencyId[], target_amount: number, max_supply_amount: number): Extrinsic
Swaps a certain amount of supply tokens A to get an exact amount of tokens B. If the current ratio of tokens in the pool doesn’t need more supply tokens than mentioned, the transaction will fail.
The slippage of the deal is defined as such:
max_supply_amount / target_amount
The current exchange ratio of the Liquidity Pool =
token_A_liquidity / token_B_liquidity
Returns
Extrinsic
type that should be signed with the private key.Arguments
Name | Type | Text |
---|---|---|
path | CurrencyId[] | An array of CurrencyIds. The first currency in the path array will be exchanged for the last one. If tokens you want to swap don’t have one pool, the path should contain an intermediate token with which each of the tokens has a pool, and etc. |
target_amount | number | exact target amount that will be received if the swap is successful |
max_supply_amount | number | The maximum amount that is allowed to spend to get the exact target amount. Variating this argument will define the slippage. |
Example:
const targetAmount = <DENORMALISED_EXACT_AMOUNT>;
const path = [
{ TOKEN: "ACA", },
{ TOKEN: "AUSD", },
]
const maxSupplyAmount = <DENORMALISED_MAX_AMOUNT>;
const extrinsic = api.tx.dex.swapWithExactTarget(
path,
targetAmount,
maxSupplyAmount,
);
const hash = await extrinsic.signAndSend(signer);
Full code snippet:
addLiquidity(
currency_id_a: CurrencyId,
currency_id_b: CurrencyId,
max_amount_a: number,
max_amount_b: number,
min_share_increment: number,
stake_increment_share: boolean
): Extrinsic
Adds liquidity to the pool of trading pairs
currency_id_a
and currency_id_b
. The operation will be successful only in case if the token pair is enabled.You can set the maximum amounts
max_amount_a
and max_amount_b.
If the ratio of them you provided is not aligned with the current pool ratio, one of the tokens will be charged as max amount, and another adjusted based on the current pool ratio.min_share_increment
defines the minimum amount of LP-tokens to receive. This to some degree provides a protective ceiling for potential exploits e.g. front-running.Returns
Extrinsic
type that should be signed with the private key.For example current pool ratio is 0.5 which means that amount of token A in the pool is twice less that token B. If you provide 100max_amount_a
and 100max_amount_b
, you will add liquidity with 100 Token B and only 50 Token A regarding the currenct pool ratio.
Arguments
Name | Type | Text |
---|---|---|
currency_id_a | CurrencyId | the first currency of trading pair to provide liquidity to |
currency_id_b | CurrencyId | second currency of trading pair to provide liquidity to |
max_amount_a | number | the denormalized maximum amount of token A in trading pair |
max_amount_b | number | the denormalized maximum amount of token B in traning pair |
min_share_increment | number | the minimum amount of LP tokens you will be received. |
stake_increment_share | boolean | if true it automatically stakes all shares |
Example
const currency_id_a = { TOKEN: 'ACA' };
const currency_id_b = { TOKEN: 'AUSD' };
const max_amount_a = 2 * 10 ** symbolsDecimals["ACA"];
const max_amount_b = 2 * 10 ** symbolsDecimals["AUSD"];
// slippage is 100% for receiving shares
const min_share_increment = 0;
const stake_increment_share = true
const extrinsic = api.tx.dex.addLiquidity(
currency_id_a,
currency_id_b,
max_amount_a,
max_amount_b,
min_share_increment,
stake_increment_share,
);
const hash = await extrinsic.signAndSend(signer);
Ensure you have positive balance of each of the tokens in the pair and that the pair is available
removeLiquidity(
currency_id_a: CurrencyId,
currency_id_b: CurrencyId,
remove_share: number,
min_withdrawn_a: number,
min_withdrawn_b: number,
by_unstake: boolean
): Extrinsic
Removes liquidity from selected trading pair. It can, also, automatically unstake all LP tokens and withdraw them. This call merges/batches the two transactions into one and requires only one fee.
min_withdrawn_
specifies the minimum amount of token A you want to receive.Arguments
Name | Type | Text |
---|---|---|
currency_id_a | CurrencyId | the first currency of trading pair to provide liquidity to |
currency_id_b | CurrencyId | second currency of trading pair to provide liquidity to |
remove_share | number | amount of shares to remove liquidity |
min_withdrawn_a | number | the minimum amount of tokens A from the trading pair you want to receive for the specified amount of shares, if the current ratio doesn’t have it, the transaction will fail |
min_withdrawn_B | number | the minimum amount of tokens B you want to receive for the specified amount of shares, if the currenct ratio doesn’t have it, the transaction will fail |
by_unstake | boolean | if true it will unstake the specified amount of LP-shares and withdraw them. If false it will only withdraw unstaked LP tokens |
Example
const currency_id_a = { TOKEN: 'ACA' };
const currency_id_b = { TOKEN: 'DOT' };
// amount of shares to remove
const remove_share = 1;
// slippage for ACA is 100%, we want to receive anything that liquidity pool ratio will offer
const min_withdrawn_a = 0;
// slippage for DOT is 100%, we want to receive anything that liquidity pool ratio will offer
const min_withdrawn_b = 0;
const by_unstake = true;
const extrinsic = api.tx.dex.removeLiquidity(
currency_id_a,
currency_id_b,
remove_share,
min_withdrawn_a,
min_withdrawn_b,
by_unstake
);
Last modified 1yr ago