# Superis — Sweetspot client SDKs

> Off-chain market-data + trading API for the Sweetspot on-chain spot DEX
> on Solana. Five gRPC services in `sweetspot.api.v1`: AuthService,
> MarketDataService, BalanceService, TxService, HistoricalService.
> Official client SDKs in Rust (tonic), Go (grpc-go), and TypeScript-web
> (@connectrpc/connect-web). Wire-compatible with any vanilla gRPC client.

The schema lives in `proto/sweetspot/api/v1/`. Decimal money values are
always strings on the wire (e.g. `"155.14"`). Authenticated services
require a session token via `authorization: Bearer <token>` metadata —
mint one with the AuthService signed-nonce flow (`Challenge → sign →
Authenticate`). MarketDataService is public.

## Schema

- [api.proto](https://superis.github.io/superis-clients/api.proto): Bundled proto (common + auth + market_data) — single-file copy for codegen tools.
- [openapi.json](https://superis.github.io/superis-clients/openapi.json): OpenAPI 3.1 spec — JSON form, used by the API reference renderer.
- [openapi.yaml](https://superis.github.io/superis-clients/openapi.yaml): OpenAPI 3.1 spec — YAML form, for Postman / Insomnia / generic codegen.

## Overview

- [Exchange](https://superis.github.io/superis-clients/overview/exchange): On-chain market structure, swap modes (global vs cross), oracle-offset quoting, lot/atom unit system, live-vs-historical routing.
- [Architecture](https://superis.github.io/superis-clients/overview/architecture): How sweetspot-server derives the API from Solana accounts; tonic vs Connect rationale.
- [Prices, sizes, units](https://superis.github.io/superis-clients/overview/units): Decimal-string contract; timestamp + enum conventions.
- [Errors](https://superis.github.io/superis-clients/overview/errors): gRPC status codes + retry guidance.

## API

- [API overview](https://superis.github.io/superis-clients/api/): Five services, URL convention, schema downloads.
- [Reference](https://superis.github.io/superis-clients/api/reference): Per-endpoint request/response, try-it-now, rendered from openapi.json via vitepress-openapi.
- [Proto schema](https://superis.github.io/superis-clients/api/schema): Inline syntax-highlighted proto.
- [Protocols & transports](https://superis.github.io/superis-clients/api/transports): gRPC / gRPC-Web / Connect on the same URL; binary vs JSON; per-SDK defaults.
- [WebSocket feed](https://superis.github.io/superis-clients/api/feed): Legacy streaming protocol — full message catalog and SDK snippets.

## SDK guides

- [Rust SDK](https://superis.github.io/superis-clients/sdks/rust): Install, quickstart, configuration, error handling, decimal parsing.
- [Go SDK](https://superis.github.io/superis-clients/sdks/go): Same, for grpc-go consumers.
- [TypeScript-web SDK](https://superis.github.io/superis-clients/sdks/typescript): ESM-only browser SDK, custom transports, Connect interceptors.

## Recipes

- [Auth flow](https://superis.github.io/superis-clients/sdks/auth): The full Challenge → sign → Authenticate cycle in all three SDKs; refresh strategy; revoke; WalletSigner contract.
- [Polling vs streaming](https://superis.github.io/superis-clients/sdks/polling): When to use REST/Connect snapshots vs gRPC streams.
- [Historical queries](https://superis.github.io/superis-clients/sdks/historical): ClickHouse-backed range queries; pagination recipe; live + historical stitching.

## LLM-friendly bundles

- [llms-full.txt](https://superis.github.io/superis-clients/llms-full.txt): Every overview, API, SDK, and recipe page concatenated into a single Markdown file. Drop into a Claude / GPT / Gemini context to ground completions in the canonical docs.