Create Order

Create an Energy or Bandwidth purchase order with an API key, paid from your TronSave internal account, and receive an orderId to track its status.

Create an Energy or Bandwidth purchase order using an API key. The order is paid from your prefunded internal account, so no per-order on-chain signing is required. On success the endpoint returns an orderId you can use to track the order status.

POST https://api.tronsave.io/v2/buy-resource

Rate limit: 15 requests per 1 second.

Headers

Name

Type

Description

apikey*

String

TronSave API key tied to your internal account. See Authentication to get your API key.

_*_Required.

Request body

Field

Type

Description

resourceType

String

"ENERGY" or "BANDWIDTH". Default: ENERGY.

unitPrice

Number, String

"FAST", "MEDIUM", "SLOW", or a number. Default: "MEDIUM".

- FAST: If the market is ready to fill = 100%, FAST = MEDIUM. If the market is ready to fill < 100%, FAST = MEDIUM + 10. If market ready to fill = 0%, FAST = SLOW + 20.

- MEDIUM: The lowest price for the maximum market fill for this order. If market is ready to fill = 0%, MEDIUM = SLOW + 10.

- SLOW: The lowest price that can be set for this order.

- If the price is a number, the price unit is SUN.

resourceAmount*

Number

The number of resources.

receiver*

String

Resource receiving address.

durationSec

Number

The duration of the bought resource, in seconds. Default: 259200 (3 days).

sponsor

String

Sponsor code.

options

Object

Optional.

options.allowPartialFill

Boolean

Allow the order to be filled partially or not.

options.onlyCreateWhenFulfilled

Boolean

true => order only creates when it can be fulfilled.

false => order will create even if it cannot be fulfilled.

Default value: false.

options.maxPriceAccepted

Number

Only create the order when the estimated price is less than this value.

options.preventDuplicateIncompleteOrders

Boolean

true => only create if no uncompleted order with the same parameters exists.

false => always create a new order, regardless of existing unfinished ones.

Default value: false.

options.minResourceDelegateRequiredAmount

Number

The minimum resource amount delegated by a single provider.

_*_Required.

Request body example

{
    "resourceType": "ENERGY",
    "receiver": "TFFbwz3UpmgaPT4UudwsxbiJf63t777777",
    "durationSec": 3600,
    "resourceAmount": 32000,
    "unitPrice": "MEDIUM",
    "options": {
        "allowPartialFill": true,
        "onlyCreateWhenFulfilled": true,
        "preventDuplicateIncompleteOrders": false,
        "maxPriceAccepted": 100,
        "minResourceDelegateRequiredAmount": 100000
    }
}

Responses

Returns the order ID on success.

{
    "error": false,
    "message": "Success",
    "data": {
        "orderId": "6818426a65fa8ea36d119d2c"
    }
}

{
    "MISSING_PARAMS": "Missing some params in body",
    "INVALID_PARAMS": "Some params are invalid",
    "MIN_PRICE_INVALID": "minPrice is less than the system's minimum price or not in the correct format.",
    "INTERNAL_ACCOUNT_NOT_FOUND": "internal account does not exist",
    "INTERNAL_BALANCE_ACCOUNT_TOO_LOW": "Balance is not enough",
    "CANNOT_FULFILLED": "The order requires an immediate full match, but the system cannot fulfill 100% of it.",
    "MUST_BE_WAIT_PREVIOUS_ORDER_FILLED": "A pending order with the same parameters already exists in the system.",
    "PRICE_EXCEED_MAX_PRICE_REQUIRED": "The price of the order exceeds the maximum price accepted."
}

Request examples

curl -X POST "https://api.tronsave.io/v2/buy-resource" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "ENERGY",
    "receiver": "YOUR_TRON_ADDRESS",
    "durationSec": 3600,
    "resourceAmount": 32000,
    "unitPrice": "MEDIUM",
    "options": {
      "allowPartialFill": true,
      "onlyCreateWhenFulfilled": false,
      "maxPriceAccepted": 100
    }
  }'

const buyResource = async () => {
  const url = "https://api.tronsave.io/v2/buy-resource";
  const body = {
    resourceType: "ENERGY",
    unitPrice: "MEDIUM", // price in SUN, or "SLOW" | "MEDIUM" | "FAST"
    resourceAmount: 32000, // amount of resource to buy
    receiver: "YOUR_TRON_ADDRESS",
    durationSec: 3600, // order duration in seconds. Default: 259200 (3 days)
    options: {
      allowPartialFill: true,
      onlyCreateWhenFulfilled: false,
      maxPriceAccepted: 100,
    },
  };

  const res = await fetch(url, {
    method: "POST",
    headers: {
      apikey: "YOUR_API_KEY",
      "content-type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const response = await res.json();
  // {
  //   "error": false,
  //   "message": "Success",
  //   "data": { "orderId": "6818426a65fa8ea36d119d2c" }
  // }
  return response;
};

import requests

url = "https://api.tronsave.io/v2/buy-resource"
headers = {
    "apikey": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
body = {
    "resourceType": "ENERGY",
    "unitPrice": "MEDIUM",  # price in SUN, or "SLOW" | "MEDIUM" | "FAST"
    "resourceAmount": 32000,
    "receiver": "YOUR_TRON_ADDRESS",
    "durationSec": 3600,
    "options": {
        "allowPartialFill": True,
        "onlyCreateWhenFulfilled": False,
        "maxPriceAccepted": 100,
    },
}

response = requests.post(url, headers=headers, json=body)
print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CreateOrder {
    public static void main(String[] args) throws Exception {
        String url = "https://api.tronsave.io/v2/buy-resource";
        String body = """
            {
              "resourceType": "ENERGY",
              "unitPrice": "MEDIUM",
              "resourceAmount": 32000,
              "receiver": "YOUR_TRON_ADDRESS",
              "durationSec": 3600,
              "options": {
                "allowPartialFill": true,
                "onlyCreateWhenFulfilled": false,
                "maxPriceAccepted": 100
              }
            }
            """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("apikey", "YOUR_API_KEY")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.tronsave.io/v2/buy-resource"
	body := []byte(`{
		"resourceType": "ENERGY",
		"unitPrice": "MEDIUM",
		"resourceAmount": 32000,
		"receiver": "YOUR_TRON_ADDRESS",
		"durationSec": 3600,
		"options": {
			"allowPartialFill": true,
			"onlyCreateWhenFulfilled": false,
			"maxPriceAccepted": 100
		}
	}`)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
	req.Header.Set("apikey", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}

use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let url = "https://api.tronsave.io/v2/buy-resource";
    let body = json!({
        "resourceType": "ENERGY",
        "unitPrice": "MEDIUM",
        "resourceAmount": 32000,
        "receiver": "YOUR_TRON_ADDRESS",
        "durationSec": 3600,
        "options": {
            "allowPartialFill": true,
            "onlyCreateWhenFulfilled": false,
            "maxPriceAccepted": 100
        }
    });

    let client = reqwest::blocking::Client::new();
    let response = client
        .post(url)
        .header("apikey", "YOUR_API_KEY")
        .header("Content-Type", "application/json")
        .json(&body)
        .send()?;

    println!("{}", response.text()?);
    Ok(())
}

To integrate with the TRON Nile Testnet, replace the base URL with https://api-dev.tronsave.io.

Next steps

Track an order with Get Order Details.
Preview cost first with Estimate TRX.
Review the Order Types before placing orders.

PreviousEstimate TRX NextGet Order Details

Last updated 3 days ago