WorkspaceDemo

Developer API · Alvo platform

API for DAM, BESS, and controlled decisions.

Connect Alvo to internal portals, BI, partner products, or trader workflows. V1 prepares verifiable calculations, explanations, risk reports, and audit trails, but it does not submit market orders without the responsible trader.

Open OpenAPI JSON Launch workspace
OpenAPI 3.1API key readyhuman approval

Integration layers

One contract for data, decisions, risk, and audit.

Market data

OREE covers live prices and indexes; UEEX stays licence-gated until a written agreement and machine-readable feed exist.

Decision engine

Strategy, BESS, and backtest endpoints share the same PricePoint model.

Control plane

Risk reports, audit events, API key mode, and rate limits for a controlled launch.

Security model

Demo can be public. Production access is protected by API keys.

ALVO_REQUIRE_API_KEY=true moves endpoints into key-protected mode. The key is accepted through x-alvo-api-key or Authorization: Bearer. Every response includes no-store, X-Alvo-API-Version, and security mode headers.

Secrets server-sideALVO_API_KEY never reaches the browser or client bundle.
Rate limitsALVO_RATE_LIMIT_PER_MINUTE and ALVO_RATE_LIMIT_WINDOW_MS protect endpoints from noisy traffic.
No automatic order submissionV1 does not submit market orders and requires trader approval.

Workflow

A typical integration follows five controlled steps.

01Load market data

GET /api/oree/prices, /api/oree/indexes, and your own CSV/import layer; the UEEX endpoint stays gated until a written agreement and feed exist.

02Build plan

POST /api/strategy/plan and POST /api/bess/plan.

03Check risk

POST /api/risk/report before export or approval.

04Write audit

POST /api/audit/events for key actions.

05Connect signals

POST /api/notifications/subscriptions for PWA channels without automatic order submission.

Intelligence layer

Alvo signals as a pluggable intelligence layer — for GPT, Claude, and your systems.

The same deterministic analytics the workspace runs, exposed to machines: an MCP tool-server for external assistants and a sovereignty receipt attesting that generation happened with zero data egress. All read-only and honest about the price-only forecast ceiling.

Model Context Protocol

MCP tool-server (read-only)

POST /api/mcpGET /api/mcp

An external GPT or Claude reads Alvo's deterministic signals (day-ahead prices, forecast, cross-border regime) and cited methodology over the Model Context Protocol — JSON-RPC 2.0 over HTTP. Read-only: no tool mutates anything or places an order. Every result carries a deterministic provenance marker (model alvo-rules-v1, dataSentToExternalModel:false).

server
alvo-sovereignty
protocolVersion
2025-06-18

Available tools

  • get_day_ahead_pricesHourly Ukraine DAM/IDM price book (UAH/MWh) for a month.
  • get_forecastProbabilistic forecast: p10/p50/p90 bands, optional capHitProbability, and model skill (rMAE).
  • get_regime_snapshotCross-border scarcity regime: scarce / balanced / surplus, UA–EU basis, flow direction.
  • cite_methodologyCited grounding from the Alvo docs corpus: forecast validation, AI sovereignty and tool guardrails.
tools/list example (JSON-RPC 2.0)
curl -X POST "$ALVO_URL/api/mcp" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
EU AI Act Article 50

Sovereignty receipt (no-egress)

POST /api/ai/receipt/verify

Every AI brief and export can carry a sovereignty receipt — a structured record that generation was deterministic, used no external model, and sent no data off-platform (0 external tokens, $0). The receipt embeds a recomputable hash of the declared inputs, so anyone can verify it independently through the open endpoint.

What the receipt attests

model
alvo-rules-v1
method
deterministic
dataSentToExternalModel
false
externalTokens
0
receiptVersion
alvo-no-egress-receipt-1
Where it appearsOn the trading brief (/api/ai/trading-brief) and in plan exports; verification is POST /api/ai/receipt/verify (no secrets, no auth).
Market Model Studio validation

504 historical DAM hours reconstructed exactly.

Backtest on the frozen Energy Map archive: Alvo's deterministic clearing engine re-derived the actual day-ahead clearing price and cleared volume from published bid/ask curves across low and high price regimes, including cap-binding hours. This validates the clearing core, not a live forecast, forward forecast, or automatic trading action.

docs/research/market-model-studio-validation.md
Market Model Studio validation
504 cases
Market Model Studio validation
0 price/volume error
Market Model Studio validation
100% boundary accuracy

Disclosure under Article 50 of the EU AI Act (EU AI Act Article 50).

Endpoints

A stable V1 surface for product and partner integrations.

GET/api/health
OperationsHealth check

Operational readiness for API, security mode, rate limits, engines, and market data dependencies.

GET/api/oree/prices
Market dataOREE prices

Monthly DAM or IDM price book from public Market Operator data.

GET/api/oree/indexes
Market dataDAM indexes

Base, Peak, OffPeak, min, max, and weighted-average DAM prices by date.

GET/api/ueex/electricity-indexes
Market dataUEEX indexes

Ukrainian Energy Exchange BCM BASE indexes — licence-gated; served only under a written UEEX redistribution agreement, off otherwise.

GET/api/forecast
Market dataPrice forecast

Monthly probabilistic forecast: hourly p10/p50/p90 bands, optional capHitProbability for DAM cap-hit risk, the served model, and its skill (rMAE vs the seasonal-naive benchmark).

POST/api/strategy/plan
StrategyDAM plan

Recommended buy/sell hours, expected result, spreads, volume, and fees.

POST/api/bess/plan
BESSBESS plan

Charge/discharge cycles, profit with efficiency, degradation, and equivalent cycles.

POST/api/backtest/summary
BacktestBacktest summary

