afp-sdk 0.5.1__tar.gz → 0.5.2__tar.gz

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [v0.5.2] - 2025-10-04
+
+### Added
+
+- Add `Trading.orders()` method for filtering orders based on multiple criteria ([#26](https://github.com/autonity/afp-sdk/pull/26))
+- Add `trade_states` argument to `Trading.order_fills()` ([#26](https://github.com/autonity/afp-sdk/pull/26))
+
+### Changed
+
+- Change `Trading.products()`, `Trading.orders()` and `Trading.order_fills()` to retrieve items in batches ([#31](https://github.com/autonity/afp-sdk/pull/31))
+
+### Fixed
+
+- Raise `afp.exceptions.ExchangeError` for AutEx internal server errors instead of `afp.exceptions.ValidationError` ([#32](https://github.com/autonity/afp-sdk/pull/32))
+
+### Removed
+
+- Flag `Trading.open_orders()` method for deprecation. ([#26](https://github.com/autonity/afp-sdk/pull/26))
+
 ## [v0.5.1] - 2025-09-23
 
 ### Added
@@ -38,6 +57,7 @@
 
 _First public release for Forecastathon._
 
+[v0.5.2]: https://github.com/autonity/afp-sdk/releases/tag/v0.5.2
 [v0.5.1]: https://github.com/autonity/afp-sdk/releases/tag/v0.5.1
 [v0.5.0]: https://github.com/autonity/afp-sdk/releases/tag/v0.5.0
 [v0.4.0]: https://github.com/autonity/afp-sdk/releases/tag/v0.4.0

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: afp-sdk
-Version: 0.5.1
+Version: 0.5.2
 Summary: Autonomous Futures Protocol Python SDK
 Keywords: autonity,web3,trading,crypto,prediction,forecast,markets
 License-Expression: MIT

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/afp/api/trading.py

@@ -1,25 +1,27 @@
 import secrets
+import warnings
 from datetime import datetime
 from decimal import Decimal
-from typing import Generator
+from typing import Generator, Iterable
 
 from web3 import Web3
 
 from .. import hashing, validators
+from ..constants import DEFAULT_BATCH_SIZE
 from ..decorators import refresh_token_on_expiry
-from ..enums import OrderType
+from ..enums import OrderSide, OrderState, OrderType, TradeState
 from ..schemas import (
     ExchangeProduct,
+    ExchangeProductFilter,
     Intent,
     IntentData,
     MarketDepthData,
     Order,
+    OrderFilter,
     OrderCancellationData,
     OrderFill,
     OrderFillFilter,
-    OrderSide,
     OrderSubmission,
-    TradeState,
 )
 from .base import ExchangeAPI
 
@@ -61,6 +63,7 @@ class Trading(ExchangeAPI):
         ----------
         product : afp.schemas.ExchangeProduct
         side : str
+            One of `BID` and `ASK`.
         limit_price : decimal.Decimal
         quantity : decimal.Decimal
         max_trading_fee_rate : decimal.Decimal
@@ -87,7 +90,7 @@ class Trading(ExchangeAPI):
             ),
             quantity=quantity,
             max_trading_fee_rate=max_trading_fee_rate,
-            side=getattr(OrderSide, side.upper()),
+            side=OrderSide(side.upper()),
             good_until_time=good_until_time,
             nonce=self._generate_nonce(),
         )
@@ -161,14 +164,34 @@ class Trading(ExchangeAPI):
         )
         return self._exchange.submit_order(submission)
 
-    def products(self) -> list[ExchangeProduct]:
+    def products(
+        self,
+        batch: int = 1,
+        batch_size: int = DEFAULT_BATCH_SIZE,
+        newest_first: bool = True,
+    ) -> list[ExchangeProduct]:
         """Retrieves the products approved for trading on the exchange.
 
+        If there are more than `batch_size` number of products then they can be queried
+        in batches.
+
+        Parameters
+        ----------
+        batch : int, optional
+            1-based index of the batch of products.
+        batch_size : int, optional
+            The maximum number of products in one batch.
+        newest_first : bool, optional
+            Whether to sort products in descending or ascending order by creation time.
+
         Returns
         -------
         list of afp.schemas.ExchangeProduct
         """
-        return self._exchange.get_approved_products()
+        filter = ExchangeProductFilter(
+            batch=batch, batch_size=batch_size, newest_first=newest_first
+        )
+        return self._exchange.get_approved_products(filter)
 
     def product(self, product_id: str) -> ExchangeProduct:
         """Retrieves a product for trading by its ID.
@@ -211,40 +234,106 @@ class Trading(ExchangeAPI):
         return self._exchange.get_order_by_id(value)
 
     @refresh_token_on_expiry
-    def open_orders(self, product_id: str | None = None) -> list[Order]:
-        """Retrieves all open and partially filled limit orders that have been submitted
-        by the authenticated account.
+    def orders(
+        self,
+        *,
+        product_id: str | None = None,
+        type_: str | None = None,
+        states: Iterable[str] = (),
+        side: str | None = None,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        batch: int = 1,
+        batch_size: int = DEFAULT_BATCH_SIZE,
+        newest_first: bool = True,
+    ) -> list[Order]:
+        """Retrieves the authenticated account's orders that match the given parameters.
+
+        If there are more than `batch_size` number of orders then they can be queried
+        in batches.
 
         Parameters
         ----------
         product_id : str, optional
+        type_ : str, optional
+            One of `LIMIT_ORDER` and `CANCEL_ORDER`.
+        states : iterable of str
+            Any of `RECEIVED`, `PENDING`, `OPEN`, `COMPLETED` and `REJECTED`.
+        side : str, optional
+            One of `BID` and `ASK`.
+        start : datetime.datetime, optional
+        end : datetime.datetime, optional
+        batch : int, optional
+            1-based index of the batch of orders.
+        batch_size : int, optional
+            The maximum number of orders in one batch.
+        newest_first : bool, optional
+            Whether to sort orders in descending or ascending order by creation time.
 
         Returns
         -------
-        list of afp.schemas.Order
+        list of afp.schemas.OrderFill
         """
-        return self._exchange.get_open_orders(product_id)
+        filter = OrderFilter(
+            intent_account_id=self._authenticator.address,
+            product_id=product_id,
+            type=None if type_ is None else OrderType(type_.upper()),
+            states=[OrderState(state.upper()) for state in states],
+            side=None if side is None else OrderSide(side.upper()),
+            start=start,
+            end=end,
+            batch=batch,
+            batch_size=batch_size,
+            newest_first=newest_first,
+        )
+        return self._exchange.get_orders(filter)
+
+    @refresh_token_on_expiry
+    def open_orders(self, product_id: str | None = None) -> list[Order]:
+        """Deprecated alias of Trading.orders(type_="LIMIT_ORDER", states=("OPEN", "PARTIAL"))."""
+        warnings.warn(
+            "Trading.open_orders() is deprecated. Use "
+            'Trading.orders(type_="LIMIT_ORDER", states=("OPEN", "PARTIAL")) instead.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.orders(
+            type_="limit_order", states=("open", "partial"), product_id=product_id
+        )
 
     @refresh_token_on_expiry
     def order_fills(
         self,
         *,
         product_id: str | None = None,
-        margin_account_id: str | None = None,
         intent_hash: str | None = None,
         start: datetime | None = None,
         end: datetime | None = None,
+        trade_states: Iterable[str] = (),
+        batch: int = 1,
+        batch_size: int = DEFAULT_BATCH_SIZE,
+        newest_first: bool = True,
     ) -> list[OrderFill]:
         """Retrieves the authenticated account's order fills that match the given
         parameters.
 
+        If there are more than `batch_size` number of order fills then they can be
+        queried in batches.
+
         Parameters
         ----------
         product_id : str, optional
-        margin_account_id : str, optional
         intent_hash : str, optional
         start : datetime.datetime, optional
         end : datetime.datetime, optional
+        trade_states : iterable of str
+            Any of `PENDING`, `CLEARED` and `REJECTED`.
+        batch : int, optional
+            1-based index of the batch of order fills.
+        batch_size : int, optional
+            The maximum number of order fills in one batch.
+        newest_first : bool, optional
+            Whether to sort order fills in descending or ascending order by creation time.
 
         Returns
         -------
@@ -253,11 +342,13 @@ class Trading(ExchangeAPI):
         filter = OrderFillFilter(
             intent_account_id=self._authenticator.address,
             product_id=product_id,
-            margin_account_id=margin_account_id,
             intent_hash=intent_hash,
             start=start,
             end=end,
-            trade_state=None,
+            trade_states=[TradeState(state.upper()) for state in trade_states],
+            batch=batch,
+            batch_size=batch_size,
+            newest_first=newest_first,
         )
         return self._exchange.get_order_fills(filter)
 
@@ -266,21 +357,28 @@ class Trading(ExchangeAPI):
         self,
         *,
         product_id: str | None = None,
-        margin_account_id: str | None = None,
         intent_hash: str | None = None,
+        trade_states: Iterable[str] = ("PENDING",),
     ) -> Generator[OrderFill, None, None]:
         """Subscribes to the authenticated account's new order fills that match the
         given parameters.
 
-        Returns a generator that yields new order fills as they are published by the
-        exchange. A new order fill gets publised as soon as there is a match in the
-        order book, before the trade is submitted to clearing.
+        Returns a generator that yields order fills as they are published by the
+        exchange.
+
+        If `trade_states` includes `PENDING` (the default value) then a new order fill
+        is yielded as soon as there is a match in the order book, before the trade is
+        submitted to clearing.
+
+        If `trade_states` is empty or more than one trade state is specified then
+        updates to order fills are yielded at every state transition.
 
         Parameters
         ----------
         product_id : str, optional
-        margin_account_id : str, optional
         intent_hash : str, optional
+        trade_states: iterable of str
+            Any of `PENDING`, `CLEARED` and `REJECTED`.
 
         Yields
         -------
@@ -289,11 +387,13 @@ class Trading(ExchangeAPI):
         filter = OrderFillFilter(
             intent_account_id=self._authenticator.address,
             product_id=product_id,
-            margin_account_id=margin_account_id,
             intent_hash=intent_hash,
             start=None,
             end=None,
-            trade_state=TradeState.PENDING,
+            trade_states=[TradeState(state.upper()) for state in trade_states],
+            batch=None,
+            batch_size=None,
+            newest_first=None,
         )
         yield from self._exchange.iter_order_fills(filter)
 

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/afp/constants.py

@@ -1,4 +1,5 @@
 import os
+from importlib import metadata
 from types import SimpleNamespace
 
 
@@ -6,10 +7,12 @@ def _int_or_none(value: str | None) -> int | None:
     return int(value) if value is not None else None
 
 
-USER_AGENT = "afp-sdk"
+# Venue API constants
+USER_AGENT = "afp-sdk/{}".format(metadata.version("afp-sdk"))
+DEFAULT_BATCH_SIZE = 50
 DEFAULT_EXCHANGE_API_VERSION = 1
 
-# Constants from clearing/contracts/lib/constants.sol
+# Clearing System constants
 RATE_MULTIPLIER = 10**4
 FEE_RATE_MULTIPLIER = 10**6
 FULL_PRECISION_MULTIPLIER = 10**18

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/afp/enums.py

@@ -4,6 +4,7 @@ from enum import StrEnum
 class ListingState(StrEnum):
     PRIVATE = "PRIVATE"
     PUBLIC = "PUBLIC"
+    READ_ONLY = "READ_ONLY"
     DELISTED = "DELISTED"
 
 

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/afp/exchange.py

@@ -16,11 +16,13 @@ from .exceptions import (
 from .schemas import (
     ExchangeParameters,
     ExchangeProduct,
+    ExchangeProductFilter,
     ExchangeProductListingSubmission,
     ExchangeProductUpdateSubmission,
     LoginSubmission,
     MarketDepthData,
     Order,
+    OrderFilter,
     OrderFill,
     OrderFillFilter,
     OrderSubmission,
@@ -51,8 +53,12 @@ class ExchangeClient:
         return ExchangeParameters(**response.json())
 
     # GET /products
-    def get_approved_products(self) -> list[ExchangeProduct]:
-        response = self._send_request("GET", "/products")
+    def get_approved_products(
+        self, filter: ExchangeProductFilter
+    ) -> list[ExchangeProduct]:
+        response = self._send_request(
+            "GET", "/products", params=filter.model_dump(exclude_none=True)
+        )
         return [ExchangeProduct(**item) for item in response.json()["products"]]
 
     # GET /products/{product_id}
@@ -86,9 +92,9 @@ class ExchangeClient:
         return Order(**response.json())
 
     # GET /orders
-    def get_open_orders(self, product_id: str | None = None) -> list[Order]:
+    def get_orders(self, filter: OrderFilter) -> list[Order]:
         response = self._send_request(
-            "GET", "/orders", params=({"product_id": product_id} if product_id else {})
+            "GET", "/orders", params=filter.model_dump(exclude_none=True)
         )
         return [Order(**item) for item in response.json()["orders"]]
 
@@ -167,11 +173,19 @@ class ExchangeClient:
                 raise AuthorizationError(http_error) from http_error
             if http_error.response.status_code == requests.codes.NOT_FOUND:
                 raise NotFoundError(http_error) from http_error
-
-            try:
-                reason = response.json()["detail"]
-            except (json.JSONDecodeError, KeyError):
-                reason = response.text
-            raise ValidationError(reason) from http_error
+            if http_error.response.status_code == requests.codes.BAD_REQUEST:
+                try:
+                    reason = response.json()["detail"]
+                except (json.JSONDecodeError, KeyError):
+                    reason = http_error
+                raise ValidationError(reason) from http_error
+            if http_error.response.status_code == requests.codes.UNPROCESSABLE:
+                try:
+                    reason = ", ".join(err["msg"] for err in response.json()["detail"])
+                except (json.JSONDecodeError, KeyError, TypeError):
+                    reason = http_error
+                raise ValidationError(reason) from http_error
+
+            raise ExchangeError(http_error) from http_error
 
         return response

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/afp/schemas.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from decimal import Decimal
 from functools import partial
-from typing import Annotated, Any
+from typing import Annotated, Any, Literal
 
 import inflection
 from pydantic import (
@@ -12,6 +12,7 @@ from pydantic import (
     ConfigDict,
     Field,
     PlainSerializer,
+    computed_field,
 )
 
 from . import validators
@@ -40,6 +41,33 @@ class Model(BaseModel):
         return super().model_dump_json(by_alias=by_alias, **kwargs)
 
 
+class PaginationFilter(Model):
+    batch: Annotated[None | int, Field(gt=0, exclude=True)]
+    batch_size: Annotated[None | int, Field(gt=0, exclude=True)]
+    newest_first: Annotated[None | bool, Field(exclude=True)]
+
+    @computed_field
+    @property
+    def page(self) -> None | int:
+        return self.batch
+
+    @computed_field
+    @property
+    def page_size(self) -> None | int:
+        return self.batch_size
+
+    @computed_field
+    @property
+    def sort(self) -> None | Literal["ASC", "DESC"]:
+        match self.newest_first:
+            case None:
+                return None
+            case True:
+                return "DESC"
+            case False:
+                return "ASC"
+
+
 # Authentication
 
 
@@ -78,6 +106,10 @@ class ExchangeProduct(Model):
         return self.id
 
 
+class ExchangeProductFilter(PaginationFilter):
+    pass
+
+
 class IntentData(Model):
     trading_protocol_id: str
     product_id: str
@@ -106,6 +138,21 @@ class Order(Model):
     intent: Intent
 
 
+class OrderFilter(PaginationFilter):
+    intent_account_id: str
+    product_id: None | Annotated[str, AfterValidator(validators.validate_hexstr32)]
+    type: None | OrderType
+    states: Annotated[list[OrderState], Field(exclude=True)]
+    side: None | OrderSide
+    start: None | Timestamp
+    end: None | Timestamp
+
+    @computed_field
+    @property
+    def state(self) -> str | None:
+        return ",".join(self.states) if self.states else None
+
+
 class OrderCancellationData(Model):
     intent_hash: Annotated[str, AfterValidator(validators.validate_hexstr32)]
     nonce: int
@@ -137,16 +184,18 @@ class OrderFill(Model):
     price: Decimal
 
 
-class OrderFillFilter(Model):
+class OrderFillFilter(PaginationFilter):
     intent_account_id: str
     product_id: None | Annotated[str, AfterValidator(validators.validate_hexstr32)]
-    margin_account_id: (
-        None | Annotated[str, AfterValidator(validators.validate_address)]
-    )
     intent_hash: None | Annotated[str, AfterValidator(validators.validate_hexstr32)]
     start: None | Timestamp
     end: None | Timestamp
-    trade_state: None | TradeState
+    trade_states: Annotated[list[TradeState], Field(exclude=True)]
+
+    @computed_field
+    @property
+    def trade_state(self) -> str | None:
+        return ",".join(self.trade_states) if self.trade_states else None
 
 
 class MarketDepthItem(Model):

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "afp-sdk"
-version = "0.5.1"
+version = "0.5.2"
 description = "Autonomous Futures Protocol Python SDK"
 readme = "README.md"
 license = "MIT"

afp_sdk-0.5.2/tests/test_schemas.py

@@ -0,0 +1,31 @@
+from afp.schemas import Model, PaginationFilter
+
+
+class Person(Model):
+    first_name: str
+    last_name: str
+
+
+def test_schema_aliasing__from_json():
+    person = Person.model_validate_json('{"firstName":"Foo","lastName":"Bar"}')
+    assert person.first_name == "Foo"
+    assert person.last_name == "Bar"
+
+
+def test_schema_aliasing__to_json():
+    person = Person(first_name="Foo", last_name="Bar")
+    assert person.model_dump_json() == '{"firstName":"Foo","lastName":"Bar"}'
+
+
+def test_pagination_parameters__conversion():
+    filter = PaginationFilter(batch=2, batch_size=20, newest_first=False)
+    assert filter.model_dump() == {
+        "page": 2,
+        "page_size": 20,
+        "sort": "ASC",
+    }
+
+
+def test_pagination_parameters__null_values():
+    filter = PaginationFilter(batch=None, batch_size=None, newest_first=None)
+    assert filter.model_dump(exclude_none=True) == {}

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/tests/test_validators.py

@@ -5,7 +5,11 @@ from decimal import Decimal
 import pytest
 
 from afp import validators
-from afp.schemas import OrderFillFilter
+from afp.schemas import Model, Timestamp
+
+
+class DummyModel(Model):
+    timestamp: Timestamp
 
 
 def test_timestamp_conversion():
@@ -13,20 +17,12 @@ def test_timestamp_conversion():
     ts_time = 1893499200
 
     # timestamp -> datetime
-    filter = OrderFillFilter(
-        intent_account_id="",
-        product_id=None,
-        margin_account_id=None,
-        intent_hash=None,
-        start=None,
-        end=ts_time,  # type: ignore
-        trade_state=None,
-    )
-    assert filter.end is not None
-    assert filter.end.astimezone(UTC) == dt_time
+    instance = DummyModel(timestamp=ts_time)  # type: ignore
+    assert instance.timestamp is not None
+    assert instance.timestamp.astimezone(UTC) == dt_time
 
     # datetime -> timestamp
-    assert '"end":%d' % ts_time in filter.model_dump_json(exclude_none=True)
+    assert '"timestamp":%d' % ts_time in instance.model_dump_json()
 
 
 def test_validate_hexstr32__pass():

{afp_sdk-0.5.1 → afp_sdk-0.5.2}/uv.lock

@@ -13,7 +13,7 @@ wheels = [
 
 [[package]]
 name = "afp-sdk"
-version = "0.5.1"
+version = "0.5.2"
 source = { editable = "." }
 dependencies = [
     { name = "decorator" },

afp_sdk-0.5.1/tests/test_schemas.py

@@ -1,17 +0,0 @@
-from afp.schemas import Model
-
-
-class Person(Model):
-    first_name: str
-    last_name: str
-
-
-def test_schema_aliasing__from_json():
-    person = Person.model_validate_json('{"firstName":"Foo","lastName":"Bar"}')
-    assert person.first_name == "Foo"
-    assert person.last_name == "Bar"
-
-
-def test_schema_aliasing__to_json():
-    person = Person(first_name="Foo", last_name="Bar")
-    assert person.model_dump_json() == '{"firstName":"Foo","lastName":"Bar"}'