API

Six gRPC services in sweetspot.api.v1. MarketDataService, StatsService, HistoricalService, and AuthService are public. MakerService and TxService require credentials.

Service	Auth	What you use it for
AuthService	none	Mint or revoke bearer session tokens.
MarketDataService	none	Stream books, fills, market snapshots; list pairs; snapshot a single book.
StatsService	none	Public aggregate stats — summary, volume breakdown/series, asset TVLs.
HistoricalService	none	ClickHouse-backed historical trades + candles.
MakerService	bearer session or org API key	Per-maker balances, fills, market snapshots, volume, and activity stats.
TxService	keypair bearer session	Submit signed transactions, stream blockhash + tx status.

Each is fully wire-compatible with vanilla gRPC and gRPC-Web on the same URL. Pick whichever transport fits your stack — the SDKs hide the difference.

Schema

• api.proto — bundled protobuf source covering every service in the package. Use the checked-in proto/ tree when you want a per-service slice.
• openapi.yaml — OpenAPI 3.1 schema for the same service URLs used by gRPC-Web clients, suitable for Postman, Insomnia, Stoplight, or client-generation tools.

CI fails the build if these files diverge from the upstream proto.

URL convention

POST https://<host>/sweetspot.api.v1.<Service>/<Method>
Content-Type: application/grpc             (gRPC binary, hot path)
              application/grpc-web+proto   (browser-native)

No URL params, no path-based versioning beyond the package name.

Authentication

MarketDataService, StatsService, HistoricalService, and AuthService are open. MakerService and TxService expect:

authorization: Bearer <session_token>

Mint a keypair token via AuthService.Challenge → sign → Authenticate. MakerService also accepts passwordless organization sessions and organization API keys. See the Auth flow recipe for the per-SDK helpers.