DEVELOPER DOCUMENTATION · PRODUCTION V1

ACERM Documentation

Integrate ACERM into your AI infrastructure. One environment variable. Sub-millisecond latency. Full carbon governance from day one.

Quick Start

Integrate in 60 Seconds

ACERM exposes an OpenAI-compatible endpoint. Any agent using the OpenAI SDK can route through ACERM by changing a single environment variable. No changes to agent code required.

BEFORE — Direct to OpenAI

# .env
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-...

AFTER — Through ACERM

# .env
OPENAI_BASE_URL=http://your-acerm-node:8080/v1
OPENAI_API_KEY=sk-...
X_ACERM_KEY=your-acerm-key

That's it. Every inference request now passes through ACERM — evaluated against live UK National Grid carbon intensity, governed by your policy, and recorded in the SHA-256 audit chain.

Authentication

X-ACERM-KEY Header

Every inference request to ACERM must include a valid X-ACERM-KEY header. Keys are SHA-256 hashed before storage — ACERM never stores plaintext keys.

POST /v1/chat/completions HTTP/1.1
Host: your-acerm-node:8080
Content-Type: application/json
X-ACERM-KEY: your-acerm-key

{
  "model": "claude-haiku-4-5-20251001",
  "max_tokens": 1000,
  "messages": [{"role": "user", "content": "Hello"}]
}

Valid keyRequest evaluated against grid policy → PERMIT / DELAY / DENY / DOWNGRADE

Invalid keyHTTP 401 Unauthorized — request rejected immediately

Missing keyHTTP 401 Unauthorized — request rejected immediately

Enforcement

Enforcement Outcomes

Every request receives one of five outcomes based on grid state and agent priority.

Outcome	HTTP Status	Meaning	When
PERMIT	200 OK	Request forwarded to upstream provider	Grid GREEN, or HIGH priority agent
DELAY	202 Accepted	Request queued — retry after grid improves	STANDARD priority in AMBER/RED
DENY	429 Too Many Requests	Request rejected — carbon policy enforced	LOW priority in AMBER/RED
DOWNGRADE	200 OK	Request routed to lighter model (claude-haiku)	LOW priority in AMBER — model swap
THROTTLE	429 Too Many Requests	Rate limited — too many requests per minute	Agent exceeding rate threshold

Handling outcomes in your agent code:

import anthropic

client = anthropic.Anthropic(
    base_url="http://your-acerm-node:8080/v1",
    default_headers={"X-ACERM-KEY": "your-key"}
)

try:
    response = client.messages.create(
        model="claude-haiku-4-5-20251001",
        max_tokens=1000,
        messages=[{"role": "user", "content": "Hello"}]
    )
    print(response.content)

except anthropic.RateLimitError:
    # DENY or THROTTLE — grid is RED
    print("Request deferred — high carbon period")
    # Queue for retry or use cached response

API Reference

Endpoints

POST/v1/chat/completions

OpenAI-compatible inference proxy. Requires X-ACERM-KEY header. Evaluates request against live grid policy and forwards to upstream provider if permitted.

EXAMPLE RESPONSE

{"id":"acerm-1234","object":"chat.completion","choices":[...],"acerm":{"outcome":"PERMIT","grid_intensity":87,"grid_state":"GREEN","co2_g":0.003}}

GET/api/heartbeat

System health check. Returns current grid state, intensity, and ACERM operational status.

EXAMPLE RESPONSE

{"status":"ok","grid_intensity":87,"grid_state":"GREEN","mode":"SHADOW","chain_length":4900}

GET/api/audit

Audit chain summary. Returns ESRS E1 compatible summary with total requests, carbon avoided, and chain verification status.

EXAMPLE RESPONSE

{"esrs_e1_status":"VERIFIED","total_requests":1000,"carbon_avoided_kg":73.6,"compliance_rate":100}

GET/api/leaderboard

Agent performance rankings. Returns per-agent carbon metrics, request counts, and compliance scores.

EXAMPLE RESPONSE

[{"agent_id":"ResearchBot","priority":"HIGH","total_requests":245,"avg_co2_g":0.004}]

POST/api/toggle-mode

Switch between SHADOW mode (record only, no enforcement) and ACTIVE mode (full enforcement). Requires authentication.

EXAMPLE RESPONSE

{"mode":"ACTIVE","message":"Enforcement now active"}

WS/ws/oracle

Real-time WebSocket feed. Broadcasts grid state updates every 30 seconds. Connect to receive live carbon intensity and gate status.

EXAMPLE RESPONSE

{"grid_intensity":87,"grid_state":"GREEN","gate":"OPEN","timestamp":"2026-05-24T14:00:00Z"}

Grid States

GREEN / AMBER / RED

ACERM queries the UK National Grid ESO Carbon Intensity API every 30 seconds. Grid state determines enforcement policy for all agents.

GREENOPEN

< 120 gCO₂/kWh

All agents PERMITTED. Grid running clean — renewable generation high.

AMBERFILTER

120–250 gCO₂/kWh

LOW priority agents DENIED. STANDARD agents DELAYED. HIGH priority PERMITTED.

REDRESTRICT

> 250 gCO₂/kWh

LOW agents DENIED. STANDARD agents DELAYED. Only HIGH priority requests PERMITTED.

Carbon Integrity Safety Protocol (CISP)

If grid telemetry is unavailable for any reason, ACERM defaults to fail-closed — treating the grid as RED and applying the most restrictive policy. This prevents unmonitored carbon leakage during telemetry outages. Audit chain continuity is maintained via auto-generated bridge entries.

Operating Modes

Shadow Mode vs Active Mode

SHADOWDefault

All requests permitted regardless of grid state. Every decision is recorded in the audit chain as if enforcement had occurred — but nothing is blocked. Use this for the first 7 days to build your baseline audit trail without any operational disruption.

First 7 days — Shadow Audit

Building CSRD baseline data

Testing policy configuration

Demonstrating to auditors

ACTIVEEnforcement

Full carbon governance enforced. Requests are PERMITTED, DELAYED, DENIED, or DOWNGRADED based on live grid state and agent priority. Every decision is cryptographically sealed in the audit chain.

Production carbon governance

CSRD limited assurance evidence

Carbon Flexibility Certificate generation

Full ESRS E1 compliance

# Switch to ACTIVE mode
curl -X POST http://your-acerm-node:8080/api/toggle-mode \
  -H "Content-Type: application/json"

# Response
{"mode":"ACTIVE","message":"Enforcement now active"}

Real-Time Feed

WebSocket Grid Feed

Subscribe to the real-time grid state WebSocket for live carbon intensity updates. Updates broadcast every 30 seconds.

// JavaScript
const ws = new WebSocket('ws://your-acerm-node:8080/ws/oracle');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.grid_state);    // "GREEN" | "AMBER" | "RED"
  console.log(data.grid_intensity); // e.g. 87
  console.log(data.gate);          // "OPEN" | "FILTER" | "RESTRICT"
};

Agent Configuration

Agent Priority Levels

Each agent key is assigned a priority level in the ACERM registry. Priority determines enforcement behaviour during AMBER and RED grid periods.

Priority	GREEN	AMBER	RED	Use Case
HIGH	PERMIT	PERMIT	PERMIT	Life-safety, legal, financial-critical
STANDARD	PERMIT	DELAY	DELAY	Core business operations
LOW	PERMIT	DENY	DENY	Background tasks, analytics, scraping

Get Your ACERM Key

ACERM is currently in early access. Contact us to get your agent keys and start your free 7-day Shadow Audit.

Request Access →Read Methodology Live Dashboard