Welcome to LAYR, a platform that enables access to energy flexibility on demand. This document is a quick-start guide for operating your virtual asset.
This document includes:
- Key terminology
- API and frontend onboarding
- Integration requirements
Key Concepts and Terminology
Before we dive into using the product, here’s a quick overview of the terms you’ll see throughout the platform and documentation. LAYR uses a novel way of interacting with physical BESS infrastructure. We abstract physical capacity into simple, virtual building blocks which can be recombined into customisable virtual assets.
This section provides a high-level explanation of the key ideas that underpin LAYR. If you’re already familiar with physical asset operations, think of this as a way to shift your mindset to the virtual layer.
Virtual assets: Simplifying the Physical
Rather than dealing directly with the complexity of physical control systems, LAYR lets users interact with virtualised representations of BESS infrastructure, called virtual assets (virtual batteries). Virtual assets are:
- Standardised: Presented in consistent, interoperable formats.
- Abstracted: Underlying physical control complexity such as State of Charge (SoC) drift and ramp rates are handled by us.
- Composable: virtual assets are composed of fundamental blocks. Each of these blocks is physically backed by a single or a pool of real-world assets. By building virtual assets from blocks, we are able to make virtual assets deeply customisable.
- Digitally Marketable: Through virtual assets, physical infrastructure capacity can be traded, auctioned, or allocated entirely digitally via API without any need for physical integration of the off-taker.
This approach allows you to focus on optimisation and trading, not on hardware-level management. Here are some examples of how we simplify infrastructure complexities:
- The SoC of a virtual asset is deterministic. If you tell it to discharge 20 MWh, it will discharge 20 MWh.
- Ramp Rates are managed by us, more details Ramp rates
- High availability. Physical assets suffer from outages. We can dynamically reallocate blocks across our physical fleet to minimise the impact of physical outages on our virtual assets.
This allows developers and analysts to focus on high-level strategy and integration logic, rather than physical control systems.
Key Terms
| Term | Definition |
|---|
| Block | A digital representation of a chunk of asset capacity. Blocks are short-lived and can only participate in one market (wholesale, aFRR POS, aFRR NEG, FCR). They typically cover the duration of a virtual asset. |
| virtual asset (virtual battery) | A time-limited collection of blocks packaged together and operated as a single unit. Usually that would be a wholesale block, a FCR block and an aFRR block which all cover the time duration of the virtual asset. |
| virtual battery Auction (vBA) | A competitive pay-as-bid auction where users compete to gain access to virtual assets. |
Getting Started
It’s important to understand that terralayr provides access to two separate environments:
- Production Environment: This is the live system, where all bids are a binding financial commitment and all asset schedules are physically backed. Any actions you take here will affect real assets and markets.
- Sandbox Environment: This is a fully isolated testing environment, designed to let you experiment, integrate, and validate your workflows without any operational impact. It’s perfect for development and testing purposes.
Both environments support the same API structure and frontend interface, so you can build confidently in Sandbox and deploy seamlessly to Production. Please note that access is environment-specific and users must be provisioned separately.
Account Setup
To access either environment, a member of our team will first create an organisation record in our backend system and associate your email addresses with that organisation. Once this is done, you will receive an email invitation with a secure link to create your account. Here’s how it works:
- Your onboarding contact at terralayr will create your Sandbox organisation and add user emails.
- Each user will receive an invite link via email.
- Clicking the link allows you to create your account and set a password. This grants access to both the API and the frontend for the Sandbox environment.
- When you’re ready to move to Production, the same process will be repeated for the Production environment. We currently require separate user setup for each environment. Accounts are not automatically promoted from Sandbox to Production. This ensures a clean separation between testing and live operations. If you’re unsure whether you’ve been invited or need help accessing either environment, please reach out to your account manager or contact us at support@trlyr.com.
API Access
Our API is designed to be the fastest and most flexible way to interact with LAYR. When integrating us into your backend systems, you’ll find all the tools you need in our public API documentation.
Getting Your Access Token
To begin using the API, you’ll first need to authenticate and obtain an access token. The process for obtaining this token is the same for both Sandbox and Production environments. This token authorises your requests and should be included with all API calls.
Send a POST request to the Authorization Endpoint:
POST / auth / public / authenticate
Content - Type : application / json
{
" username ": "your.email@example.com",
" password ": "your_password"
}
{
" access_token ": "eyJhbGciOiJIUzI1NiIsIn ..."
}
Authorization : Bearer YOUR_ACCESS_TOKEN
Frontend Access
For teams who prefer a visual interface or want to explore the platform without writing code, our web frontend offers full access to LAYR’s core functionality.
The frontend makes it easy to:
- View and manage your virtual assets
- Submit and monitor ancillary services bids (for ancillary services enabled virtual assets)
- Perform intraday dispatch operations and State of Charge (SoC) management
System Integration Overview
Once you have your account setup, LAYR is designed to be as easy to integrate with as possible. For most users, no deep system integration is required to get started. For support implementing the API, please don’t hesitate to contact us at support@trlyr.com
Balancing Group Integration via EIC Codes
The only required integration step for wholesale market settlement is a one-time exchange ofn EIC codes - unique identifiers for each party’s balancing group within the EU energy market. This is necessary to facilitate nominations between our balancing group and yours, which align actual physical dispatch with the trades your company places.
TSO Zone Requirement
Important: Both your balancing group and ours must reside within the same Transmission System Operator (TSO) zone. At present, our physical assets are live only in the TenneT TSO zone. Customers must therefore have, or be able to trade through, a balancing group registered in the TenneT zone in order to participate in virtual assets.
How It Works
- You make wholesale market trades within your own balancing group and send us schedules for execution.
- We send dispatch schedules to our physical fleet within our balancing group to deliver those trades.
- This creates a temporary market imbalance:
- You have traded volumes without corresponding physical delivery.
- We have dispatches without corresponding trades.
- On the day after each delivery day (D+1), we resolve this by nominating your virtual asset’s schedule from our balancing group to yours. This nomination signals to the TSO that the apparent imbalance is administrative, not physical, and that both sides of the transaction are accounted for across balancing groups.
What You Need To Do
- Provide your EIC code to our onboarding team.
- Ensure that your team is able to generate and send schedules via our API (see API documentation) or frontend.
- We will provide our own EIC code, and automatically handle nominations for each trading day.
This simple process ensures that physical delivery and market trades are reconciled transparently.
Tutorial: Your First virtual asset
You’re now ready to experience how easy and powerful it is to trade and dispatch virtual infrastructure via LAYR. Whether you’re accessing via API or using the frontend, this step-by-step guide will walk you through bidding in your first virtual asset and dispatching your first asset.
What You’ll Learn:
- How to find your upcoming capacity
- How to dispatch your capacity
- How to handle unavailability events (if they arise)
View Upcoming Capacity
At approx. 5pm CET/CEST, 2 days before delivery (D-2), you will have virtual assets created against your organisation. For Designated Optimisers, the capacity you receive is allocated from a pool of physical infrastructure owned by both terralayr and our customers. For vBA participants, the capacity you receive is determined by the clearing process of the auctions you participate in.
- Frontend: Go to Dispatch → Upcoming and review the virtual assets.
- API: Use:
GET /organisations/{organisationID}/virtual-assets
Dispatch Your Capacity
- Once you’ve secured capacity, you can start to dispatch it in accordance with your trading activity.
- You can change the schedule for the virtual asset as often as you like up until the gate closure time specified for the virtual asset (typically 5 minutes and 30 seconds before delivery).
- Frontend: Navigate to the Dispatch tab and select the virtual asset you want to dispatch.
- Select your timeslot and assign a dispatch value in kW for charging (import) and discharging (export). Click Submit Schedule.
- API: Updates to the virtual asset’s wholesale dispatch schedule should be send to the virtual asset’s wholesale market block. Submit your schedule to:
POST /organisations/{organisationID}/virtual-assets/{virtualassetID}/blocks/{blockID}
Body:
{
"schedule": [
{
"power": 380,
"time": "2023-11-11T14:30:00Z"
},
]
}
- Our backend will then carry out some basic schedule validations to ensure that your virtual asset will remain within bounds and that your submitted schedule is physically deliverable. More information on schedule validations can be found here.
- Congratulations! You have now dispatched your first virtual asset via LAYR!
Frequently Asked Questions
- What If an Unavailability Occurs? While rare, outages do happen - even in the virtual world. LAYR is designed to minimise disruption: There’s a deep dive into unavailabilities at: Virtual asset unavailabilities
Welcome to a new way of engaging with BESS infrastructure - flexible, programmable, and purpose-built for offtakers. Last modified on May 6, 2026
