BYO Data API Plan

The data API is the programmatic access layer for BYO signals and receipts. It is planned for Phase 2 and sits beside dashboard access and alert delivery.

⚠️

Roadmap - Phase 2. Endpoints, limits, pricing, and plan inclusion below are draft product design, not live API terms.

Who is it for?

User	API use
Renters	Read historical receipts before renting, fetch active rental signals, subscribe to realtime delivery, and route events into their own tools.
Creators	Inspect their own source receipts, monitor scoring, debug rejected signals, review uptime/incident history, and manage outbound delivery settings.
Public readers	Access limited public receipts and status metadata where a listing exposes them.

Creators still push signals through the Signal Source ingest endpoint. The data API is mainly for reading, subscribing, and delivery.

Draft API surfaces

Capability	Draft endpoint / mechanism	Access
List public receipts	`GET /v1/byo/sources/:source_id/receipts`	Public or renter, depending listing settings
Fetch one receipt	`GET /v1/byo/receipts/:receipt_id`	Public/renter/creator
Fetch source status	`GET /v1/byo/sources/:source_id/status`	Public metadata
Fetch rental signals	`GET /v1/rentals/:rental_id/signals`	Active renter
Realtime stream	`GET /v1/rentals/:rental_id/events` using SSE	Active renter
Outbound webhook	`POST` to renter-provided URL	Active renter plan
Creator diagnostics	`GET /v1/byo/sources/:source_id/ingest-errors`	Source operator

Historical signals and receipts

Historical access should support:

Filter by source, Agent shell, token, severity, outcome, time window, and status.
Cursor pagination.
Receipt detail including emitted time, recorded time, scoring windows, baseline, outcome, and dispute/slash status.
Public receipt access before rent where the listing allows it.
Active-rental access to the full live feed for the rented Agent/source combination.

Example:

GET /v1/byo/sources/src_42/receipts?from=2026-06-01T00:00:00Z&outcome=hit&limit=50

Realtime subscriptions

Realtime API delivery is planned for renters who need machine-readable signals:

Mode	Use
SSE event feed	Simple server-to-client stream for dashboards, bots, and scripts.
Outbound webhook	Sandbox GHI pushes JSON events to the renter's endpoint.
API polling	Fallback for clients that cannot keep a stream open.

Draft event:

{
  "event": "byo.signal.accepted",
  "rental_id": "rent_123",
  "source_id": "src_42",
  "signal_id": "src_42_0001931",
  "token": "ABC",
  "severity": "elevated",
  "emitted_at": "2026-06-19T12:00:00Z",
  "received_at": "2026-06-19T12:00:03Z"
}

Is API access included in rentals?

Draft packaging:

Plan surface	Included by default?
Dashboard receipt viewing	Yes for active renters; limited public view before rent
In-app alert feed	Yes for active renters
Basic historical receipt API	May be included with rental
Realtime SSE/API stream	May require API-enabled rental plan
Outbound webhook delivery	Metered or premium plan
High-volume export	Metered add-on

Final plan terms will be shown before rental checkout.

Rate limits and metering

Draft limits:

API type	Draft limit
Public receipt reads	Lower anonymous/IP-based limit
Active renter reads	Higher per-wallet/per-rental limit
Realtime stream	Limited concurrent streams per rental
Outbound webhook retries	Backoff + max retry window
Bulk export	Metered by rows/events delivered

Premium delivery channels, API streams, webhooks, SMS, and high-volume exports may be metered in $SGHI or another supported payment unit. Metering covers marginal delivery cost; it does not guarantee trading outcome.

Privacy and access boundaries

API users can read receipts and events they are entitled to see.
Renters do not receive creator source code, private wallet lists, API keys, signing keys, or model internals.
Public receipts can redact fields that would leak private alpha beyond the intended signal record.
Creator diagnostics are private to the source operator and protocol review process.

💡

The data API should answer: can I verify the record, fetch receipts, and route live rental events into my own system? It should not turn a rental into ownership of the creator's source.

→ Next: Service Reliability - how heartbeat, downtime, and delivery status affect API and alert access.

Renter View Service Reliability