Multi-day strategy + BESS performance, hit rate, best/worst days, and daily rows.

POST/api/risk/report
RiskRisk report

Data coverage, anomalies, exposure, BESS cycles, and guardrails before trader approval.

POST/api/ai/trading-brief
AITrading brief

Localized deterministic brief for the trader in Ukrainian or English.

GET/api/narrator/tools
AIDeterministic tool registry

Service-token guarded list of available AiNarrator tools with input schemas. Describes tools only - no external model and no trading action.

POST/api/narrator/tools/{name}
AIRun a deterministic tool

Service-token guarded call for one tool using its schema. Invalid input or an unknown tool returns ok:false instead of a raw exception.

GET/api/billing/plans
BillingSubscription catalog

Public contract for plans, AI/API limits, add-ons, and overage policy before future checkout.

POST/api/audit/events
AuditAudit event

Typed prices_loaded, csv_imported, ai_brief_generated, and plan_exported events for the action log.

GET/api/audit/events
AuditTenant event log

Tenant-scoped list of recent events (audit.read role only when RBAC is enforced). Supports limit and before cursor for pagination.

GET/api/coupling/flows
ENTSO-ECross-border flows

Hourly MW flows for a UA border (default UA↔PL): leg.fromTo, leg.toFrom, netFlowMw. Live from ENTSO-E A11; fixture when token absent.

GET/api/multi-zone/prices
Energy-ChartsRegional DAM prices

Day-ahead prices for UA neighbours (PL, SK, HU, RO) and DE-LU — EUR/MWh via Energy-Charts, shown only for CC-BY-licensed zones with attribution. Non-CC-BY zones (e.g. SK/OKTE) are suppressed; raw ENTSO-E A44 (exchange-owned) is never redistributed.

GET/api/system-operations
ENTSO-EUA power system

Hourly UA load + generation mix (nuclear / coal / gas / hydro / wind / solar). Live from ENTSO-E A65 + A75; fixture when UA TSO doesn't publish (today).

GET/api/regime
AlvoCross-border scarcity regime

Deterministic headline signal: the regime (scarce/balanced/surplus), the derived UA↔EU basis (EUR/MWh) + its level, and the coupling flow direction. Derived basis only — never a raw exchange A44/NEMO price. A present-state read, not a forecast. The same signal as the MCP tool get_regime_snapshot, over plain REST.

GET/api/market-model/market-depth
Market ModelMarket depth / execution risk

Service-token guarded read over stored order-book snapshots: walk-the-book slippage, depth, and execution risk by size. Display over supplied ladders - not a forecast, order recommendation, or fill guarantee.

POST/api/account/api-keys
SecurityCreate API key

Mint a tenant-scoped API key for programmatic access. Plaintext is returned exactly once — save it. Requires api.manage role (owner).

GET/api/account/api-keys
SecurityList API keys

Active API keys for the tenant (without plaintext): name, prefix, lastUsedAt, createdAt.

DELETE/api/account/api-keys/{id}
SecurityRevoke API key

Soft-revoke a key (writes revokedAt + actorId). Revoked keys cannot be restored — issue a new one.

POST/api/notifications/subscriptions
NotificationsPWA subscription

Web Push contract for price updates, risk alerts, BESS windows, and export readiness without trading action.

Risk report request
curl -X POST "$ALVO_URL/api/risk/report" \
  -H "content-type: application/json" \
  -H "x-alvo-api-key: $ALVO_API_KEY" \
  -d '{
    "tradeDate": "13.05.2026",
    "prices": [
      { "hour": 0, "priceUahMwh": 5575 },
      { "hour": 1, "priceUahMwh": 5100 },
      { "hour": 2, "priceUahMwh": 100 },
      { "hour": 3, "priceUahMwh": 70 },
      { "hour": 4, "priceUahMwh": 100 },
      { "hour": 5, "priceUahMwh": 4800 },
      { "hour": 6, "priceUahMwh": 5880 },
      { "hour": 7, "priceUahMwh": 5267 },
      { "hour": 8, "priceUahMwh": 3878 },
      { "hour": 9, "priceUahMwh": 3050 },
      { "hour": 10, "priceUahMwh": 49 },
      { "hour": 11, "priceUahMwh": 10 },
      { "hour": 12, "priceUahMwh": 11 },
      { "hour": 13, "priceUahMwh": 11 },
      { "hour": 14, "priceUahMwh": 10 },
      { "hour": 15, "priceUahMwh": 12 },
      { "hour": 16, "priceUahMwh": 110 },
      { "hour": 17, "priceUahMwh": 1900 },
      { "hour": 18, "priceUahMwh": 6200 },
      { "hour": 19, "priceUahMwh": 7400 },
      { "hour": 20, "priceUahMwh": 6900 },
      { "hour": 21, "priceUahMwh": 6100 },
      { "hour": 22, "priceUahMwh": 5400 },
      { "hour": 23, "priceUahMwh": 4800 }
    ],
    "strategySettings": {
      "volumeMwh": 5,
      "minSpreadUah": 250,
      "maxTradesPerDay": 4,
      "feeUahPerMwh": 12
    },
    "bessSettings": {
      "capacityMwh": 10,
      "powerMw": 5,
      "roundTripEfficiency": 0.9,
      "maxCyclesPerDay": 2,
      "degradationCostUahMwh": 80
    }
  }'
Guardrail response
{
  "tradeDate": "13.05.2026",
  "report": {
    "overallStatus": "needsReview",
    "score": 76,
    "reviewCount": 3,
    "blockCount": 0
  }
}

Ready to connect the API to a product?

Use the workspace to verify logic manually, then use OpenAPI JSON for SDKs, Postman, contract tests, or partner integrations.

Open workspace OpenAPI JSON