terralayr API - terralayr

The terralayr API gives your organisation programmatic access to the terralayr platform across six domains: virtual assets, auctions, revenue reporting, physical assets, asset monitoring, and authentication. Every endpoint is secured with a Bearer token — see Authentication to get started.

Virtual Assets

Manage virtual batteries and their block schedules

Auctions

Browse energy auctions, submit bids, and track outcomes

Revenue Reporting

Query revenue and aggregated data points across assets and portfolios

Physical Assets

Manage physical asset parameters, schedules, bids, and logbook entries

Asset Monitoring

Retrieve timeseries datapoints for physical assets

Authentication

Authenticate and obtain Bearer tokens

Virtual Assets

A virtual asset is a virtual battery with static parameters that control how much power it can import and export, how much energy it can store, and how efficiently it charges and discharges. It also has a state of charge that changes as the asset exports and imports power. A block represents a slice of a virtual asset’s power capacity over a time window. Each block has a schedule you can update to control what the virtual asset does during that period.

Keep virtual assets balanced: manage schedules so that the state of charge at the end of the asset’s lifetime is 50%. You can submit schedules that deviate from this, but the response will include an imbalance report.

Auctions

This API lets participating organisations browse energy auctions, submit bids, and track outcomes on the terralayr platform. Each auction offers a virtual-asset delivery window — power, energy, and efficiency parameters — for a specific period. During the auction open interval, invited organisations can place bids priced in EUR. After the auction closes, the highest valid bid wins; if prices tie, the earliest bid wins. Auction responses include a status for your organisation:

Status	Meaning
`NOT_STARTED`	The auction has not yet opened
`RUNNING`	The auction is open and accepting bids
`PENDING`	The auction has closed and results are being processed
`WON`	Your organisation won the auction
`LOST`	Your organisation did not win
`NO_BIDS_SUBMITTED`	The auction closed with no bids from your organisation

When you win, the response includes the allocated virtual asset ID.

Revenue Reporting

This API exposes revenue data and aggregated data points for virtual assets, portfolios, fleets, and physical assets on the terralayr platform. Use the revenue endpoints to query wholesale, ancillary, tolling, and virtual battery auction revenue for a virtual asset over a time range. Data-point endpoints return aggregated metrics at raw, 15-minute, hourly, or daily resolution.

Data point categories

Data-point endpoints accept an optional datapoints query parameter: a comma-separated list of category names. When omitted, all categories for the asset are returned. Each category name appears as a key under data in the response (dataPointName in metaData).

Total and wholesale

Wholesale metrics are calculated per 15-minute delivery period. Buy means energy imported (charging); sell means energy exported (discharging). Volume-weighted average prices (VWAP) are the average wholesale price weighted by traded volume within each period. Net volume is sell minus buy energy (MWh). Net-off volume is the portfolio schedule-netting volume: energy attributed to internal schedule netting rather than wholesale market trades.

Category	Description
`revenue_total_revenue`	Total revenue across wholesale, ancillary, tolling, and virtual battery auction products
`revenue_wholesale`	Wholesale market revenue for the period (sell proceeds minus buy cost)
`buy_vwap_wholesale`	Volume-weighted average buy price over the 15-minute period (EUR/MWh)
`sell_vwap_wholesale`	Volume-weighted average sell price over the 15-minute period (EUR/MWh)
`buy_volume_wholesale`	Energy bought on the wholesale market in the period (MWh)
`sell_volume_wholesale`	Energy sold on the wholesale market in the period (MWh)
`net_volume_wholesale`	Net wholesale energy: sell volume minus buy volume (MWh)
`net_off_volume_wholesale`	Schedule-netting volume from portfolio internal netting (MWh)

FCR

FCR metrics relate to 4-hour EFA delivery blocks. Weighted capacity and settlement price values multiply each accepted capacity or price by its delivery hours within the block. The weighted-average categories divide those sums by total delivery hours in the block.

Category	Description
`revenue_fcr`	FCR capacity revenue for the delivery window
`capacity_fcr`	Accepted FCR capacity (MW)
`settlement_price_fcr`	FCR settlement price (EUR/MW per hour)
`weighted_capacity_fcr`	Accepted capacity multiplied by delivery hours within the window
`weighted_settlement_price_fcr`	Settlement price multiplied by delivery hours within the window
`delivery_hours_fcr`	FCR delivery hours in the window
`capacity_fcr_weighted_avg`	Capacity-weighted average accepted FCR capacity over the 4-hour EFA block
`settlement_price_fcr_weighted_avg`	Capacity-weighted average FCR settlement price over the 4-hour EFA block

