> ## Documentation Index > Fetch the complete documentation index at: https://docs.trlyr.com/llms.txt > Use this file to discover all available pages before exploring further. # Designated optimiser onboarding > A quick-start guide for operating as a Designated Optimiser (DO) on Layr. Welcome to LAYR, a platform that enables access to energy flexibility on demand. This document is a quick-start guide for operating as a Designated Optimiser on LAYR. 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 Batteries: 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 Batteries (vBs). vBs 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: vBs are composed of fundamental blocks. Each of these blocks is physically backed by a real-world asset. By building vBs from blocks, we are able to make vBs deeply customisable. * Digitally Marketable: Through vBs, physical infrastructure capacity can be traded, auctioned, or allocated entirely digitally without any need for physical integration. 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 vB is deterministic. If you tell it to discharge 20 MWh, it will discharge 20 MWh. * Ramp Rates are fully managed. Instead of calculating trapezoidal dispatch curves with fixed ramp rates between wholesale market settlement periods, vBs just require your final position. We handle the ramping. * 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 vBs. This allows developers and analysts to focus on high-level strategy and integration logic, rather than control systems. ## Key Terms | Term | Definition | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Block | A digital representation of a chunk of flex capacity. Blocks are short-lived and can only participate in one market (wholesale, aFRR POS, aFRR NEG, FCR) | | Virtual Battery (vB) | A collection of blocks packaged together and operated as a single unit | | Virtual Battery Auction (vBA) | A competitive pay-as-bid auction where users compete to gain access to vBs | # 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 battery 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: 1. Your onboarding contact at terralayr will create your Sandbox organisation and add user emails. 2. Each user will receive an invite link via email. 3. 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. 4. 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](mailto: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. * API Docs: [Link](/trlyr-API/introduction) ### 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: ```json theme={null} POST / auth / public / authenticate Content - Type : application / json { " username ": " your . email@example . com " , " password ": " your_password " } ``` On success, the response will include an access token: ```json theme={null} { " access_token ": " eyJhbGciOiJIUzI1NiIsIn ..." } ``` Use this token in the header for all subsequent API requests: ```json theme={null} Authorization : Bearer YOUR_ACCESS_TOKEN ``` If you have any trouble accessing the API, reach out to us at [support@trlyr.com](mailto:support@trlyr.com). We’re happy to help you get up and running quickly. ## 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. * Production Login URL: [https://app.trlyr.com](https://app.trlyr.com/) * Sandbox Login URL: [https://app.sandbox.trlyr.com](https://app.sandbox.trlyr.com/) * Supported Browsers: Chrome, Firefox, Safari (latest versions) The frontend makes it easy to: * View and manage your virtual assets * Submit and monitor ancillary services bids (for ancillary services enabled virtual batteries) * 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 hesistate to contact us at [support@trlyr.com](mailto: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 vBAs. ### How It Works 1. You make wholesale market trades within your own balancing group and send us schedules for execution. 2. We send dispatch schedules to our physical fleet within our balancing group to deliver those trades. 3. This creates a temporary market imbalance: 1. You have traded volumes without corresponding physical delivery. 2. We have dispatches without corresponding trades. 4. On the day after each delivery day (D+1), we resolve this by nominating your virtual battery’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 vBA 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-bystep guide will walk you through bidding in your first vBA 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) 1. View Upcoming Capacity The capacity you receive as an optimiser is allocated from a pool of physical infrastructure owned by both terralayr and our customers. At approx. 5pm CET/CEST, 2 days before delivery (D-2), you will automatically have vBs created against your organisation. * Frontend: Go to Dispatch → Upcoming and review the vBs. * API: Use: ```jsx theme={null} GET /organisations/{organisationID}/virtual-assets ``` This lists all vBs you have access rights to dispatch. 2. Dispatch Your Capacity Once you’ve been allocated capacity, you can dispatch it in accordance with your trading activity. You can change the schedule for the virtual battery as often as you like up until the gate closure time specified for the vB (typically 5 minutes and 30 seconds before delivery). Frontend: Navigate to the Dispatch tab and select the vB 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 vB’s wholesale dispatch schedule should be send to the vB’s wholesale market block. Submit your schedule to: ```json theme={null} 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 vB will remain within bounds and that your submitted schedule is physically deliverable. Congratulations! You have now dispatched your first vB via LAYR! 3. What If an Unavailability Occurs? While rare, outages do happen - even in the virtual world. LAYR is designed to minimise disruption: * If one physical asset becomes unavailable, we automatically reassign your blocks to another asset, if available. * If no substitute capacity is available, your power capacity and/or energy capacity will be partially or fully curtailed. * In such cases, we provide financial compensation for the period of unavailability. How to Monitor Availability: Our automated notification system for vB unavailability monitoring is planned for release in Q4 2025. In the meantime we will contact you as quickly as possible after an unavailability event. We also provide ways to monitor a vB’s availability through the frontend and API. * Frontend: Navigate to the Dispatch tab and select the vB you want to monitor. The graphs in the dispatch page for the virtual asset show the usable energy and power capacity of the asset as a time series and show any unavailabilities affecting your vB. * API: For the available power capacity of your vB, use: ```json theme={null} GET /organisations/{organisationID}/virtual-assets/{virtualAssetID}/blocks/{blockID} ``` For the available energy capacity of your vB, use: ```json theme={null} GET /organisations/{organisationID}/virtual-assets/{virtualAssetID}/energy-capacity ``` There’s a deep dive into unavailabilities at: [Virtual asset unavailabilities](/layrUserGuide/features/unavailabilities) 4. You’re Live! You’ve now successfully: * Sent your first schedule * Learned how to handle unavailabilities Welcome to a new way of engaging with BESS infrastructure - flexible, programmable, and purpose-built for offtakers.