TESTNET

REST Guide

REST is the HTTP-first interface for Polyester and is production-supported for real exchange integrations.

It is often the fastest way to ship because payloads are readable, tooling is familiar, and integration teams can debug quickly.

REST is first-class

REST is not a second-tier interface. Use it confidently in production when it matches your workload and team tooling.

When to use REST

Choose REST when you want:

  • simple HTTP integration with broad ecosystem support

  • human-readable request/response payloads

  • easier debugging with existing API tools

  • fast onboarding for teams that already know exchange REST patterns

If you later need tighter transport efficiency, you can move selected flows to ConnectRPC without changing business logic.

Signing private requests

  • no API-key signature required

  • ideal for market data and discovery flows

Use the full signing guide here: Ed25519 API keys. Replay policy and latency tradeoffs are documented here: API Key Replay Policy.

Pagination patterns

REST endpoints use multiple pagination styles depending on data shape and endpoint semantics.

Pattern

Request fields

Response fields

Notes

Opaque cursor token

limit, page_token

next_page_token

Do not parse the token client-side; treat as opaque.

Time cursor

limit, before_ts_ns or since

next_before_ts_ns or next_cursor

Common for history/event timelines.

Offset pagination

limit, offset

total (or equivalent)

Practical for list views; can drift on rapidly changing datasets.

General guidance:

  • keep page sizes bounded and predictable

  • always use the server-provided next cursor/token instead of constructing your own

  • stop paginating when the next cursor/token is empty or zero (endpoint dependent)

Common REST integration patterns

  • Readable payloads: decimal strings and text identifiers are common on REST surfaces for developer ergonomics.

  • Idempotent writes: for endpoints that support request IDs, use stable request IDs to make retries safe.

  • Retry discipline: retry transient failures with bounded backoff and jitter; do not blindly retry validation or auth errors.

  • Transport hygiene: reuse HTTP connections and keep request/response handling lightweight.

REST JSON handling is optimized for production performance, while still keeping payloads easy to inspect.

ConnectRPC vs REST

  • readability and compatibility matter most

  • your team already has strong REST operational tooling

  • you want straightforward request inspection in production workflows

Interfaces & Transports roadmap

  • ConnectRPC guide (clients, metadata, retries) - available

  • REST guide (signing, pagination, common patterns) - this page

  • WebSocket guide (public vs private, subscribe model) - planned

  • Proto vs JSON mapping (Proto = Protocol Buffers, JSON = JavaScript Object Notation) - planned

  • Compression & performance tips (payload size, batching) - planned

  • FIX planned overview (FIX = Financial Information eXchange) - planned

  • SBE planned overview (SBE = Simple Binary Encoding) - planned

Previous

API Key Replay Policy