API documentation

Energy buying procedure

To buy energy, you need to register in the EnergyFather service, grab the authorization token from the page "Buyer > API tokens", and top up the Buyer account balance.

After creating an order (method ‘buy/energy’) energy can be delivered with a delay of several seconds or even minutes, so when developing automated systems it is recommended to periodically check the order execution by requesting method ‘order/get/{guid}’.

For example, if you are planning to send USDT and wish to make transactions cheaper by purchasing energy, you do the following:

• request the ‘buy/energy’ method to estimate needed energy amount and buy it,
• periodically request ‘order/get/{guid}’ method until energy is delegated (usually it takes a few seconds),
• send USDT (the purchased energy will be used to pay the transaction fee).

General notes

In this documentation, an expression wrapped into curly braces like ‘{guid}’ or ‘{id}’ means the value of the corresponding variable:

• ‘{guid}’ is the global unique identifier of the object in EnergyFather (usually 8 digits),
• ‘{id}’ is the sequential number of the object for this user (numbering starts with ‘1’ for each user).

API End-point

https://panel.energyfather.com/api/v1/private

Do send requests using the POST method.

Authorization of requests

To confirm (authorize) requests to a private API, a HTTP header should be passed:

Token: {token}

Management of authorization tokens is located in the control panel, on the page "Buyer > API tokens".

For example, you can get information about order 123456 in the following way:

CURL -X POST 'https://panel.energyfather.com/api/v1/private/order/get/123456' 
-H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

Order status

• "0" - Pending. The order has just been created.
• "1" - Awaiting the payment. The payment link has already been generated, EnergyFather is waiting for a callback from the payment system. This status is not used if the order is paid entirely by funds available at the internal account.
• "2" - Procedure of energy delegation is ongoing.
• "3" - Delegated. Energy is given out.
• "4" - Reclaimed (Undelegated). Energy is withdrawn due to the end of the paid time period.
• "5" - Paid. The order is paid and added into the queue for energy delivery.
• "6" - Error.

The usual sequence of statuses: 0, 5, 2, 3, 4.

The "buy/energy" method – buy energy (paid from internal account)

Request to buy energy by a registered customer with debit from the internal account. The energy is immediately sent to the specified address.

If the internal account has insufficient funds, the order will be created and instantly got status "6" (Error). In this case you need to visit the panel, deposit some funds and then send a new API request for energy buying.

There are two ways to define the amount of energy to be purchased:

a) You may set the exact energy amount in the "amount" parameter, then you should also set amount_source="amount".

b) If you don’t know how much energy is required for a transaction to send USDT or another token, you can set amount_source="estimate" and fill in the appropriate parameters (estimate_to, estimate_token, estimate_adjust_percent).

buy/energy: Example request with exact amount of energy

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/buy/energy' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS' 
  -d '{
    "format": "json",
    "to":     "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
    "amount_source": "amount", 
    "amount": 31895,
    "period_type": "days",
    "period_amount": 3
}'

buy/energy: Example request with calculation of needed amount of energy

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/buy/energy' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS' 
  -d '{
    "format": "json",
    "to":     "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
    "amount_source": "estimate", 
    "estimate_to": "TLVkYEp4Ue2RpK5v1XNZAB3769g44BSZyH,TJm6HiCMVZdBHbNHThdMv1RambstJPrfYo",
    "estimate_token": "USDT",
    "estimate_adjust_percent": 0.04,
    "period_type": "days",
    "period_amount": 3
}'

buy/energy: Request params

• to (string, required) – TRON address to which the energy is to be delegated
• period_amount (integer, required) – time period to buy energy
• period_type (string, required) – type of time period. Possible values: days, hours.
• format (string, optional) – response format. Possible values: json (default), xml.
• amount_source (string, required) – algorithm for determining the amount of delegated energy. If the value is "amount", then the value of the parameter "amount" is used. If the value is "estimate", the required amount of energy is calculated based on the parameters estimate_to, estimate_token, estimate_adjust_percent. Possible values: amount, estimate.
• amount (integer, required if amount_source="amount") – amount of energy to be purchased. It is ignored if amount_source="estimate".
• estimate_to (string, required if amount_source="estimate") – comma-separated list of TRON addresses to which token transactions are planned to be sent
• estimate_token (string, required if amount_source="estimate") – the TRC20 token. Possible values (case-sensitive): USDT, USDC, USDD, USDJ, JST, TUSD, stUSDT, WTRX.
• estimate_adjust_percent (decimal, required if amount_source="estimate") – the excess energy amount expressed as a percentage. This excess is needed to avoid burning TRX, which may happen if the address has exactly the necessary amount of energy. Recommended value is 0.04%.

