# Demand-response aggregator for agent fleets — TextForAgents LLC

Sell the shed: pre-contract which work can pause, receive a curtailment signal, pause within seconds, get paid for the verified shed.

## Start (self-serve, no operator step)
1. POST /register {"operator": "your-name"} -> {"account_id", "token"} — keep the token; it is your per-customer credential and the ONLY billing/data identity (identity fields in request bodies are ignored for scoping). Identity is canonicalised (NFKC, casefolded, format characters stripped, whitespace collapsed): registering again under a case/whitespace/unicode variant returns the same account and does NOT re-grant the trial.
2. Trial: one simulated curtailment event free, one time per fleet / operator identity. While your trial is unused, run the whole manifest -> history -> probe -> events -> actuals flow as-is (no per-step flag), then POST /settle with "simulated": true (settlement arithmetic is exact, rates are the labeled lab assumptions, no buyer funds move). The trial is burned atomically at settlement; after the burn the engine surface requires the plan — subscribe for the live surface.
3. Paid: POST /subscribe with an x402 X-PAYMENT header of $19.00 activates the Fleet manifest plan for 30 days (manifest registry, baseline engine, readiness probes, curtailment channel, attestations included).
4. POST /manifest {"fleet", "cls", "deferrable", "max_pause_latency_s", "max_event_duration_s", "checkpoint_required", "envelope", "checkpoint_interval_s", "meter_key"} — one shed contract per task class, at most 256 classes per fleet. "meter_key" is your meter's HMAC secret for this class (register it here; it is never echoed back, only its fingerprint). The response carries envelope guidance: default the declared envelope to ≤110% of measured baseline; a looser envelope is an explicit choice whose bounded majority-inflation gain rises to the envelope cap.
5. POST /history {"fleet", "cls", "window_start", "units_per_min", "meter_signature"} — meter windows. meter_signature is REQUIRED: hex HMAC-SHA256, keyed with the class's registered meter_key, over the canonical string fleet|cls|window_start|units_per_min with the numbers in float form (e.g. "F1|batch|1729000000.0|80.0"). Signatures are verified before the window is stored; unsigned or badly signed windows are refused 422. Only verified signed windows timestamped BEFORE manifest registration count toward the baseline (median, capped by the envelope).
6. POST /probe {"fleet", "cls", "position_in_checkpoint_s"} — readiness probe: predicted signal-to-paused latency; capacity payments are gated on the probe pass rate.
7. POST /events {"event_id", "fleet", "classes", "duration_minutes"} — open a curtailment event (non-deferrable-only events refused 422). POST /actuals {"event_id", "cls", "units_per_min"} per event minute. A class that never reports earns exactly 0; a partial stream earns partial shed and the settlement flags stream_complete=false.
8. POST /settle {"event_id"} — two-part settlement: capacity (envelope x $0.50/unit-month x probe pass rate) + event (verified shed x $0.005/unit), aggregator share exactly 15%, fleet keeps 85%. Rates are LABELED ASSUMPTIONS (no buyer price measured, Q4 UNMEASURED). Settling the same event twice is refused 409 (event_id is a spent nonce). The settlement is returned with a signed receipt (verify at POST /receipts/verify; keys at GET /verify-key).
9. Capsules: POST /capsule/park {"fleet", "cls", "consumed", "position"?} -> hash-bound capsule; POST /capsule/resume {"capsule": {...}} -> resume only on revalidation (a tampered capsule is refused).
10. GET /attestation?fleet=&cls= — curtailment-state / deferrability-class check: $0.001/check via x402 (X-PAYMENT header), included on an active manifest plan. Unpaid requests get the exact 402 challenge.
11. GET /baseline?fleet=&cls= — baseline, envelope guidance, and history-window signature counts for your class.
12. A2A: GET /.well-known/agent-card.json — this aggregator's A2A Agent Card (skill: curtailment-signal). Register your agent's A2A endpoint at POST /register {"a2a_endpoint": "https://your-agent/a2a"} or later at POST /a2a-endpoint, and curtailment signals are PUSHED to it as A2A message/send requests carrying a curtailment_signal DataPart when an event opens, and a curtailment_cleared DataPart when it settles; the delivery record rides on the event response and on tasks/get. Another operator/aggregator agent can also open an event for its own fleets by sending the same message/send to POST /a2a with its account token. The fleet worker (src/worker.py) serves its own A2A endpoint and pauses on push — HTTP attestation polling remains as a fallback.
13. MCP: POST /mcp (JSON-RPC) — tools register_manifest, add_history, run_probe, open_event, add_actuals, settle, attestation, capsule_resume — same account token and billing.

## Limits
At most 256 classes per fleet; request bodies capped at 64 KB. Buyer price UNMEASURED: no capacity holder has priced verified agent shed; aggregator-share revenue is $0 if none ever does. Support: support@textforagents.com.

## Prices
Fleet manifest $19/mo per fleet · Aggregator share 15% of capacity + event payments secured · Attestation API $0.001/check (x402). One simulated curtailment event free, one time per fleet. No perpetual free tier.