API

Five gRPC services in sweetspot.api.v1. One is unauthenticated; the rest require a session token from AuthService.Authenticate.

Service	Auth	What you use it for
AuthService	none	Sign in once with your pubkey, get a bearer token.
MarketDataService	none	Stream books, fills, list pairs, snapshot a single book.
BalanceService	yes	Per-maker balances — current snapshot or live stream.
TxService	yes	Submit signed transactions, stream blockhash + tx status.
HistoricalService	yes	ClickHouse-backed historical trades + candles.

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

Schema

• api.proto — protobuf source. Drop into your codegen tool.
• openapi.yaml — OpenAPI 3.1 spec. For Postman, Insomnia, Stoplight, or generating clients in languages we don't ship.
• openapi.json — same as YAML, JSON-encoded.

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/proto       (gRPC binary, hot path)
              application/grpc-web    (browser-native)
              application/json        (Connect-JSON, curl-friendly)

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

Authentication

MarketDataService is open. Every other service expects:

authorization: Bearer <session_token>

Mint a token via AuthService.Challenge → sign → Authenticate. See the Auth flow recipe — every SDK ships a one-line helper that handles refresh.