Authentication model

Programmatic access uses Ed25519 API keys. The SDK signs each authenticated request.

Credentials

Use the Account ID string exactly as shown. Do not use internal numeric ids. Account-ID authentication is valid even when the account has no username; username is optional profile metadata, not an authentication requirement or a value that must be set to "-".

Signing (what the SDK does)

For each authenticated unary call the SDK builds a signature over:

timestamp_ms
METHOD
pathname
canonical_query
hex(sha256(body))

and sends headers X-API-KEY-ID, X-API-TIMESTAMP, X-API-SIGNATURE.

The client allocates a distinct timestamp for every call, including concurrent identical calls, so replay protection does not confuse them. You normally never assemble this yourself; pass credentials via polyester.Config. Credential copies for the same key share the process allocator. Automatic timestamps may lead the local wall clock by at most five seconds, leaving half of the API's 10-second freshness window for clock and network skew. A burst that exhausts that capacity is backpressured; prolonged exhaustion returns a retryable *errors.RateLimitError instead of reusing an authentication tuple.

Deep dive: Ed25519 API keys and API key replay policy.

Public vs private

• Public market-data calls work with no key.
• Private RPCs and private WebSocket channels need a key and Account ID.
• Consume private streams with Messages(), Go has no Recv().
• Hyphenated channel segments (for example api-keys, api-policies) are signed with RFC 3986 unreserved-preserving query encoding (- _ . ~ stay unescaped). The SDK does this via url.QueryEscape / Centrifugo token fetch, do not re-encode hyphens as %2D yourself.

Key lifecycle on this SDK

Guide: Authentication.

Related Topics