TronsaveSDK

TronsaveSDK is a TypeScript library that helps you easily interact with the Tronsave API to manage resources (ENERGY/BANDWIDTH) on the TRON blockchain. This SDK provides robust, strongly-typed functions and can be integrated into modern backend systems.

You can also directly interact with the Tronsave API using the comprehensive documentation available at documentation, which provides detailed API endpoints, authentication methods, and integration examples for both REST API.

Key Features

• Buy resources (Buy Resource)
• Estimate resource purchase cost (Estimate Buy Resource)
• Extend resource requests (Extend Request)
• Get list of extendable delegates (Get Extendable Delegates)
• Fetch user information (Get User Info)
• Fetch order details (Get Order, Get Orders)
• Get order book (Get Order Book)

Installation

npm install tronsave-sdk

Or

yarn add tronsave-sdk

SDK Initialization

import { TronsaveSDK, SDKConfig } from 'tronsave-sdk';

const config: SDKConfig = {
  network: 'mainnet', // or 'testnet'
  apiKey: 'YOUR_API_KEY', // if available
};

const sdk = new TronsaveSDK(config);

Notes:

• network (Optional): "mainnet" or "testnet". Default is "mainnet". Currently, we use Nile network for testnet.
• apiKey (Optional): If no API key is provided, you will only be able to use a limited set of functions. How to get API key Read here

Usage Examples

1. Estimate Buy Resource

Before making any resource purchases, you can leverage the estimateBuyResource function to get real-time market insights. This powerful feature allows you to:

• Check current available resource amounts in the market
• Get accurate price estimates for your desired resource quantity
• Verify if your requested amount can be fulfilled
• Calculate the total TRX cost before committing to a purchase

Here's a quick example of how to use it:

// Example: Estimate cost for 32,000 ENERGY units for 1 hour
const estimate = await sdk.estimateBuyResource(
  {
    receiver: "TRx...Jhd",
    resourceType: "ENERGY",
    durationSec: 3600, // 1 hour
    resourceAmount: 32000
  }
);
/*
Example return
{
    unitPrice: 64, // Current unit price
    durationSec: 3600, // Duration in seconds
    estimateTrx: 6144000, // Estimated TRX cost
    availableResource: 32000 // Available resource amount
}
*/

2. Buy Resource

• If no API key is provided, you must use signedTx for payment.
• If both API key and signedTx are present, the API key will always be prioritized for payment.

• Using API Key

const result = await sdk.buyResource(
  {
    receiver: "TRx...Jhd",
    resourceType: "ENERGY",
    durationSec: 3600,
    resourceAmount: 32000,
  },
);

• Using signedTx

Note: When using signedTx, unitPrice must be specified as a number in sun

const result = await sdk.buyResource(
  {
    receiver: "TRx...Jhd",
    resourceType: "ENERGY",
    unitPrice: 65,
    durationSec: 3600,
    resourceAmount: 32000,
    signedTx // Signed transaction data 
  }
);

/*
Example return
{
  orderId: "67ce9ea9dedec5c48fa2e058"
}
*/

3. Get Extendable Delegates

Get list of extendable delegates

const delegates = await sdk.getExtendableDelegates({
  receiver: "TRx...Jhd",
  extendTo: 1715222400, // Target extension time (Unix timestamp)
  resourceType: "ENERGY", // Optional: "ENERGY" or "BANDWIDTH", default is "ENERGY"
  maxPriceAccepted: 100, // Optional: Maximum acceptable price
});

/*
Response will be in this format:
{
  extendOrderBook: [
    { price: 50, value: 10000 },  // Price and extendable amount
    { price: 55, value: 20000 },
    { price: 60, value: 15000 }
  ],
  totalDelegateAmount: 45000,     // Total delegated amount
  totalAvailableExtendAmount: 45000, // Total amount available for extension
  totalEstimateTrx: 2250000,      // Estimated total TRX needed
  yourBalance: 3000000,           // Your TRX balance
  isAbleToExtend: true,           // Whether extension is possible
  extendData: [                   // Extension data
    {
      delegator: "TRx...Jfv",     // Delegator address
      extendTo: 1715222400,       // Extension target time
      isExtend: true,             // Whether to extend
      extraAmount: 0              // Additional amount
    }
  ]
}
*/

4. Extend Request

• If no API key is provided, you must use signedTx for payment.
• If both API key and signedTx are present, the API key will always be prioritized for payment.

Use extendData from the getExtendableDelegates result

• Using API key

