# API changes and versioning Track API changes, select the published Testnet contracts, and update a trading integration safely. Monitor the [public changelog](https://testnet.polyester.com/docs/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](https://testnet.polyester.com/docs/developer-docs/getting-started/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`](https://testnet.polyester.com/docs/api-docs/connect/changelog.v1.ChangelogService/ListPosts)**\ Use [`GET /v1/changelog/posts`](https://testnet.polyester.com/docs/api-docs/rest/GET/v1/changelog/posts) to discover posts, newest first. Set `limit` to `1` to check the latest post. - **[`GetPost`](https://testnet.polyester.com/docs/api-docs/connect/changelog.v1.ChangelogService/GetPost)**\ Use [`GET /v1/changelog/posts/{slug}`](https://testnet.polyester.com/docs/api-docs/rest/GET/v1/changelog/posts/slug) to read one complete post and its changes. - **[`ListChanges`](https://testnet.polyester.com/docs/api-docs/connect/changelog.v1.ChangelogService/ListChanges)**\ Use [`GET /v1/changelog/changes`](https://testnet.polyester.com/docs/api-docs/rest/GET/v1/changelog/changes) to 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](https://github.com/Fabric-Labs/polyester-proto/tree/testnet). 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`](https://github.com/Fabric-Labs/polyester-proto/blob/testnet/manifest.json). Its `paths` object locates the published artifacts: - **`proto` and `descriptor`**\ 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](https://github.com/Fabric-Labs/polyester-sdk-typescript/releases), [Python](https://github.com/Fabric-Labs/polyester-sdk-python/releases), [Go](https://github.com/Fabric-Labs/polyester-sdk-go/releases), and [Rust](https://github.com/Fabric-Labs/polyester-sdk-rust/releases). 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 1. 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. 2. 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. 3. 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. 4. 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](https://testnet.polyester.com/docs/developer-docs/getting-started/market-maker-guide) as a checklist.