TESTNET
Connect

Regions and connectivity

Testnet is Polyester's public environment and runs the latest release. Mainnet is coming soon. Start with https://api.testnet.polyester.com for REST, ConnectRPC, and realtime access. Use the separate trade host for SBE and Protobuf order entry.

This page helps you choose and operate a connection. For interface selection, see the connectivity matrix. For environment and contract details, see environments and hosts.

Choose an API host

The global API host is the default entry point. A regional hostname gives your client an explicit regional entry point. Choose one when you need to configure that entry point yourself and test connectivity from your own infrastructure.

  • Global
    https://api.testnet.polyester.com
  • EU West · bru
    https://bru.api.testnet.polyester.com
  • US East · iad
    https://iad.api.testnet.polyester.com
  • US West · pdx
    https://pdx.api.testnet.polyester.com
  • Tokyo · tyo
    https://tyo.api.testnet.polyester.com

These API hosts serve the same REST, ConnectRPC, and realtime routes. Changing the API host does not change your account, API-key permissions, or request format. Configure the host separately from the operation path so switching hosts does not change the request body.

For a public read, use GET /v1/spot/config or GetSpotConfig. Keep TLS certificate verification enabled and connect by hostname rather than a resolved IP address.

Use the trade host for order entry

Both binary trade WebSockets use trade.api.testnet.polyester.com:

  • SBE order entry
    wss://trade.api.testnet.polyester.com/ws/trade.sbe
  • Protobuf order entry
    wss://trade.api.testnet.polyester.com/ws/trade.proto

The global and regional API hosts do not serve these trade paths. The trade host is not a replacement base URL for REST, ConnectRPC, or realtime subscriptions. There are no regional trade hostnames in the public connection contract.

Authenticate the trade WebSocket upgrade with an Ed25519 API key. A user session JWT cannot authenticate this upgrade. Keep the socket open for successive commands instead of opening one per order. See SBE connection and authentication for signing, heartbeats, sequencing, and recovery. The Protobuf trade interface uses its own message encoding on the trade path above.

Connect realtime streams

Use the global API host or your chosen regional API host with wss://:

  • Market data and account events
    wss://api.testnet.polyester.com/connection/websocket
    Carries market subscriptions and authorized private streams such as balances, trades, transfers, and trigger events.
  • Private order updates
    wss://api.testnet.polyester.com/v1/ws/private
    Carries your orders, fills, and command outcomes. See Private WebSocket.

Replace only the hostname to use a regional API endpoint. These are subscription connections; choose REST, ConnectRPC, or a trade WebSocket to submit order commands.

Obtain connection and subscription tokens through /v1/rt/token and /v1/rt/subscribe on the API host. Use the authentication and refresh flow for the stream you selected. These tokens are distinct from a partner app's login JWT and from an API key's signing credentials.

Reuse connections

Keep a long-lived HTTP client and connection pool for REST and ConnectRPC. Enable connection reuse and consume or close response bodies so the client can return connections to its pool. Creating a new client for every request repeatedly pays connection and TLS setup costs.

The public API endpoints accept HTTPS requests over HTTP/2 and HTTP/1.1. Allow HTTP/2 negotiation when your client supports it; multiplex requests on that connection. With HTTP/1.1, use persistent keep-alive connections and a pool suited to your concurrent workload.

WebSocket routes use a GET upgrade handshake. Use a WebSocket client that supports the HTTP/1.1 Upgrade: websocket flow. An HTTP/2 connection for API requests does not replace a WebSocket connection, and ConnectRPC's Protobuf encoding does not itself require HTTP/2.

Idle HTTP connections can close. Let the pool replace them and keep request deadlines separate from idle-connection settings. For WebSockets, follow the interface's heartbeat or ping/pong contract and keep reading while commands are in flight.

Synchronize clocks and allow network access

Synchronize your signing hosts with a reliable time source, such as NTP, and monitor drift. API-key signatures are time-bound, including signed trade WebSocket upgrades. Generate the timestamp and signature close to transmission, after any deliberate retry delay.

For TIMESTAMP_SKEW or AUTH_TIMESTAMP_SKEW, correct the clock and sign again. Reusing the same signed upgrade after a disconnect can also fail replay protection. Follow Ed25519 API keys for the exact signing and timestamp rules.

If an API key has an IP allowlist, authorize the public egress addresses your clients actually use. Include failover egress paths before relying on them. Changing the destination API region does not add your client's source address to the allowlist. See API key IP allowlists.

Reconnect with backoff

Use exponential backoff with jitter and a maximum delay for transient connection failures. Honor Retry-After when present. Stagger reconnects across your clients so a disconnect does not trigger simultaneous retries. A regional fallback should be an explicit, tested client policy.

After a realtime reconnect, obtain valid tokens, restore subscriptions, and resume from the last applied cursor where supported. If recovery is refused or a gap is detected, reload the required snapshot or history before treating local state as current.

After a trade WebSocket disconnect, sign a new upgrade and follow that interface's sequence rules. Reconcile commands with uncertain outcomes before resending them. A lost connection does not prove that an order was rejected or cancelled.

Fix authentication, permissions, allowlist denials, and malformed requests before retrying. For a 403, inspect the response: an access challenge before the API or WebSocket opens is different from a Polyester permission error. See troubleshooting, error responses, and error codes.

Developer documentation Start here to integrate with Polyester: the integration path, the interfaces, the guide sections, and where the API reference fits. Quickstart Create a Testnet API key, fund your account, and place, read, and cancel your first limit order with an official SDK or raw HTTP. Testnet funds Claim test Assets programmatically, test deposits from other Networks, and fund Subaccounts for trading strategies. Environments and hosts Polyester's environments, the public host for each interface, where each environment's contracts are published, and the conventions every API shares. Connectivity matrix Choose the Polyester interfaces for your workload by comparing traffic pattern, encoding, and client path. Market maker guide An end-to-end checklist for running a quoting system on Polyester, with links to the page that owns each topic. Build a trading bot Build a small two-sided quoting bot on Testnet with the official Python SDK, from keys and Pair rules to a clean shutdown. SDK capability matrix Compare official Polyester SDK capability coverage across TypeScript, Python, Go, and Rust. API changes and versioning Track API changes, select the published Testnet contracts, and update a trading integration safely. Other APIs Find profile, social verification, analytics, rewards, changelog, and QuickSwap APIs beyond the trading guides. Troubleshooting Diagnose authentication failures, rejected orders, uncertain writes, and stream interruptions in a Polyester integration.
Previous

Environments and hosts
Next

Connectivity matrix