afp-sdk 0.1.0__tar.gz

afp_sdk-0.1.0/.env.template

@@ -0,0 +1,6 @@
+# AFP_EXCHANGE_URL=
+# AFP_CHAIN_ID=
+# AFP_CLEARING_DIAMOND_ADDRESS=
+# AFP_MARGIN_ACCOUNT_REGISTRY_ADDRESS=
+# AFP_ORACLE_PROVIDER_ADDRESS=
+# AFP_PRODUCT_REGISTRY_ADDRESS=

afp_sdk-0.1.0/.envrc

@@ -0,0 +1,5 @@
+export DIRENV_WARN_TIMEOUT=20s
+
+eval "$(devenv direnvrc)"
+
+use devenv

afp_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [v0.1.0] - 2025-08-22
+
+_First release._
+
+[v0.1.0]: https://github.com/autonity/afp-sdk/releases/tag/v0.1.0

afp_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Autonity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

afp_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: afp-sdk
+Version: 0.1.0
+Summary: Autonity Futures Protocol Python SDK
+Keywords: autonity,web3,trading,crypto,prediction,forecast,markets
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: decorator>=5.2.1
+Requires-Dist: inflection>=0.5.1
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: requests>=2.32.0
+Requires-Dist: siwe>=4.4.0
+Requires-Dist: web3>=7.6.0
+Requires-Python: >=3.11
+Project-URL: Changes, https://github.com/autonity/afp-sdk/blob/master/CHANGELOG.md
+Project-URL: Homepage, https://github.com/autonity/afp-sdk
+Project-URL: Issues, https://github.com/autonity/afp-sdk/issues
+Project-URL: Source, https://github.com/autonity/afp-sdk
+Description-Content-Type: text/markdown
+
+# Autonity Futures Protocol Python SDK
+
+## Installation
+
+This library is published on PyPI as the [afp-sdk](https://pypi.org/project/afp-sdk/)
+package. It can be installed in a virtualenv with:
+
+```py
+pip install afp-sdk
+```
+
+## Overview
+
+The `afp` package consists of the following:
+
+- `afp` top-level module: High-level API for interacting with the Clearing
+  System and the AutEx exchange.
+- `afp.bindings` submodule: Low-level API that provides typed Python bindings
+  for the Clearing System smart contracts.
+
+## Usage
+
+### Preparation
+
+In order to use the AFP system, traders need to prepare the following:
+
+- The ID of a product to be traded.
+- The address of the product's collateral token.
+- An Autonity account for managing the margin account. It needs to hold a
+  balance in ATN (for paying gas fee) and in the product's collateral token.
+- An Autonity account for signing intents. The two accounts can be the same.
+- The address of an Autonity RPC provider. They can be found on
+  [Chainlist](https://chainlist.org/?search=autonity&testnets=true).
+
+We can store those in the following constants (using random example IDs):
+
+```py
+import os
+
+PRODUCT_ID = "0x38d502bb683f53ec7c3d7a14b4aa47ac717659e121426131c0189c15bf4b9460"
+COLLATERAL_ASSET = "0xD1A1e4035a164cF42228A8aAaBC2c0Ac9e49687B"
+MARGIN_ACCOUNT_PRIVATE_KEY = os.environ["MARGIN_ACCOUNT_PRIVATE_KEY"]
+INTENT_ACCOUNT_PRIVATE_KEY = os.environ["INTENT_ACCOUNT_PRIVATE_KEY"]
+AUTONITY_RPC_URL = "https://bakerloo.autonity-apis.com"
+```
+
+Account IDs (addresses) may be retrieved from the private keys with `eth_account`:
+
+```py
+from eth_account import Account
+
+MARGIN_ACCOUNT_ID = Account.from_key(MARGIN_ACCOUNT_PRIVATE_KEY).address
+INTENT_ACCOUNT_ID = Account.from_key(INTENT_ACCOUNT_PRIVATE_KEY).address
+```
+
+### Clearing API
+
+Functions of the Clearing API can be accessed via the `afp.Clearing`
+session object. It connects to the specified Autonity RPC provider and
+communicates with the Clearing System smart contracts.
+
+```py
+import afp
+
+clearing = afp.Clearing(MARGIN_ACCOUNT_PRIVATE_KEY, AUTONITY_RPC_URL)
+```
+
+Collateral can be deposited into the margin account with
+`clearing.deposit_into_margin_account()`.
+
+```py
+from decimal import Decimal
+
+clearing.deposit_into_margin_account(COLLATERAL_ASSET, Decimal("100.00"))
+print(clearing.capital(COLLATERAL_ASSET))
+```
+
+The intent account should be authorized to submit orders. This is only required
+if the intent account and the margin account are different.
+
+```py
+clearing.authorize(COLLATERAL_ASSET, INTENT_ACCOUNT_ID)
+```
+
+### Trading API
+
+The functions of the trading API can be accessed via the `afp.Trading` session
+object. It communicates with the AutEx exchange and authenticates on creation with
+the intent account's private key.
+
+```py
+trading = afp.Trading(INTENT_ACCOUNT_PRIVATE_KEY)
+```
+
+To start trading a product, its parameters shall be retrieved from the server.
+
+```py
+product = trading.product(PRODUCT_ID)
+```
+
+Intents can be created with `trading.create_intent()`. Intent creation involves
+hashing and signing the intent data. (The intent account's address is derived
+from the private key specified in the `Trading` constructor.)
+
+```py
+from datetime import datetime, timedelta
+from decimal import Decimal
+
+intent = trading.create_intent(
+    margin_account_id=MARGIN_ACCOUNT_ID,
+    product=product,
+    side="bid",
+    limit_price=Decimal("1.23"),
+    quantity=2,
+    max_trading_fee_rate=Decimal("0.1"),
+    good_until_time=datetime.now() + timedelta(hours=1),
+)
+```
+
+The intent expressing a limit order can then be submitted to the exchange with
+`trading.submit_limit_order()` that returns the created order object.
+
+```py
+order = trading.submit_limit_order(intent)
+print(order)
+```
+
+The exchange then performs various checks to ensure that the order is valid. To
+ensure that the order has been accepted, its state can be polled with
+`trading.order()`.
+
+```py
+order = trading.order(order.id)
+print(order.state)
+```
+
+Fills of orders submitted by the authenticated intent account can be queried
+with `trading.order_fills()`.
+
+```py
+fills = trading.order_fills(product_id=PRODUCT_ID)
+print(fills)
+```
+
+See further code examples in the [examples](./examples/) directory.
+
+## Development
+
+The package uses [`uv`](https://docs.astral.sh/uv/) as project manager.
+
+- Dependecies can be installed with the `uv sync` command.
+- Linters can be executed with the `uv run poe lint` command.
+- Tests can be executed with the `uv run poe test` command.
+- Distributions can be checked before release with the `uv run poe check-dist` command.
+- Markdown API documentation can be generated with the `uv run poe doc-gen` command.

afp_sdk-0.1.0/README.md

@@ -0,0 +1,155 @@
+# Autonity Futures Protocol Python SDK
+
+## Installation
+
+This library is published on PyPI as the [afp-sdk](https://pypi.org/project/afp-sdk/)
+package. It can be installed in a virtualenv with:
+
+```py
+pip install afp-sdk
+```
+
+## Overview
+
+The `afp` package consists of the following:
+
+- `afp` top-level module: High-level API for interacting with the Clearing
+  System and the AutEx exchange.
+- `afp.bindings` submodule: Low-level API that provides typed Python bindings
+  for the Clearing System smart contracts.
+
+## Usage
+
+### Preparation
+
+In order to use the AFP system, traders need to prepare the following:
+
+- The ID of a product to be traded.
+- The address of the product's collateral token.
+- An Autonity account for managing the margin account. It needs to hold a
+  balance in ATN (for paying gas fee) and in the product's collateral token.
+- An Autonity account for signing intents. The two accounts can be the same.
+- The address of an Autonity RPC provider. They can be found on
+  [Chainlist](https://chainlist.org/?search=autonity&testnets=true).
+
+We can store those in the following constants (using random example IDs):
+
+```py
+import os
+
+PRODUCT_ID = "0x38d502bb683f53ec7c3d7a14b4aa47ac717659e121426131c0189c15bf4b9460"
+COLLATERAL_ASSET = "0xD1A1e4035a164cF42228A8aAaBC2c0Ac9e49687B"
+MARGIN_ACCOUNT_PRIVATE_KEY = os.environ["MARGIN_ACCOUNT_PRIVATE_KEY"]
+INTENT_ACCOUNT_PRIVATE_KEY = os.environ["INTENT_ACCOUNT_PRIVATE_KEY"]
+AUTONITY_RPC_URL = "https://bakerloo.autonity-apis.com"
+```
+
+Account IDs (addresses) may be retrieved from the private keys with `eth_account`:
+
+```py
+from eth_account import Account
+
+MARGIN_ACCOUNT_ID = Account.from_key(MARGIN_ACCOUNT_PRIVATE_KEY).address
+INTENT_ACCOUNT_ID = Account.from_key(INTENT_ACCOUNT_PRIVATE_KEY).address
+```
+
+### Clearing API
+
+Functions of the Clearing API can be accessed via the `afp.Clearing`
+session object. It connects to the specified Autonity RPC provider and
+communicates with the Clearing System smart contracts.
+
+```py
+import afp
+
+clearing = afp.Clearing(MARGIN_ACCOUNT_PRIVATE_KEY, AUTONITY_RPC_URL)
+```
+
+Collateral can be deposited into the margin account with
+`clearing.deposit_into_margin_account()`.
+
+```py
+from decimal import Decimal
+
+clearing.deposit_into_margin_account(COLLATERAL_ASSET, Decimal("100.00"))
+print(clearing.capital(COLLATERAL_ASSET))
+```
+
+The intent account should be authorized to submit orders. This is only required
+if the intent account and the margin account are different.
+
+```py
+clearing.authorize(COLLATERAL_ASSET, INTENT_ACCOUNT_ID)
+```
+
+### Trading API
+
+The functions of the trading API can be accessed via the `afp.Trading` session
+object. It communicates with the AutEx exchange and authenticates on creation with
+the intent account's private key.
+
+```py
+trading = afp.Trading(INTENT_ACCOUNT_PRIVATE_KEY)
+```
+
+To start trading a product, its parameters shall be retrieved from the server.
+
+```py
+product = trading.product(PRODUCT_ID)
+```
+
+Intents can be created with `trading.create_intent()`. Intent creation involves
+hashing and signing the intent data. (The intent account's address is derived
+from the private key specified in the `Trading` constructor.)
+
+```py
+from datetime import datetime, timedelta
+from decimal import Decimal
+
+intent = trading.create_intent(
+    margin_account_id=MARGIN_ACCOUNT_ID,
+    product=product,
+    side="bid",
+    limit_price=Decimal("1.23"),
+    quantity=2,
+    max_trading_fee_rate=Decimal("0.1"),
+    good_until_time=datetime.now() + timedelta(hours=1),
+)
+```
+
+The intent expressing a limit order can then be submitted to the exchange with
+`trading.submit_limit_order()` that returns the created order object.
+
+```py
+order = trading.submit_limit_order(intent)
+print(order)
+```
+
+The exchange then performs various checks to ensure that the order is valid. To
+ensure that the order has been accepted, its state can be polled with
+`trading.order()`.
+
+```py
+order = trading.order(order.id)
+print(order.state)
+```
+
+Fills of orders submitted by the authenticated intent account can be queried
+with `trading.order_fills()`.
+
+```py
+fills = trading.order_fills(product_id=PRODUCT_ID)
+print(fills)
+```
+
+See further code examples in the [examples](./examples/) directory.
+
+## Development
+
+The package uses [`uv`](https://docs.astral.sh/uv/) as project manager.
+
+- Dependecies can be installed with the `uv sync` command.
+- Linters can be executed with the `uv run poe lint` command.
+- Tests can be executed with the `uv run poe test` command.
+- Distributions can be checked before release with the `uv run poe check-dist` command.
+- Markdown API documentation can be generated with the `uv run poe doc-gen` command.

afp_sdk-0.1.0/afp/__init__.py

@@ -0,0 +1,10 @@
+"""Autonity Futures Protocol Python SDK."""
+
+from afp import bindings
+from .api.admin import Admin
+from .api.builder import Builder
+from .api.clearing import Clearing
+from .api.liquidation import Liquidation
+from .api.trading import Trading
+
+__all__ = ("bindings", "Admin", "Builder", "Clearing", "Liquidation", "Trading")

afp_sdk-0.1.0/afp/api/admin.py

@@ -0,0 +1,55 @@
+from .. import validators
+from ..decorators import refresh_token_on_expiry
+from ..schemas import ExchangeProductSubmission
+from .base import ExchangeAPI
+
+
+class Admin(ExchangeAPI):
+    """API for AutEx administration, restricted to AutEx admins.
+
+    Authenticates with the exchange on creation.
+
+    Parameters
+    ----------
+    private_key : str
+        The private key of the exchange adminstrator account.
+
+    Raises
+    ------
+    afp.exceptions.AuthenticationError
+        If the exchange rejects the login attempt.
+    """
+
+    @refresh_token_on_expiry
+    def approve_product(self, product_id: str) -> None:
+        """Approves a product for trading on the exchange.
+
+        Parameters
+        ----------
+        product_id : str
+
+        Raises
+        ------
+        afp.exceptions.AuthorizationError
+            If the configured account is not an exchange administrator.
+        """
+        product = ExchangeProductSubmission(id=product_id)
+        self._exchange.approve_product(product)
+
+    @refresh_token_on_expiry
+    def delist_product(self, product_id: str) -> None:
+        """Delists a product from the exchange.
+
+        New order submissions of this product will be rejected.
+
+        Parameters
+        ----------
+        product_id : str
+
+        Raises
+        ------
+        afp.exceptions.AuthorizationError
+            If the configured account is not an exchange administrator.
+        """
+        value = validators.validate_hexstr32(product_id)
+        self._exchange.delist_product(value)

afp_sdk-0.1.0/afp/api/base.py

@@ -0,0 +1,76 @@
+from abc import ABC
+from datetime import datetime
+from functools import cache
+from typing import cast
+from urllib.parse import urlparse
+
+from eth_account.account import Account
+from eth_account.signers.local import LocalAccount
+from eth_typing.evm import ChecksumAddress
+from siwe import ISO8601Datetime, SiweMessage, siwe  # type: ignore (untyped library)
+from web3 import Web3, HTTPProvider
+from web3.middleware import Middleware, SignAndSendRawMiddlewareBuilder
+
+from .. import config, signing
+from ..bindings.erc20 import ERC20
+from ..exchange import ExchangeClient
+from ..schemas import LoginSubmission
+
+
+EXCHANGE_DOMAIN = urlparse(config.EXCHANGE_URL).netloc
+
+
+class ClearingSystemAPI(ABC):
+    _account: LocalAccount
+    _w3: Web3
+
+    def __init__(self, private_key: str, autonity_rpc_url: str):
+        self._account = Account.from_key(private_key)
+        self._w3 = Web3(HTTPProvider(autonity_rpc_url))
+
+        # Configure the default sender account
+        self._w3.eth.default_account = self._account.address
+        signing_middleware = SignAndSendRawMiddlewareBuilder.build(self._account)
+        self._w3.middleware_onion.add(cast(Middleware, signing_middleware))
+
+    @cache
+    def _decimals(self, collateral_asset: ChecksumAddress) -> int:
+        token_contract = ERC20(self._w3, collateral_asset)
+        return token_contract.decimals()
+
+
+class ExchangeAPI(ABC):
+    _account: LocalAccount
+    _exchange: ExchangeClient
+    _trading_protocol_id: str
+
+    def __init__(self, private_key: str):
+        self._account = Account.from_key(private_key)
+        self._exchange = ExchangeClient()
+        self._login()
+
+    def _login(self):
+        nonce = self._exchange.generate_login_nonce()
+        message = self._generate_eip4361_message(self._account, nonce)
+        signature = signing.sign_message(self._account, message.encode("ascii"))
+
+        login_submission = LoginSubmission(
+            message=message, signature=Web3.to_hex(signature)
+        )
+        exchange_parameters = self._exchange.login(login_submission)
+
+        self._trading_protocol_id = exchange_parameters.trading_protocol_id
+
+    @staticmethod
+    def _generate_eip4361_message(account: LocalAccount, nonce: str) -> str:
+        message = SiweMessage(
+            domain=EXCHANGE_DOMAIN,
+            address=account.address,
+            uri=config.EXCHANGE_URL,
+            version=siwe.VersionEnum.one,  # type: ignore
+            chain_id=config.CHAIN_ID,
+            issued_at=ISO8601Datetime.from_datetime(datetime.now()),
+            nonce=nonce,
+            statement=None,
+        )
+        return message.prepare_message()