tronsave-sdk
Version:
TypeScript SDK for Tronsave API to manage TRON blockchain resources
380 lines (323 loc) • 9.25 kB
Markdown
# 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](https://docs.tronsave.io/), 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
```bash
npm install tronsave-sdk
```
#### Or
```bash
yarn add tronsave-sdk
```
## SDK Initialization
```typescript
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](https://docs.tronsave.io/developer/get-api-key)
## 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:
```typescript
// 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**
```typescript
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
```typescript
const result = await sdk.buyResource(
{
receiver: "TRx...Jhd",
resourceType: "ENERGY",
unitPrice: 65,
durationSec: 3600,
resourceAmount: 32000,
signedTx // Signed transaction data
}
);
```
```typescript
/*
Example return
{
orderId: "67ce9ea9dedec5c48fa2e058"
}
*/
```
### 3. Get Extendable Delegates
Get list of extendable delegates
```typescript
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
```typescript
const extendResult = await sdk.extendRequest({
receiver: "TRx...Jhd",
extendData: [{
delegator: "TRx...Jfv",
extendTo: 1715222400,
isExtend: true,
extraAmount: 0,
}]
});
```
* Using **signedTx**
```typescript
const extendResult = await sdk.extendRequest({
receiver: "TRx...Jhd",
extendData: [{
delegator: "TRx...Jfv",
extendTo: 1715222400,
isExtend: true,
extraAmount: 0,
}],
signedTx // Signed transaction data
});
```
```typescript
/*
Example return
{
orderId: "67ce9ea9dedec5c48fa2e058"
}
*/
```
### 5. Get User Info
> - API key is required
Get internal account information using API key
```typescript
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
```typescript
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
```typescript
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