compass_api_sdk 2.2.110__tar.gz → 2.2.111__tar.gz

{compass_api_sdk-2.2.110 → compass_api_sdk-2.2.111}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compass_api_sdk
-Version: 2.2.110
+Version: 2.2.111
 Summary: Compass API SDK.
 Author: royalnine
 Requires-Python: >=3.10

{compass_api_sdk-2.2.110 → compass_api_sdk-2.2.111}/pyproject.toml

@@ -1,7 +1,7 @@
 
 [project]
 name = "compass_api_sdk"
-version = "2.2.110"
+version = "2.2.111"
 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.110"
+version = "2.2.111"
 description = "Compass API SDK."
 authors = ["Compass Labs"]
 repository = "https://github.com/CompassLabs/mono.git"

{compass_api_sdk-2.2.110 → compass_api_sdk-2.2.111}/src/compass_api_sdk/credit.py

@@ -2804,6 +2804,7 @@ class Credit(BaseSDK):
             ]
         ] = None,
         gas_sponsorship: Optional[bool] = None,
+        preview: Optional[bool] = None,
         pricing: Optional[models.CreditSwapRequestPricing] = None,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
@@ -2826,7 +2827,8 @@ class Credit(BaseSDK):
         :param chain: Target blockchain network where the swap will execute.
         :param slippage: Maximum slippage tolerance as a percentage (e.g., 0.5 = 0.5%). Bounds the market route only; a firm quote fills exactly and ignores it.
         :param gas_sponsorship: Optionally request gas sponsorship. If `true`, EIP-712 typed data will be returned that must be signed by the `owner` and submitted to the 'Prepare gas-sponsored transaction' endpoint (`/gas_sponsorship/prepare`). Gas-sponsored builds always execute at market rate.
-        :param pricing: Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing).
+        :param preview: If true, build a display ESTIMATE: no firm RFQ quote is ever requested (quote_expires_at stays null). NOTE that this guarantees only that no firm quote was spent — it does not guarantee an absent payload: under 'auto' when the firm provider does not cover or cannot currently price the pair, and always under pricing=market, the call falls through to the aggregator and returns a signable market build (an unsigned transaction, or EIP-712 typed data when gas_sponsorship=true), without requiring the account to hold token_in yet. How the estimate is priced follows `pricing`: on a firm-covered pair whose size the firm provider's live price levels can serve, 'auto' and 'firm' price it from those levels (indicative, transaction stays null — re-call with preview=false for the signable build); otherwise it comes from the market build above (pricing='firm' instead refuses with a typed error). Set it on every call made while a user is exploring parameters, and leave it false only for the build they actually intend to sign — firm quotes are single-use maker commitments, and requesting them for displays that are never executed degrades the pricing this API is offered.
+        :param pricing: Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing — previews included: a preview the firm provider's live price levels cannot price returns the same typed error rather than market numbers. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing).
         :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
@@ -2850,6 +2852,7 @@ class Credit(BaseSDK):
             owner=owner,
             chain=chain,
             gas_sponsorship=gas_sponsorship,
+            preview=preview,
             pricing=pricing,
         )
 
@@ -2930,6 +2933,7 @@ class Credit(BaseSDK):
             ]
         ] = None,
         gas_sponsorship: Optional[bool] = None,
+        preview: Optional[bool] = None,
         pricing: Optional[models.CreditSwapRequestPricing] = None,
         retries: OptionalNullable[utils.RetryConfig] = UNSET,
         server_url: Optional[str] = None,
@@ -2952,7 +2956,8 @@ class Credit(BaseSDK):
         :param chain: Target blockchain network where the swap will execute.
         :param slippage: Maximum slippage tolerance as a percentage (e.g., 0.5 = 0.5%). Bounds the market route only; a firm quote fills exactly and ignores it.
         :param gas_sponsorship: Optionally request gas sponsorship. If `true`, EIP-712 typed data will be returned that must be signed by the `owner` and submitted to the 'Prepare gas-sponsored transaction' endpoint (`/gas_sponsorship/prepare`). Gas-sponsored builds always execute at market rate.
