Monitor the public changelog and pin the contracts and SDK your integration uses.
Testnet runs the latest release at api.testnet.polyester.com. Mainnet is coming soon;
see Environments and hosts.
Before v1
Before v1, a release may include breaking API changes. Breaking changes are announced in the changelog. Fields are removed rather than deprecated, so do not rely on a deprecation period before updating an integration.
A v1 package name or /v1/ URL does not override this pre-v1 release policy. Review the
announced changes when Testnet is upgraded, including changes to request fields, response
interpretation, and trading behavior.
Read the changelog programmatically
changelog.v1.ChangelogService provides the published changelog for the environment you query.
It is public and does not require authentication.
ListPosts
UseGET /v1/changelog/poststo discover posts, newest first. Setlimitto1to check the latest post.GetPost
UseGET /v1/changelog/posts/{slug}to read one complete post and its changes.ListChanges
UseGET /v1/changelog/changesto query individual changes across posts.
For a bot's release monitor, query changes since the last reviewed publication time. Filter for BREAKING_CHANGE or action-required entries when triaging migrations. Read migrationGuidance on REST, or migration_guidance on ConnectRPC, when present.
Audience filters can select developers and market makers; changes addressed to all users also match. Filters on different fields combine with AND, so an API surface filter can exclude relevant funding or trading changes. Keep an unfiltered review of the changelog too.
Follow nextPageToken on REST or next_page_token on ConnectRPC until it is empty. Reuse a
page token only with the same filters, time bounds, and sort. If several posts appeared since
your last check, process every intervening page before advancing your saved review position.
Use the published Testnet contracts
Public contracts are published per environment in polyester-proto.
Use its testnet branch for Testnet. A branch advances with releases; save the commit you
generate from so a later build uses the same inputs.
Start with the branch's manifest.json.
Its paths object locates the published artifacts:
protoanddescriptor
Public Protobuf definitions and their compiled descriptor set for generated clients.openapi
Published OpenAPI documents for REST client generation.sbe
The schema for the SBE trade WebSocket.docs
Generated API reference data, when included.
publicDescriptorSha256 fingerprints the compiled public Protobuf descriptor. A changed hash
signals a descriptor change; an unchanged hash does not establish that every API artifact or
customer-visible behavior is unchanged. Review the changelog and the artifacts your integration uses.
Generate custom clients from these published contracts. Use the REST OpenAPI document for REST and the public Protobuf definitions for ConnectRPC. Keep the manifest and selected artifacts from the same commit together.
Follow SDK releases
Check your SDK's release notes alongside the Polyester changelog. SDK releases describe client changes; the environment's contracts describe the API your client must call.
Official SDK releases are available for TypeScript, Python, Go, and Rust.
The SDK manifest records publicDescriptorSha256, which you can compare with the Testnet
contract manifest when checking the generated API definitions.
Pin an exact SDK version and commit your dependency lockfile where your tooling supports one. For a source dependency, pin a tag or commit rather than a moving branch. A local version pin makes builds reproducible; it does not hold Testnet on an older server release.
Keep an integration ready for changes
Watch for releases
Review the changelog regularly and before enabling a strategy after an upgrade. Record the last reviewed publication and inspect breaking changes, action-required entries, and migration guidance.
Compare and update deliberately
Compare the current Testnet manifest and contracts with your saved versions. Update your pinned SDK, or regenerate your client from the published contracts, then adapt affected requests and response handling.
Accept additive responses safely
Ignore response fields your client does not use. Handle unknown enum values with an explicit fallback instead of crashing or treating an unfamiliar order or payout state as success. Check generated-client and JSON-decoder settings so new fields do not reject otherwise usable responses.
Exercise the affected strategy flows
Test the changed operations on Testnet before resuming automated trading. Include the order, cancel, balance, and transfer flows your strategy depends on, and verify its error handling. Use the market maker guide as a checklist.
