compass_api_sdk 2.2.65__tar.gz → 2.2.66__tar.gz

{compass_api_sdk-2.2.65 → compass_api_sdk-2.2.66}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compass_api_sdk
-Version: 2.2.65
+Version: 2.2.66
 Summary: Compass API SDK.
 Author: royalnine
 Requires-Python: >=3.10
@@ -295,6 +295,7 @@ with CompassAPI(
 * [global_markets_perps_approve_builder_fee](docs/sdks/globalmarketsperps/README.md#global_markets_perps_approve_builder_fee) - Approve builder fee
 * [global_markets_perps_enable_unified_account](docs/sdks/globalmarketsperps/README.md#global_markets_perps_enable_unified_account) - Enable unified account mode
 * [global_markets_perps_ensure_leverage](docs/sdks/globalmarketsperps/README.md#global_markets_perps_ensure_leverage) - Ensure 1x cross leverage
+* [global_markets_perps_set_leverage](docs/sdks/globalmarketsperps/README.md#global_markets_perps_set_leverage) - Set leverage (defaults to market maximum)
 
 ### [Morpho](docs/sdks/morpho/README.md)
 
@@ -497,8 +498,8 @@ with CompassAPI(
 
 
 **Inherit from [`CompassAPIError`](./src/compass_api_sdk/errors/compassapierror.py)**:
-* [`TokenizedAssetsErrorResponse`](./src/compass_api_sdk/errors/tokenizedassetserrorresponse.py): Standard error envelope returned by every non-2xx response.  Surfaced in OpenAPI ``responses`` declarations so SDK consumers can decode failures uniformly without inspecting per-status-code shapes. Applicable to 11 of 129 methods.*
-* [`MintPrepareNotFoundResponseError`](./src/compass_api_sdk/errors/mintpreparenotfoundresponseerror.py): Response when the burn event has not been found yet.  This means the burn transaction hasn't been confirmed on-chain yet, or the user hasn't broadcast the burn transaction. Status code `404`. Applicable to 1 of 129 methods.*
+* [`TokenizedAssetsErrorResponse`](./src/compass_api_sdk/errors/tokenizedassetserrorresponse.py): Standard error envelope returned by every non-2xx response.  Surfaced in OpenAPI ``responses`` declarations so SDK consumers can decode failures uniformly without inspecting per-status-code shapes. Applicable to 11 of 130 methods.*
+* [`MintPrepareNotFoundResponseError`](./src/compass_api_sdk/errors/mintpreparenotfoundresponseerror.py): Response when the burn event has not been found yet.  This means the burn transaction hasn't been confirmed on-chain yet, or the user hasn't broadcast the burn transaction. Status code `404`. Applicable to 1 of 130 methods.*
 * [`ResponseValidationError`](./src/compass_api_sdk/errors/responsevalidationerror.py): Type mismatch between the response data and the expected Pydantic model. Provides access to the Pydantic validation error via the `cause` attribute.
 
 </details>

{compass_api_sdk-2.2.65 → compass_api_sdk-2.2.66}/README-PYPI.md

@@ -277,6 +277,7 @@ with CompassAPI(
 * [global_markets_perps_approve_builder_fee](docs/sdks/globalmarketsperps/README.md#global_markets_perps_approve_builder_fee) - Approve builder fee
 * [global_markets_perps_enable_unified_account](docs/sdks/globalmarketsperps/README.md#global_markets_perps_enable_unified_account) - Enable unified account mode
 * [global_markets_perps_ensure_leverage](docs/sdks/globalmarketsperps/README.md#global_markets_perps_ensure_leverage) - Ensure 1x cross leverage
+* [global_markets_perps_set_leverage](docs/sdks/globalmarketsperps/README.md#global_markets_perps_set_leverage) - Set leverage (defaults to market maximum)
 
 ### [Morpho](docs/sdks/morpho/README.md)
 
@@ -479,8 +480,8 @@ with CompassAPI(
 
 
 **Inherit from [`CompassAPIError`](./src/compass_api_sdk/errors/compassapierror.py)**:
-* [`TokenizedAssetsErrorResponse`](./src/compass_api_sdk/errors/tokenizedassetserrorresponse.py): Standard error envelope returned by every non-2xx response.  Surfaced in OpenAPI ``responses`` declarations so SDK consumers can decode failures uniformly without inspecting per-status-code shapes. Applicable to 11 of 129 methods.*
-* [`MintPrepareNotFoundResponseError`](./src/compass_api_sdk/errors/mintpreparenotfoundresponseerror.py): Response when the burn event has not been found yet.  This means the burn transaction hasn't been confirmed on-chain yet, or the user hasn't broadcast the burn transaction. Status code `404`. Applicable to 1 of 129 methods.*
+* [`TokenizedAssetsErrorResponse`](./src/compass_api_sdk/errors/tokenizedassetserrorresponse.py): Standard error envelope returned by every non-2xx response.  Surfaced in OpenAPI ``responses`` declarations so SDK consumers can decode failures uniformly without inspecting per-status-code shapes. Applicable to 11 of 130 methods.*
+* [`MintPrepareNotFoundResponseError`](./src/compass_api_sdk/errors/mintpreparenotfoundresponseerror.py): Response when the burn event has not been found yet.  This means the burn transaction hasn't been confirmed on-chain yet, or the user hasn't broadcast the burn transaction. Status code `404`. Applicable to 1 of 130 methods.*
 * [`ResponseValidationError`](./src/compass_api_sdk/errors/responsevalidationerror.py): Type mismatch between the response data and the expected Pydantic model. Provides access to the Pydantic validation error via the `cause` attribute.
 
 </details>

{compass_api_sdk-2.2.65 → compass_api_sdk-2.2.66}/pyproject.toml

@@ -1,7 +1,7 @@
 
 [project]
 name = "compass_api_sdk"
-version = "2.2.65"
+version = "2.2.66"
 description = "Compass API SDK."
 authors = [{ name = "royalnine" },]
 readme = "README-PYPI.md"
@@ -14,7 +14,7 @@ dependencies = [
 
 [tool.poetry]
 name = "compass_api_sdk"
-version = "2.2.65"
+version = "2.2.66"
 description = "Compass API SDK."
 authors = ["Compass Labs"]
 repository = "https://github.com/CompassLabs/mono.git"

{compass_api_sdk-2.2.65 → compass_api_sdk-2.2.66}/src/compass_api_sdk/_version.py

@@ -5,8 +5,8 @@ import importlib.metadata
 __title__: str = "compass_api_sdk"
 __version__: str = "2.0.0"
 __openapi_doc_version__: str = "0.0.1"
-__gen_version__: str = "2.906.0"
-__user_agent__: str = "speakeasy-sdk/python 2.0.0 2.906.0 0.0.1 compass_api_sdk"
+__gen_version__: str = "2.910.1"
+__user_agent__: str = "speakeasy-sdk/python 2.0.0 2.910.1 0.0.1 compass_api_sdk"
 
 try:
     if __package__ is not None:

{compass_api_sdk-2.2.65 → compass_api_sdk-2.2.66}/src/compass_api_sdk/global_markets_perps.py

@@ -3028,3 +3028,221 @@ class GlobalMarketsPerps(BaseSDK):
             raise errors.APIError("API error occurred", http_res, http_res_text)
 
         raise errors.APIError("Unexpected response received", http_res)
+
+    def global_markets_perps_set_leverage(
+        self,
+        *,
+        owner: str,
+        asset: str,
+        leverage: OptionalNullable[int] = UNSET,
+        retries: OptionalNullable[utils.RetryConfig] = UNSET,
+        server_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        http_headers: Optional[Mapping[str, str]] = None,
+    ) -> models.GlobalMarketsPerpsSetLeverageResponse:
+        r"""Set leverage (defaults to market maximum)
+
+        Check leverage and prepare an updateLeverage action to the requested value.
+
+        If `leverage` is omitted, targets the asset's maximum leverage for that
+        market. If the asset is already at the requested leverage, returns
+        leverage_ok=true with null typed_data — no signing needed. Otherwise,
+        returns EIP-712 typed data for the user to sign. After signing, submit the
+        signature via the /execute endpoint.
+
+        :param owner: User's EOA address
+        :param asset: Asset ticker (e.g. 'AAPL', 'CL')
+        :param leverage: Target leverage as a whole-number multiplier. Omit (or pass null) to use the asset's maximum leverage. Must be between 1 and the asset's max leverage, which is available from the /opportunities endpoint.
+        :param retries: Override the default retry configuration for this method
+        :param server_url: Override the default server URL for this method
+        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
+        :param http_headers: Additional headers to set or replace on requests.
+        """
+        base_url = None
+        url_variables = None
+        if timeout_ms is None:
+            timeout_ms = self.sdk_configuration.timeout_ms
+
+        if server_url is not None:
+            base_url = server_url
+        else:
+            base_url = self._get_url(base_url, url_variables)
+
+        request = models.GlobalMarketsPerpsSetLeverageRequest(
+            owner=owner,
+            asset=asset,
+            leverage=leverage,
+        )
+
+        req = self._build_request(
+            method="POST",
+            path="/v2/global_markets_perps/set_leverage",
+            base_url=base_url,
+            url_variables=url_variables,
+            request=request,
+            request_body_required=True,
+            request_has_path_params=False,
+            request_has_query_params=True,
+            user_agent_header="user-agent",
+            accept_header_value="application/json",
+            http_headers=http_headers,
+            security=self.sdk_configuration.security,
+            get_serialized_body=lambda: utils.serialize_request_body(
+                request,
+                False,
+                False,
+                "json",
+                models.GlobalMarketsPerpsSetLeverageRequest,
+            ),
+            allow_empty_value=None,
+            timeout_ms=timeout_ms,
+        )
+
+        if retries == UNSET:
+            if self.sdk_configuration.retry_config is not UNSET:
+                retries = self.sdk_configuration.retry_config
+
+        retry_config = None
+        if isinstance(retries, utils.RetryConfig):
+            retry_config = (retries, ["429", "500", "502", "503", "504"])
+
+        http_res = self.do_request(
+            hook_ctx=HookContext(
+                config=self.sdk_configuration,
+                base_url=base_url or "",
+                operation_id="v2_global_markets_perps_set_leverage",
+                oauth2_scopes=None,
+                security_source=self.sdk_configuration.security,
+            ),
+            request=req,
+            is_error_status_code=lambda c: utils.match_status_codes(["4XX", "5XX"], c),
+            retry_config=retry_config,
+        )
+
+        response_data: Any = None
+        if utils.match_response(http_res, "200", "application/json"):
+            return unmarshal_json_response(
+                models.GlobalMarketsPerpsSetLeverageResponse, http_res
+            )
+        if utils.match_response(http_res, "422", "application/json"):
+            response_data = unmarshal_json_response(
+                errors.HTTPValidationErrorData, http_res
+            )
+            raise errors.HTTPValidationError(response_data, http_res)
+        if utils.match_response(http_res, "4XX", "*"):
+            http_res_text = utils.stream_to_text(http_res)
+            raise errors.APIError("API error occurred", http_res, http_res_text)
+        if utils.match_response(http_res, "5XX", "*"):
+            http_res_text = utils.stream_to_text(http_res)
+            raise errors.APIError("API error occurred", http_res, http_res_text)
+
+        raise errors.APIError("Unexpected response received", http_res)
+
+    async def global_markets_perps_set_leverage_async(
+        self,
+        *,
+        owner: str,
+        asset: str,
+        leverage: OptionalNullable[int] = UNSET,
+        retries: OptionalNullable[utils.RetryConfig] = UNSET,
+        server_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        http_headers: Optional[Mapping[str, str]] = None,
+    ) -> models.GlobalMarketsPerpsSetLeverageResponse:
+        r"""Set leverage (defaults to market maximum)
+
+        Check leverage and prepare an updateLeverage action to the requested value.
+
+        If `leverage` is omitted, targets the asset's maximum leverage for that
+        market. If the asset is already at the requested leverage, returns
+        leverage_ok=true with null typed_data — no signing needed. Otherwise,
+        returns EIP-712 typed data for the user to sign. After signing, submit the
+        signature via the /execute endpoint.
+
+        :param owner: User's EOA address
+        :param asset: Asset ticker (e.g. 'AAPL', 'CL')
+        :param leverage: Target leverage as a whole-number multiplier. Omit (or pass null) to use the asset's maximum leverage. Must be between 1 and the asset's max leverage, which is available from the /opportunities endpoint.
+        :param retries: Override the default retry configuration for this method
+        :param server_url: Override the default server URL for this method
+        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
+        :param http_headers: Additional headers to set or replace on requests.
+        """
+        base_url = None
+        url_variables = None
+        if timeout_ms is None:
+            timeout_ms = self.sdk_configuration.timeout_ms
+
+        if server_url is not None:
+            base_url = server_url
+        else:
+            base_url = self._get_url(base_url, url_variables)
+
+        request = models.GlobalMarketsPerpsSetLeverageRequest(
+            owner=owner,
+            asset=asset,
+            leverage=leverage,
+        )
+
+        req = self._build_request_async(
+            method="POST",
+            path="/v2/global_markets_perps/set_leverage",
+            base_url=base_url,
+            url_variables=url_variables,
+            request=request,
+            request_body_required=True,
+            request_has_path_params=False,
+            request_has_query_params=True,
+            user_agent_header="user-agent",
+            accept_header_value="application/json",
+            http_headers=http_headers,
+            security=self.sdk_configuration.security,
+            get_serialized_body=lambda: utils.serialize_request_body(
+                request,
+                False,
+                False,
+                "json",
+                models.GlobalMarketsPerpsSetLeverageRequest,
+            ),
+            allow_empty_value=None,
+            timeout_ms=timeout_ms,
+        )
+
+        if retries == UNSET:
+            if self.sdk_configuration.retry_config is not UNSET:
+                retries = self.sdk_configuration.retry_config
+
+        retry_config = None
+        if isinstance(retries, utils.RetryConfig):
+            retry_config = (retries, ["429", "500", "502", "503", "504"])
+
+        http_res = await self.do_request_async(
+            hook_ctx=HookContext(
+                config=self.sdk_configuration,
+                base_url=base_url or "",
+                operation_id="v2_global_markets_perps_set_leverage",
+                oauth2_scopes=None,
+                security_source=self.sdk_configuration.security,
+            ),
+            request=req,
+            is_error_status_code=lambda c: utils.match_status_codes(["4XX", "5XX"], c),
+            retry_config=retry_config,
+        )
+
+        response_data: Any = None
+        if utils.match_response(http_res, "200", "application/json"):
+            return unmarshal_json_response(
+                models.GlobalMarketsPerpsSetLeverageResponse, http_res
+            )
+        if utils.match_response(http_res, "422", "application/json"):
+            response_data = unmarshal_json_response(
+                errors.HTTPValidationErrorData, http_res
+            )
+            raise errors.HTTPValidationError(response_data, http_res)
+        if utils.match_response(http_res, "4XX", "*"):
+            http_res_text = await utils.stream_to_text_async(http_res)
+            raise errors.APIError("API error occurred", http_res, http_res_text)
+        if utils.match_response(http_res, "5XX", "*"):
+            http_res_text = await utils.stream_to_text_async(http_res)
+            raise errors.APIError("API error occurred", http_res, http_res_text)
+
+        raise errors.APIError("Unexpected response received", http_res)

{compass_api_sdk-2.2.65 → compass_api_sdk-2.2.66}/src/compass_api_sdk/models/__init__.py

@@ -762,6 +762,14 @@ if TYPE_CHECKING:
         GlobalMarketsPerpsPositionsResponse,
         GlobalMarketsPerpsPositionsResponseTypedDict,
     )
+    from .globalmarketsperpssetleveragerequest import (
+        GlobalMarketsPerpsSetLeverageRequest,
+        GlobalMarketsPerpsSetLeverageRequestTypedDict,
+    )
+    from .globalmarketsperpssetleverageresponse import (
+        GlobalMarketsPerpsSetLeverageResponse,
+        GlobalMarketsPerpsSetLeverageResponseTypedDict,
+    )
     from .globalmarketsperpssignableactionresponse import (
         GlobalMarketsPerpsSignableActionResponse,
         GlobalMarketsPerpsSignableActionResponseTypedDict,
@@ -2281,6 +2289,10 @@ __all__ = [
     "GlobalMarketsPerpsPositionTypedDict",
     "GlobalMarketsPerpsPositionsResponse",
     "GlobalMarketsPerpsPositionsResponseTypedDict",
+    "GlobalMarketsPerpsSetLeverageRequest",
+    "GlobalMarketsPerpsSetLeverageRequestTypedDict",
+    "GlobalMarketsPerpsSetLeverageResponse",
+    "GlobalMarketsPerpsSetLeverageResponseTypedDict",
     "GlobalMarketsPerpsSignableActionResponse",
     "GlobalMarketsPerpsSignableActionResponseTypedDict",
     "GlobalMarketsPerpsSortBy",
@@ -3548,6 +3560,10 @@ _dynamic_imports: dict[str, str] = {
     "GlobalMarketsPerpsPositionTypedDict": ".globalmarketsperpsposition",
     "GlobalMarketsPerpsPositionsResponse": ".globalmarketsperpspositionsresponse",
     "GlobalMarketsPerpsPositionsResponseTypedDict": ".globalmarketsperpspositionsresponse",
+    "GlobalMarketsPerpsSetLeverageRequest": ".globalmarketsperpssetleveragerequest",
+    "GlobalMarketsPerpsSetLeverageRequestTypedDict": ".globalmarketsperpssetleveragerequest",
+    "GlobalMarketsPerpsSetLeverageResponse": ".globalmarketsperpssetleverageresponse",
+    "GlobalMarketsPerpsSetLeverageResponseTypedDict": ".globalmarketsperpssetleverageresponse",
     "GlobalMarketsPerpsSignableActionResponse": ".globalmarketsperpssignableactionresponse",
     "GlobalMarketsPerpsSignableActionResponseTypedDict": ".globalmarketsperpssignableactionresponse",
     "GlobalMarketsPerpsWithdrawRequest": ".globalmarketsperpswithdrawrequest",

compass_api_sdk-2.2.66/src/compass_api_sdk/models/globalmarketsperpssetleveragerequest.py

@@ -0,0 +1,67 @@
+"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT."""
+
+from __future__ import annotations
+from compass_api_sdk.types import (
+    BaseModel,
+    Nullable,
+    OptionalNullable,
+    UNSET,
+    UNSET_SENTINEL,
+)
+from pydantic import model_serializer
+from typing_extensions import NotRequired, TypedDict
+
+
+class GlobalMarketsPerpsSetLeverageRequestTypedDict(TypedDict):
+    r"""Request to set leverage on a global markets perps asset.
+
+    Omit ``leverage`` (or pass null) to target the asset's maximum leverage.
+    """
+
+    owner: str
+    r"""User's EOA address"""
+    asset: str
+    r"""Asset ticker (e.g. 'AAPL', 'CL')"""
+    leverage: NotRequired[Nullable[int]]
+    r"""Target leverage as a whole-number multiplier. Omit (or pass null) to use the asset's maximum leverage. Must be between 1 and the asset's max leverage, which is available from the /opportunities endpoint."""
+
+
+class GlobalMarketsPerpsSetLeverageRequest(BaseModel):
+    r"""Request to set leverage on a global markets perps asset.
+
+    Omit ``leverage`` (or pass null) to target the asset's maximum leverage.
+    """
+
+    owner: str
+    r"""User's EOA address"""
+
+    asset: str
+    r"""Asset ticker (e.g. 'AAPL', 'CL')"""
+
+    leverage: OptionalNullable[int] = UNSET
+    r"""Target leverage as a whole-number multiplier. Omit (or pass null) to use the asset's maximum leverage. Must be between 1 and the asset's max leverage, which is available from the /opportunities endpoint."""
+
+    @model_serializer(mode="wrap")
+    def serialize_model(self, handler):
+        optional_fields = set(["leverage"])
+        nullable_fields = set(["leverage"])
+        serialized = handler(self)
+        m = {}
+
+        for n, f in type(self).model_fields.items():
+            k = f.alias or n
+            val = serialized.get(k, serialized.get(n))
+            is_nullable_and_explicitly_set = (
+                k in nullable_fields
+                and (self.__pydantic_fields_set__.intersection({n}))  # pylint: disable=no-member
+            )
+
+            if val != UNSET_SENTINEL:
+                if (
+                    val is not None
+                    or k not in optional_fields
+                    or is_nullable_and_explicitly_set
+                ):
+                    m[k] = val
+
+        return m

compass_api_sdk-2.2.66/src/compass_api_sdk/models/globalmarketsperpssetleverageresponse.py

@@ -0,0 +1,75 @@
+"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT."""
+
+from __future__ import annotations
+from compass_api_sdk.types import (
+    BaseModel,
+    Nullable,
+    OptionalNullable,
+    UNSET,
+    UNSET_SENTINEL,
+)
+from pydantic import model_serializer
+from typing import Any, Dict
+from typing_extensions import NotRequired, TypedDict
+
+
+class GlobalMarketsPerpsSetLeverageResponseTypedDict(TypedDict):
+    r"""Returned by the set_leverage endpoint.
+
+    If the asset is already at the requested leverage, typed_data/action/nonce
+    are null. If not, they contain the EIP-712 payload the user must sign.
+    """
+
+    leverage_ok: bool
+    r"""True if leverage already matches the requested value, false if an update is needed"""
+    typed_data: NotRequired[Nullable[Dict[str, Any]]]
+    r"""EIP-712 typed data for wallet signing, or null if no change is needed"""
+    action: NotRequired[Nullable[Dict[str, Any]]]
+    r"""Raw Hyperliquid action (passed back to the execute endpoint), or null"""
+    nonce: NotRequired[Nullable[int]]
+    r"""Timestamp-based nonce, or null if no action needed"""
+
+
+class GlobalMarketsPerpsSetLeverageResponse(BaseModel):
+    r"""Returned by the set_leverage endpoint.
+
+    If the asset is already at the requested leverage, typed_data/action/nonce
+    are null. If not, they contain the EIP-712 payload the user must sign.
+    """
+
+    leverage_ok: bool
+    r"""True if leverage already matches the requested value, false if an update is needed"""
+
+    typed_data: OptionalNullable[Dict[str, Any]] = UNSET
+    r"""EIP-712 typed data for wallet signing, or null if no change is needed"""
+
+    action: OptionalNullable[Dict[str, Any]] = UNSET
+    r"""Raw Hyperliquid action (passed back to the execute endpoint), or null"""
+
+    nonce: OptionalNullable[int] = UNSET
+    r"""Timestamp-based nonce, or null if no action needed"""
+
+    @model_serializer(mode="wrap")
+    def serialize_model(self, handler):
+        optional_fields = set(["typed_data", "action", "nonce"])
+        nullable_fields = set(["typed_data", "action", "nonce"])
+        serialized = handler(self)
+        m = {}
+
+        for n, f in type(self).model_fields.items():
+            k = f.alias or n
+            val = serialized.get(k, serialized.get(n))
+            is_nullable_and_explicitly_set = (
+                k in nullable_fields
+                and (self.__pydantic_fields_set__.intersection({n}))  # pylint: disable=no-member
+            )
+
+            if val != UNSET_SENTINEL:
+                if (
+                    val is not None
+                    or k not in optional_fields
+                    or is_nullable_and_explicitly_set
+                ):
+                    m[k] = val
+
+        return m

{compass_api_sdk-2.2.65 → compass_api_sdk-2.2.66}/src/compass_api_sdk/utils/retries.py

@@ -11,10 +11,13 @@ import httpx
 
 
 class BackoffStrategy:
+    """Exponential backoff strategy configuration."""
+
     initial_interval: int
     max_interval: int
     exponent: float
     max_elapsed_time: int
+    jitter_ms: Optional[int]
 
     def __init__(
         self,
@@ -22,24 +25,63 @@ class BackoffStrategy:
         max_interval: int,
         exponent: float,
         max_elapsed_time: int,
+        jitter_ms: Optional[int] = None,
     ):
+        """Initialize a backoff strategy.
+
+        Args:
+            initial_interval: Initial retry interval in milliseconds.
+            max_interval: Maximum retry interval in milliseconds.
+            exponent: Base of the exponential backoff; the interval grows as
+                ``initial_interval * exponent ** retries``.
+            max_elapsed_time: Maximum total elapsed time in milliseconds.
+            jitter_ms: Additive jitter bound in milliseconds. When set, adds a random
+                value in ``[0, jitter_ms]`` to each computed backoff interval (default
+                ``+[0, 1s]``).
+
+        Note:
+            When a response carries a ``Retry-After`` or ``retry-after-ms`` header,
+            that delay is used as-is and the sleep-shaping parameters
+            (``initial_interval``, ``max_interval``, ``exponent``, ``jitter_ms``) are
+            ignored for that attempt.
+        """
+        if jitter_ms is not None and jitter_ms < 0:
+            raise ValueError("jitter_ms must be >= 0")
         self.initial_interval = initial_interval
         self.max_interval = max_interval
         self.exponent = exponent
         self.max_elapsed_time = max_elapsed_time
+        self.jitter_ms = jitter_ms
 
 
 class RetryConfig:
+    """Runtime retry configuration."""
+
     strategy: str
     backoff: BackoffStrategy
     retry_connection_errors: bool
+    status_codes_override: Optional[List[str]]
 
     def __init__(
-        self, strategy: str, backoff: BackoffStrategy, retry_connection_errors: bool
+        self,
+        strategy: str,
+        backoff: BackoffStrategy,
+        retry_connection_errors: bool,
+        status_codes_override: Optional[List[str]] = None,
     ):
+        """Initialize a retry configuration.
+
+        Args:
+            strategy: Retry strategy: ``"none"`` or ``"backoff"``.
+            backoff: Backoff parameters.
+            retry_connection_errors: Whether to also retry transport-level connection errors.
+            status_codes_override: Retryable HTTP status codes that take precedence over the
+                per-operation defaults when non-empty.
+        """
         self.strategy = strategy
         self.backoff = backoff
         self.retry_connection_errors = retry_connection_errors
+        self.status_codes_override = status_codes_override
 
 
 class Retries:
@@ -48,7 +90,7 @@ class Retries:
 
     def __init__(self, config: RetryConfig, status_codes: List[str]):
         self.config = config
-        self.status_codes = status_codes
+        self.status_codes = config.status_codes_override or status_codes
 
 
 class TemporaryError(Exception):
@@ -114,6 +156,7 @@ def _get_sleep_interval(
     max_interval: int,
     exponent: float,
     retries: int,
+    jitter_ms: Optional[int] = None,
 ) -> float:
     """Get sleep interval for retry with exponential backoff.
 
@@ -123,6 +166,7 @@ def _get_sleep_interval(
         max_interval: Maximum retry interval in milliseconds.
         exponent: Base for exponential backoff calculation.
         retries: Current retry attempt count.
+        jitter_ms: Additive jitter bound in ms; see ``BackoffStrategy.jitter_ms``.
 
     Returns:
         Sleep interval in seconds.
@@ -134,7 +178,11 @@ def _get_sleep_interval(
     ):
         return exception.retry_after / 1000
 
-    sleep = (initial_interval / 1000) * exponent**retries + random.uniform(0, 1)
+    sleep = (initial_interval / 1000) * exponent**retries
+    if jitter_ms is not None:
+        sleep += random.uniform(0, jitter_ms / 1000)
+    else:
+        sleep += random.uniform(0, 1)
     return min(sleep, max_interval / 1000)
 
 
@@ -177,6 +225,7 @@ def retry(func, retries: Retries):
             retries.config.backoff.max_interval,
             retries.config.backoff.exponent,
             retries.config.backoff.max_elapsed_time,
+            retries.config.backoff.jitter_ms,
         )
 
     return func()
@@ -221,6 +270,7 @@ async def retry_async(func, retries: Retries):
             retries.config.backoff.max_interval,
             retries.config.backoff.exponent,
             retries.config.backoff.max_elapsed_time,
+            retries.config.backoff.jitter_ms,
         )
 
     return await func()
@@ -232,6 +282,7 @@ def retry_with_backoff(
     max_interval=60000,
     exponent=1.5,
     max_elapsed_time=3600000,
+    jitter_ms=None,
 ):
     start = round(time.time() * 1000)
     retries = 0
@@ -254,7 +305,12 @@ def retry_with_backoff(
                 if retry_after_ms is not None:
                     exception.retry_after = retry_after_ms
             sleep = _get_sleep_interval(
-                exception, initial_interval, max_interval, exponent, retries
+                exception,
+                initial_interval,
+                max_interval,
+                exponent,
+                retries,
+                jitter_ms=jitter_ms,
             )
             time.sleep(sleep)
             retries += 1
@@ -266,6 +322,7 @@ async def retry_with_backoff_async(
     max_interval=60000,
     exponent=1.5,
     max_elapsed_time=3600000,
+    jitter_ms=None,
 ):
     start = round(time.time() * 1000)
     retries = 0
@@ -288,7 +345,12 @@ async def retry_with_backoff_async(
                 if retry_after_ms is not None:
                     exception.retry_after = retry_after_ms
             sleep = _get_sleep_interval(
-                exception, initial_interval, max_interval, exponent, retries
+                exception,
+                initial_interval,
+                max_interval,
+                exponent,
+                retries,
+                jitter_ms=jitter_ms,
             )
             await asyncio.sleep(sleep)
             retries += 1