-        :param pricing: Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing).
+        :param preview: If true, build a display ESTIMATE: no firm RFQ quote is ever requested (quote_expires_at stays null). NOTE that this guarantees only that no firm quote was spent — it does not guarantee an absent payload: under 'auto' when the firm provider does not cover or cannot currently price the pair, and always under pricing=market, the call falls through to the aggregator and returns a signable market build (an unsigned transaction, or EIP-712 typed data when gas_sponsorship=true), without requiring the account to hold token_in yet. How the estimate is priced follows `pricing`: on a firm-covered pair whose size the firm provider's live price levels can serve, 'auto' and 'firm' price it from those levels (indicative, transaction stays null — re-call with preview=false for the signable build); otherwise it comes from the market build above (pricing='firm' instead refuses with a typed error). Set it on every call made while a user is exploring parameters, and leave it false only for the build they actually intend to sign — firm quotes are single-use maker commitments, and requesting them for displays that are never executed degrades the pricing this API is offered.
+        :param pricing: Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing — previews included: a preview the firm provider's live price levels cannot price returns the same typed error rather than market numbers. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing).
         :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
@@ -2976,6 +2981,7 @@ class Credit(BaseSDK):
             owner=owner,
             chain=chain,
             gas_sponsorship=gas_sponsorship,
+            preview=preview,
             pricing=pricing,
         )
 

{compass_api_sdk-2.2.110 → compass_api_sdk-2.2.111}/src/compass_api_sdk/models/creditswaprequest.py

@@ -47,7 +47,7 @@ class CreditSwapRequestChain(str, Enum):
 
 
 class CreditSwapRequestPricing(str, Enum):
-    r"""Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing)."""
+    r"""Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing — previews included: a preview the firm provider's live price levels cannot price returns the same typed error rather than market numbers. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing)."""
 
     AUTO = "auto"
     FIRM = "firm"
@@ -76,8 +76,10 @@ class CreditSwapRequestTypedDict(TypedDict):
     r"""Maximum slippage tolerance as a percentage (e.g., 0.5 = 0.5%). Bounds the market route only; a firm quote fills exactly and ignores it."""
     gas_sponsorship: NotRequired[bool]
     r"""Optionally request gas sponsorship. If `true`, EIP-712 typed data will be returned that must be signed by the `owner` and submitted to the 'Prepare gas-sponsored transaction' endpoint (`/gas_sponsorship/prepare`). Gas-sponsored builds always execute at market rate."""
+    preview: NotRequired[bool]
+    r"""If true, build a display ESTIMATE: no firm RFQ quote is ever requested (quote_expires_at stays null). NOTE that this guarantees only that no firm quote was spent — it does not guarantee an absent payload: under 'auto' when the firm provider does not cover or cannot currently price the pair, and always under pricing=market, the call falls through to the aggregator and returns a signable market build (an unsigned transaction, or EIP-712 typed data when gas_sponsorship=true), without requiring the account to hold token_in yet. How the estimate is priced follows `pricing`: on a firm-covered pair whose size the firm provider's live price levels can serve, 'auto' and 'firm' price it from those levels (indicative, transaction stays null — re-call with preview=false for the signable build); otherwise it comes from the market build above (pricing='firm' instead refuses with a typed error). Set it on every call made while a user is exploring parameters, and leave it false only for the build they actually intend to sign — firm quotes are single-use maker commitments, and requesting them for displays that are never executed degrades the pricing this API is offered."""
     pricing: NotRequired[CreditSwapRequestPricing]
-    r"""Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing)."""
+    r"""Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing — previews included: a preview the firm provider's live price levels cannot price returns the same typed error rather than market numbers. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing)."""
 
 
 class CreditSwapRequest(BaseModel):
@@ -115,12 +117,17 @@ class CreditSwapRequest(BaseModel):
     gas_sponsorship: Optional[bool] = None
     r"""Optionally request gas sponsorship. If `true`, EIP-712 typed data will be returned that must be signed by the `owner` and submitted to the 'Prepare gas-sponsored transaction' endpoint (`/gas_sponsorship/prepare`). Gas-sponsored builds always execute at market rate."""
 