Important: Currently, only 6 periods are valid: 1 hour and 1, 3, 7, 15, 30 days.

buy/energy: Response

In case of success, the response will contain the order GUID, by which you can later obtain its actual details.

{
	"status": "ok",
	"data": {
		"guid": 81373165,
		"estimate_task_id": null,
		"status": 0,
		"order_cost": "6.051",
		"to": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
		"energy_amount": 61000,
		"period_type": "hours",
		"energy_delegation_fee": "0.561000000000000000",
		"address_activation_fee": "0.000000000000000000",
		"hours": 1,
		"days": 0,
		"estimate_task": null
	},
	"balance": "7.29412"
}

If request contains amount_source="estimate" then the response has an additional section "estimate_task". For example:

{
	"status": "ok",
	"data": {
		"guid": 77082757,
		"estimate_task_id": 42708906,
		"status": 0,
		"order_cost": "0.561",
		"to": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
		"energy_amount": null,
		"period_type": "hours",
		"energy_delegation_fee": "0.561000000000000000",
		"address_activation_fee": "0.000000000000000000",
		"hours": 1,
		"days": 0,
		"estimate_task": {
			"id": 42708906,
			"token": "USDT",
			"currency": "USD",
			"from": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
			"to": [
				"TLVkYEp4Ue2RpK5v1XNZAB3769g44BSZyH",
				"TJm6HiCMVZdBHbNHThdMv1RambstJPrfYo"
			]
		}
	},
	"balance": "18.29412"
}

buy/energy: Response params

• guid – the order GUID
• balance – funds currently available in the internal account, TRX
• days – duration of energy provision in days, if "period_type=days"
• hours – duration of energy provision in hours, if "period_type=hours"
• estimate_task – calculation (estimation) of energy needed to send TRC20 transactions from one TRON address to the list of another TRON addresses

The "order/get/{guid}" method – getting details of the order

Obtaining information about the specific order.

order/get/{guid} – Example request

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/order/get/12345' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

order/get/{guid} – Example response

{
	"status": "ok",
	"data": {
		"guid": 81373165,
		"estimate_task_id": 32301594,
		"status": 3,
		"payment_status": 0,
		"order_cost_paid": "4.146350000000000000",
		"order_cost": "4.146350000000000000",
		"to": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
		"energy_amount": 31895,
		"period_type": "hours",
		"energy_delegation_fee": "0.000000000000000000",
		"address_activation_fee": "0.000000000000000000",
		"hours": 1,
		"days": 0,
		"resource_txs": [
			{
				"order_guid": 81373165,
				"delegate_txid": "961b6fbd7cc2090d1a65abc06bfabde1046e02d35394f6eca8d05812a6e3ab7"
			}
		],
		"estimate_task": {
			"id": 42708906,
			"token": "USDT",
			"currency": "USD",
			"from": "TQHAAJWLLEjBgYq2sjUnq4kbKfajEXEvyE",
			"to": [
				"TLVkYEp4Ue2RpK5v1XNZAB3769g44BSZyH",
				"TJm6HiCMVZdBHbNHThdMv1RambstJPrfYo"
			]
		}
	}
}

order/get/{guid} – Response params

• guid – the order GUID
• balance – funds currently available in the internal account, TRX
• days – duration of energy provision in days, if "period_type=days"
• hours – duration of energy provision in hours, if "period_type=hours"
• to – TRX address where energy is delivered
• energy_amount – energy quantity
• order_cost – order cost, TRX
• order_cost_paid – amount already paid, TRX (in case of insufficient funds in the internal account this amount will be less than "order_cost")
• address_activation_fee – amount of fee for activation of the destination address, TRX
• energy_delegation_fee – fee for too small order size, TRX
• resource_txs – array containing the list of transactions in TRON blockchain where resources are delegated and reclaimed (undelegated)
• status – order status, possible values are described at the beginning of this manual
• payment_status – order payment status in the payment system (possible values depend on the payment system)