aFRR

Positive and negative energy categories refer to upward and downward aFRR energy activation respectively.

Category	Description
`revenue_afrr_capacity`	aFRR capacity revenue
`revenue_afrr_energy`	Combined aFRR energy revenue (positive plus negative)
`revenue_afrr_energy_pos`	aFRR positive (upward) energy revenue
`revenue_afrr_energy_neg`	aFRR negative (downward) energy revenue
`settlement_price_afrr_energy_pos`	Settlement price for positive aFRR energy activations
`settlement_price_afrr_energy_neg`	Settlement price for negative aFRR energy activations
`total_volume_afrr_energy_pos`	Total activated positive aFRR energy volume
`total_volume_afrr_energy_neg`	Total activated negative aFRR energy volume

Tolling and virtual battery auction

Category	Description
`revenue_tolling`	Tolling revenue
`annual_price_tolling`	Tolling annual price
`revenue_vba`	Virtual battery auction revenue
`hurdle_price_vba`	Virtual battery auction hurdle price

Normalised revenue (per MW)

Normalised revenue divides absolute revenue (EUR) by the virtual asset’s average rated power capacity (MW), where capacity is the mean of rated charge and discharge power. This allows comparison across assets of different sizes.

Category	Description
`revenue_normalised_total`	Total revenue normalised per MW
`revenue_normalised_wholesale`	Wholesale revenue normalised per MW
`revenue_normalised_fcr`	FCR revenue normalised per MW
`revenue_normalised_afrr_capacity`	aFRR capacity revenue normalised per MW
`revenue_normalised_afrr_energy`	Combined aFRR energy revenue normalised per MW
`revenue_normalised_afrr_energy_pos`	Positive aFRR energy revenue normalised per MW
`revenue_normalised_afrr_energy_neg`	Negative aFRR energy revenue normalised per MW
`revenue_normalised_vba`	Virtual battery auction revenue normalised per MW
`revenue_normalised_tolling`	Tolling revenue normalised per MW

Normalised revenue (per MW per year)

These categories scale the per-MW normalised values by 365 to express an annualised rate (EUR/MW/year).

Category	Description
`revenue_normalised_per_year_total`	Total normalised revenue per MW per year
`revenue_normalised_per_year_wholesale`	Wholesale revenue normalised per MW per year
`revenue_normalised_per_year_fcr`	FCR revenue normalised per MW per year
`revenue_normalised_per_year_afrr_capacity`	aFRR capacity revenue normalised per MW per year
`revenue_normalised_per_year_afrr_energy`	Combined aFRR energy revenue normalised per MW per year
`revenue_normalised_per_year_afrr_energy_pos`	Positive aFRR energy revenue normalised per MW per year
`revenue_normalised_per_year_afrr_energy_neg`	Negative aFRR energy revenue normalised per MW per year
`revenue_normalised_per_year_vba`	Virtual battery auction revenue normalised per MW per year
`revenue_normalised_per_year_tolling`	Tolling revenue normalised per MW per year

Physical Assets

This API manages physical assets on the terralayr platform: asset parameters, schedules, ancillary bids and results, metadata, logbook entries, unavailabilities, and EEX notifications.

Asset Monitoring

This API provides timeseries datapoints for physical assets, allowing you to observe asset behaviour and operational state over time.

Authentication

All endpoints require a Bearer token in the Authorization header. Step 1 — get a token:

POST https://api.trlyr.com/auth/public/authenticate
Content-Type: application/json

{
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD"
}

Extract access_token from the response body. Step 2 — use the token on every request:

Authorization: Bearer <access_token>

Your username and password are set when you accept an invitation to join your organisation. If you need access, contact support@trlyr.com.

Virtual Assets

Auctions

Revenue Reporting

Physical Assets

Asset Monitoring

Authentication

​Virtual Assets

​Auctions

​Revenue Reporting

​Data point categories

​Total and wholesale

​FCR

​aFRR

​Tolling and virtual battery auction

​Normalised revenue (per MW)

​Normalised revenue (per MW per year)

​Physical Assets

​Asset Monitoring

​Authentication

Virtual Assets

Auctions

Revenue Reporting

Data point categories

Total and wholesale

FCR

aFRR

Tolling and virtual battery auction

Normalised revenue (per MW)

Normalised revenue (per MW per year)

Physical Assets

Asset Monitoring

Authentication