+    preview: Optional[bool] = None
+    r"""If true, build a display ESTIMATE: no firm RFQ quote is ever requested (quote_expires_at stays null). NOTE that this guarantees only that no firm quote was spent — it does not guarantee an absent payload: under 'auto' when the firm provider does not cover or cannot currently price the pair, and always under pricing=market, the call falls through to the aggregator and returns a signable market build (an unsigned transaction, or EIP-712 typed data when gas_sponsorship=true), without requiring the account to hold token_in yet. How the estimate is priced follows `pricing`: on a firm-covered pair whose size the firm provider's live price levels can serve, 'auto' and 'firm' price it from those levels (indicative, transaction stays null — re-call with preview=false for the signable build); otherwise it comes from the market build above (pricing='firm' instead refuses with a typed error). Set it on every call made while a user is exploring parameters, and leave it false only for the build they actually intend to sign — firm quotes are single-use maker commitments, and requesting them for displays that are never executed degrades the pricing this API is offered."""
+
     pricing: Optional[CreditSwapRequestPricing] = None
-    r"""Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing)."""
+    r"""Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing — previews included: a preview the firm provider's live price levels cannot price returns the same typed error rather than market numbers. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by `slippage` (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing)."""
 
     @model_serializer(mode="wrap")
     def serialize_model(self, handler):
-        optional_fields = set(["action_type", "slippage", "gas_sponsorship", "pricing"])
+        optional_fields = set(
+            ["action_type", "slippage", "gas_sponsorship", "preview", "pricing"]
+        )
         serialized = handler(self)
         m = {}
 

{compass_api_sdk-2.2.110 → compass_api_sdk-2.2.111}/src/compass_api_sdk/models/creditswapresponse.py

@@ -21,7 +21,7 @@ from typing_extensions import NotRequired, TypedDict
 
 
 class CreditSwapResponseSwapProvider(str, Enum):
-    r"""Identifies which route priced the swap. 'market': a DEX aggregator, slippage-bounded. 'firm': a zero-slippage quote that fills exactly or reverts. Always present. This is the authoritative firm-vs-market signal and clients do need to read it: `pricing` is only what was REQUESTED, and under 'auto' a firm build can fall back to market transparently."""
+    r"""Identifies which route priced the swap. 'market': a DEX aggregator, slippage-bounded. 'firm': a zero-slippage quote that fills exactly or reverts. On preview=true responses 'firm' means the estimate is INDICATIVE, computed from live maker price levels without spending any quote; execution fetches the firm quote at signing time. Always present. This is the authoritative firm-vs-market signal and clients do need to read it: `pricing` is only what was REQUESTED, and under 'auto' a firm build can fall back to market transparently."""
 
     MARKET = "market"
     FIRM = "firm"
@@ -33,15 +33,15 @@ class CreditSwapResponseTypedDict(TypedDict):
     """
 
     estimated_amount_out: str
-    r"""Estimated amount of output token received from the swap. Exact on firm builds (a firm quote fills at this amount or reverts). On market builds it is a quote-time estimate, and `slippage` sets how far below it the transaction's enforced minimum output sits."""
+    r"""Estimated amount of output token received from the swap. Exact on executable firm builds (a firm quote fills at this amount or reverts). On market builds it is a quote-time estimate, and `slippage` sets how far below it the transaction's enforced minimum output sits. On preview=true responses reporting 'firm' it is INDICATIVE — computed from the firm provider's live price levels without spending a quote."""
     transaction: NotRequired[Nullable[UnsignedTransactionTypedDict]]
-    r"""Unsigned transaction for direct execution. Present when gas_sponsorship=false."""
+    r"""Unsigned transaction for direct execution. Present when gas_sponsorship=false — except firm-priced previews (preview=true responses reporting swap_provider='firm'), which carry the estimate only: the firm quote is fetched at execution time, so there is no payload to sign yet. A preview whose response reports swap_provider='market' does carry this signable payload."""
     eip_712: NotRequired[Nullable[BatchedSafeOperationsResponseOutputTypedDict]]
     r"""EIP-712 typed data for gas-sponsored execution. Present when gas_sponsorship=true."""
     swap_provider: NotRequired[CreditSwapResponseSwapProvider]
