/v1. Within v1, changes are additive: an integration that follows the rules below keeps working as the API grows.
Changes within v1
These can happen at any time, without notice:- New endpoints and new stream channels.
- New optional request parameters and filter fields.
- New fields in responses and stream updates.
- New error codes.
- New chains.
- New values in open sets, such as a trade’s
flags, a token’sdexesandlaunchpad, a platform’splatform, and an identity’ssource.
Changes that need a new version
These never happen withinv1. They would ship under a new path, such as /v2:
- Removing or renaming a field.
- Changing a field’s type or unit.
- Changing what an error code means.
- Removing a chain.
Write a client that keeps working
- Ignore unknown fields. Do not reject a response because it carries a field you did not expect.
- Keep unknown values. When a value in an open set is new to you, store or skip it, but do not fail.
- Fall back on the status. When an error
codeis new to you, handle the response by its HTTP status. - Generate clients leniently. The OpenAPI document publishes trade
flagsas plain strings, but it still publisheschain, an identity’ssourceand a platform’splatformas closed enums. Configure your generator to accept unknown enum values, or treat these fields as strings, so a new value does not break deserialization.