const extendResult = await sdk.extendRequest({
  receiver: "TRx...Jhd",
  extendData: [{
    delegator: "TRx...Jfv",
    extendTo: 1715222400,
    isExtend: true,
    extraAmount: 0,
  }]
});

• Using signedTx

const extendResult = await sdk.extendRequest({
  receiver: "TRx...Jhd",
  extendData: [{
    delegator: "TRx...Jfv",
    extendTo: 1715222400,
    isExtend: true,
    extraAmount: 0,
  }],
  signedTx // Signed transaction data
});

/*
Example return
{
  orderId: "67ce9ea9dedec5c48fa2e058"
}
*/

5. Get User Info

• API key is required

Get internal account information using API key

const userInfo = await sdk.getUserInfo();

/*
Example return
{
  id: 'TRx...Jhd',
  balance: '965023747',
  representAddress: 'TRx...Jhd',
  depositAddress: 'TRx...Jfv'
}
*/

6. Get Order Details

• API key is required

Get order detail by orderId

const order = await sdk.getOrder("67ce9ea9dedec5c48fa2e058");

/* Example return
{
  id: "67ce9ea9dedec5c48fa2e058",
  requester: "TRx...Jhd",
  receiver: "TRx...Jfv",
  resourceAmount: 40000,
  resourceType: "ENERGY",
  remainAmount: 0,
  orderType: "NORMAL",
  price: 81.5,
  durationSec: 900,
  allowPartialFill: false,
  payoutAmount: 3260000,
  fulfilledPercent: 100,
  smartMatching: {
          autoBuyMoreMaximumDurationPercent: 33,
          totalSmartMatchingOrderCount: 2,
          totalSmartMatchingOrderAmount: 662943,
          totalRefundSmartMatchingAmount: 32629226
      },
      delegates: [
          {
              delegator: "TRx...Jhd",
              amount: 40000,
              txid: "19be98d0183b29575d74999a93154b09b3c7d05051cdbd52c667cd9f0b3cc9b0",
              extendInfo: {
                  extraAmount: 300018,
                  extendAmount: 0,
                  extendDuration: 0,
                  buyAmountDuration: 29581,
                  extendPrice: 78.75,
                  extraBuyPrice: 78.75,
                  extendTo: 1753187265,
                  oldDelegatedResourceInSun: 4416700000,
                  oldExpiredAt: 1753187262
              },
              smartMatchingInfo: {
                  refundAmount: 14766511
              }
          }
      ]
}
*/

// Get orders history
const orders = await sdk.getOrders(1, 10); // page, limit

/*
Example return
{
  total: 3,
  data: [
  {
      id: "67ce9ea9dedec5c48fa2e058",
      requester: "TRx...Jhd",
      receiver: "TRx...Jfv",
      resourceAmount: 40000,
      resourceType: "ENERGY",
      remainAmount: 0,
      orderType: "NORMAL",
      price: 81.5,
      durationSec: 900,
      allowPartialFill: false,
      payoutAmount: 3260000,
      fulfilledPercent: 100,
      smartMatching: {
          autoBuyMoreMaximumDurationPercent: 33,
          totalSmartMatchingOrderCount: 2,
          totalSmartMatchingOrderAmount: 662943,
          totalRefundSmartMatchingAmount: 32629226
      },
      delegates: [
          {
              delegator: "TRx...Jhd",
              amount: 40000,
              txid: "19be98d0183b29575d74999a93154b09b3c7d05051cdbd52c667cd9f0b3cc9b0",
              extendInfo: {
                  extraAmount: 300018,
                  extendAmount: 0,
                  extendDuration: 0,
                  buyAmountDuration: 29581,
                  extendPrice: 78.75,
                  extraBuyPrice: 78.75,
                  extendTo: 1753187265,
                  oldDelegatedResourceInSun: 4416700000,
                  oldExpiredAt: 1753187262
              },
              smartMatchingInfo: {
                  refundAmount: 14766511
              }
          }
      ]
  }
]
*/

7. Get Order Book

const orderBook = await sdk.getOrderBook({
  resourceType: 'ENERGY',
  address: 'TRx...Jhd'
});

/*
Example return
[
    {
        price: 52,
        availableResourceAmount: 643966
    },
    {
        price: 54,
        availableResourceAmount: 2004782
    },
    {
        price: 90,
        availableResourceAmount: 2829333
    }
]
*/

Strong Typing

The SDK uses clear interfaces/types for all parameters and return values, ensuring safe and easy development.

See more types in the src/types/ directory.

Contribution

All contributions are welcome! Please create a pull request or issue if you encounter a bug or want to suggest a new feature.

License

MIT