-    r"""Identifies which route priced the swap. 'market': a DEX aggregator, slippage-bounded. 'firm': a zero-slippage quote that fills exactly or reverts. Always present. This is the authoritative firm-vs-market signal and clients do need to read it: `pricing` is only what was REQUESTED, and under 'auto' a firm build can fall back to market transparently."""
+    r"""Identifies which route priced the swap. 'market': a DEX aggregator, slippage-bounded. 'firm': a zero-slippage quote that fills exactly or reverts. On preview=true responses 'firm' means the estimate is INDICATIVE, computed from live maker price levels without spending any quote; execution fetches the firm quote at signing time. Always present. This is the authoritative firm-vs-market signal and clients do need to read it: `pricing` is only what was REQUESTED, and under 'auto' a firm build can fall back to market transparently."""
     quote_expires_at: NotRequired[Nullable[datetime]]
-    r"""Deadline of the firm swap quote. Sign and broadcast before it or the transaction reverts on-chain; refresh by re-calling this endpoint (discard the previous payload). Null on market builds."""
+    r"""Deadline of the firm swap quote. Sign and broadcast before it or the transaction reverts on-chain; refresh by re-calling this endpoint (discard the previous payload). Null on market builds and on every preview (a preview never holds a firm quote)."""
 
 
 class CreditSwapResponse(BaseModel):
@@ -50,19 +50,19 @@ class CreditSwapResponse(BaseModel):
     """
 
     estimated_amount_out: str
-    r"""Estimated amount of output token received from the swap. Exact on firm builds (a firm quote fills at this amount or reverts). On market builds it is a quote-time estimate, and `slippage` sets how far below it the transaction's enforced minimum output sits."""
+    r"""Estimated amount of output token received from the swap. Exact on executable firm builds (a firm quote fills at this amount or reverts). On market builds it is a quote-time estimate, and `slippage` sets how far below it the transaction's enforced minimum output sits. On preview=true responses reporting 'firm' it is INDICATIVE — computed from the firm provider's live price levels without spending a quote."""
 
     transaction: OptionalNullable[UnsignedTransaction] = UNSET
-    r"""Unsigned transaction for direct execution. Present when gas_sponsorship=false."""
+    r"""Unsigned transaction for direct execution. Present when gas_sponsorship=false — except firm-priced previews (preview=true responses reporting swap_provider='firm'), which carry the estimate only: the firm quote is fetched at execution time, so there is no payload to sign yet. A preview whose response reports swap_provider='market' does carry this signable payload."""
 
     eip_712: OptionalNullable[BatchedSafeOperationsResponseOutput] = UNSET
     r"""EIP-712 typed data for gas-sponsored execution. Present when gas_sponsorship=true."""
 
     swap_provider: Optional[CreditSwapResponseSwapProvider] = None
-    r"""Identifies which route priced the swap. 'market': a DEX aggregator, slippage-bounded. 'firm': a zero-slippage quote that fills exactly or reverts. Always present. This is the authoritative firm-vs-market signal and clients do need to read it: `pricing` is only what was REQUESTED, and under 'auto' a firm build can fall back to market transparently."""
+    r"""Identifies which route priced the swap. 'market': a DEX aggregator, slippage-bounded. 'firm': a zero-slippage quote that fills exactly or reverts. On preview=true responses 'firm' means the estimate is INDICATIVE, computed from live maker price levels without spending any quote; execution fetches the firm quote at signing time. Always present. This is the authoritative firm-vs-market signal and clients do need to read it: `pricing` is only what was REQUESTED, and under 'auto' a firm build can fall back to market transparently."""
 
     quote_expires_at: OptionalNullable[datetime] = UNSET
-    r"""Deadline of the firm swap quote. Sign and broadcast before it or the transaction reverts on-chain; refresh by re-calling this endpoint (discard the previous payload). Null on market builds."""
+    r"""Deadline of the firm swap quote. Sign and broadcast before it or the transaction reverts on-chain; refresh by re-calling this endpoint (discard the previous payload). Null on market builds and on every preview (a preview never holds a firm quote)."""
 
     @model_serializer(mode="wrap")
     def serialize_model(self, handler):