The "order/list" method – getting the list of orders

Getting the list of orders.

order/list – Example request

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/order/list' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

order/list – Request params

• sort (string, optional) – sorting of entries, by default "created_at|desc"
• per_page (integer, optional) – limit the number of entries per response
• page (integer, optional) – sequential number of the response page
• filter (array of arrays(objects), optional) – filter of entries

order/list – Example response

{
	"current_page": 1,
	"data": [
		{
			"guid": 96134274,
			"status": 4
		},
		{
			"guid": 81373165,
			"status": 3
		}
	],
	"first_page_url": "/api/v1/private/order/list?page=1",
	"from": 1,
	"last_page": 1,
	"last_page_url": "/api/v1/private/order/list?page=1",
	"links": [
		{
			"url": null,
			"label": "pagination.previous",
			"active": false
		},
		{
			"url": "/api/v1/private/order/list?page=1",
			"label": "1",
			"active": true
		},
		{
			"url": null,
			"label": "pagination.next",
			"active": false
		}
	],
	"next_page_url": null,
	"path": "/api/v1/private/order/list",
	"per_page": 15,
	"prev_page_url": null,
	"to": 2,
	"total": 2,
	"draw": null,
	"status": "ok"
}

order/list – Response params

• guid – GUID of the order
• status – status of API response

The "account/list" method – listing of internal accounts

Getting a list of internal accounts, including the amount of funds currently available. Since there is a separate internal account for each section of the site (buyer, affiliate, seller, dealer), there are multiple accounts in the account.

account/list – Example request

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/account/list' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

account/list – Example response

{
	"current_page": 1,
	"data": [
		{
			"guid": 29778748,
			"user_id": 81841325,
			"id": 1,
			"section": "affiliate",
			"currency": "TRX",
			"balance": "2.511531"
		},
		{
			"guid": 64463815,
			"user_id": 81841325,
			"id": 2,
			"section": "buyer",
			"currency": "TRX",
			"balance": "41.704"
		}
	],
	"first_page_url": "/api/v1/private/account/list?page=1",
	"from": 1,
	"last_page": 1,
	"last_page_url": "/api/v1/private/account/list?page=1",
	"links": [
		{
			"url": null,
			"label": "pagination.previous",
			"active": false
		},
		{
			"url": "/api/v1/private/account/list?page=1",
			"label": "1",
			"active": true
		},
		{
			"url": null,
			"label": "pagination.next",
			"active": false
		}
	],
	"next_page_url": null,
	"path": "/api/v1/private/account/list",
	"per_page": 15,
	"prev_page_url": null,
	"to": 2,
	"total": 2,
	"draw": null,
	"status": "ok"
}

account/list – Response params

• guid – GUID of the internal account
• id – sequential ID of the internal account
• section – to which EnergyFather section this balance belongs to
• balance – available funds
• currency – currency
• user_id – GUID of the user

The "account/get/{id}" method – getting the exact internal account

Obtaining the balance of the internal account for a specific section of EnergyFather. Since each section has its own account (buyer, affiliate, seller, dealer), there are several accounts for each user. You can first use the "account/list" method to get their list, find out the ‘id’ of the account of interest, and then use this ‘id’ to get the balance of a particular account.

account/get/{id} – Example request

curl -X 'POST' 
  'https://panel.energyfather.com/api/v1/private/account/get/1' 
  -H 'Token: 123456xxxxxxxxxxxxxxxxxxxxxxNOPQRS'

account/get/{id} – Example response

{
	"status": "ok",
	"data": {
		"guid": 64463815,
		"user_id": 81841325,
		"id": 2,
		"section": "buyer",
		"currency": "TRX",
		"balance": "41.704"
	}
}

account/get/{id} – Response params

• guid – GUID of the internal account
• id - sequential ID of the internal account
• section - which EnergyFather section this balance belongs to
• balance - available funds
• currency - currency
• user_id - GUID of the user