API Functions

Common Use Cases

TRC Token/TRX Trades

Suppose you wish to purchase TRC tokens using the TRX balance from your TRX wallet. The standard procedure for performing this trade would be to perform the token exchange, sign the transaction, and broadcast the transaction. Since the outputs of performing the token exchange and signing the transaction are JSON files, it makes sense to write a script to handle the trading process.

The following JavaScript example is a simple program which performs the trade:

  1. Define tronWeb object to allow for connection to TronGrid.
  2. Define the parameter object, composed of the exchange ID, token name, quantity of TRX sold, expected Token amount at the exchange rate, and private key.
  3. Define a function for performing the trade. This function takes in the parameters, performs the exchange, signs the transaction, and broadcasts the transaction to the TRON network.
  4. Execute the function.
const TronWeb = require('tronweb');
const HttpProvider = TronWeb.providers.HttpProvider;
const fullNode = new HttpProvider('https://api.trongrid.io');
const solidityNode = new HttpProvider('https://api.trongrid.io');
const eventServer = 'https://api.trongrid.io';
const privateKey = 'Your Private Key Here';

// Create tronWeb object defining Node addresses
const tronWeb = new TronWeb(
    fullNode,
    solidityNode,
    eventServer,
    privateKey,
);

// Create param object that defines all the API input parameters
const param = {
  exchangeID:5,          //Exchange ID Number
  tokenName:"_",         //Token name for TRX
  sold:100000000,        //TRX amount sold. Must be in SUN denomination.
  expected:1,            //Assigned as 1 to keep wide limit, like market order
  privKey:'Your Private Key Here',
}

async function trade(param){
  try {
    // Performs the trade between Token and TRX
    const tradeobj = await tronWeb.transactionBuilder.tradeExchangeTokens(exchangeID = param.exchangeID,
    tokenName = param.tokenName,
    tokenAmountSold = param.sold,
    tokenAmountExpected = param.expected,
    ownerAddress = "Your TRX Wallet Address Here - in Hex String");

    // Signing the transaction
    const signedtxn = await tronWeb.trx.sign(tradeobj, param.privKey);

    // Broadcasting the transaction
    const receipt = await tronWeb.trx.sendRawTransaction(signedtxn);
    console.log(receipt)
  }
  catch(err) {
    console.log(err);
  };
};

trade(param); // Execute the function

📘

Note about Market Slippage

In the tradeExchangeTokens API, tokenAmountExpected is a key body parameter. This parameter works similarly to a Stop-Limit in many centralized exchanges.

Example: Assume you have a function calculating the expected amount of TRC tokens to receive, given the Token/TRX ratio. You feed this expected amount as an input parameter into the tradeExchangeTokens API function. However, the API call may fail for two reasons:

  1. Price slippage occurs during the trade process, pushing the exchange ratio higher, thus reducing the amount of TRC tokens you would actually receive to be below your expected amount.

  2. Buying large amounts of the TRC token relative to the TRC token balance. This action drives the exchange ratio up, reducing the amount of TRC tokens you would actually receive to be below your expected amount.

To circumvent these issues, you may try setting the expected value to always be a percentage lower than the calculated expected. However, recognize that setting very low expected values to force a successful trade, also opens you up to purchasing tokens at potentially high prices.