# Autonomous 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "afp-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "autonity, web3, trading, crypto, prediction, forecast, markets",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/91/76/034db3a83ece7af859d0c874b64f6b86a9466f089b0e4bb6e9abbc493719/afp_sdk-0.1.1.tar.gz",
"platform": null,
"description": "# Autonomous Futures Protocol Python SDK\n\n## Installation\n\nThis library is published on PyPI as the [afp-sdk](https://pypi.org/project/afp-sdk/)\npackage. It can be installed in a virtualenv with:\n\n```py\npip install afp-sdk\n```\n\n## Overview\n\nThe `afp` package consists of the following:\n\n- `afp` top-level module: High-level API for interacting with the Clearing\n System and the AutEx exchange.\n- `afp.bindings` submodule: Low-level API that provides typed Python bindings\n for the Clearing System smart contracts.\n\n## Usage\n\n### Preparation\n\nIn order to use the AFP system, traders need to prepare the following:\n\n- The ID of a product to be traded.\n- The address of the product's collateral token.\n- An Autonity account for managing the margin account. It needs to hold a\n balance in ATN (for paying gas fee) and in the product's collateral token.\n- An Autonity account for signing intents. The two accounts can be the same.\n- The address of an Autonity RPC provider. They can be found on\n [Chainlist](https://chainlist.org/?search=autonity&testnets=true).\n\nWe can store those in the following constants (using random example IDs):\n\n```py\nimport os\n\nPRODUCT_ID = \"0x38d502bb683f53ec7c3d7a14b4aa47ac717659e121426131c0189c15bf4b9460\"\nCOLLATERAL_ASSET = \"0xD1A1e4035a164cF42228A8aAaBC2c0Ac9e49687B\"\nMARGIN_ACCOUNT_PRIVATE_KEY = os.environ[\"MARGIN_ACCOUNT_PRIVATE_KEY\"]\nINTENT_ACCOUNT_PRIVATE_KEY = os.environ[\"INTENT_ACCOUNT_PRIVATE_KEY\"]\nAUTONITY_RPC_URL = \"https://bakerloo.autonity-apis.com\"\n```\n\nAccount IDs (addresses) may be retrieved from the private keys with `eth_account`:\n\n```py\nfrom eth_account import Account\n\nMARGIN_ACCOUNT_ID = Account.from_key(MARGIN_ACCOUNT_PRIVATE_KEY).address\nINTENT_ACCOUNT_ID = Account.from_key(INTENT_ACCOUNT_PRIVATE_KEY).address\n```\n\n### Clearing API\n\nFunctions of the Clearing API can be accessed via the `afp.Clearing`\nsession object. It connects to the specified Autonity RPC provider and\ncommunicates with the Clearing System smart contracts.\n\n```py\nimport afp\n\nclearing = afp.Clearing(MARGIN_ACCOUNT_PRIVATE_KEY, AUTONITY_RPC_URL)\n```\n\nCollateral can be deposited into the margin account with\n`clearing.deposit_into_margin_account()`.\n\n```py\nfrom decimal import Decimal\n\nclearing.deposit_into_margin_account(COLLATERAL_ASSET, Decimal(\"100.00\"))\nprint(clearing.capital(COLLATERAL_ASSET))\n```\n\nThe intent account should be authorized to submit orders. This is only required\nif the intent account and the margin account are different.\n\n```py\nclearing.authorize(COLLATERAL_ASSET, INTENT_ACCOUNT_ID)\n```\n\n### Trading API\n\nThe functions of the trading API can be accessed via the `afp.Trading` session\nobject. It communicates with the AutEx exchange and authenticates on creation with\nthe intent account's private key.\n\n```py\ntrading = afp.Trading(INTENT_ACCOUNT_PRIVATE_KEY)\n```\n\nTo start trading a product, its parameters shall be retrieved from the server.\n\n```py\nproduct = trading.product(PRODUCT_ID)\n```\n\nIntents can be created with `trading.create_intent()`. Intent creation involves\nhashing and signing the intent data. (The intent account's address is derived\nfrom the private key specified in the `Trading` constructor.)\n\n```py\nfrom datetime import datetime, timedelta\nfrom decimal import Decimal\n\nintent = trading.create_intent(\n margin_account_id=MARGIN_ACCOUNT_ID,\n product=product,\n side=\"bid\",\n limit_price=Decimal(\"1.23\"),\n quantity=2,\n max_trading_fee_rate=Decimal(\"0.1\"),\n good_until_time=datetime.now() + timedelta(hours=1),\n)\n```\n\nThe intent expressing a limit order can then be submitted to the exchange with\n`trading.submit_limit_order()` that returns the created order object.\n\n```py\norder = trading.submit_limit_order(intent)\nprint(order)\n```\n\nThe exchange then performs various checks to ensure that the order is valid. To\nensure that the order has been accepted, its state can be polled with\n`trading.order()`.\n\n```py\norder = trading.order(order.id)\nprint(order.state)\n```\n\nFills of orders submitted by the authenticated intent account can be queried\nwith `trading.order_fills()`.\n\n```py\nfills = trading.order_fills(product_id=PRODUCT_ID)\nprint(fills)\n```\n\nSee further code examples in the [examples](./examples/) directory.\n\n## Development\n\nThe package uses [`uv`](https://docs.astral.sh/uv/) as project manager.\n\n- Dependecies can be installed with the `uv sync` command.\n- Linters can be executed with the `uv run poe lint` command.\n- Tests can be executed with the `uv run poe test` command.\n- Distributions can be checked before release with the `uv run poe check-dist` command.\n- Markdown API documentation can be generated with the `uv run poe doc-gen` command.\n",
"bugtrack_url": null,
"license": null,
"summary": "Autonomous Futures Protocol Python SDK",
"version": "0.1.1",
"project_urls": {
"Changes": "https://github.com/autonity/afp-sdk/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/autonity/afp-sdk",
"Issues": "https://github.com/autonity/afp-sdk/issues",
"Source": "https://github.com/autonity/afp-sdk"
},
"split_keywords": [
"autonity",
" web3",
" trading",
" crypto",
" prediction",
" forecast",
" markets"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c86a1635b2e40b3299989b0c4d20bab5d8a1ecf10f35d94e6d805fe7fde84f8c",
"md5": "3de7de2de43ca0d0f3237d305973a890",
"sha256": "1645356f00dac413cd228d7516213b5e73fb7de81bfe5412fd3268437d828465"
},
"downloads": -1,
"filename": "afp_sdk-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3de7de2de43ca0d0f3237d305973a890",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 49256,
"upload_time": "2025-08-28T11:52:54",
"upload_time_iso_8601": "2025-08-28T11:52:54.143961Z",
"url": "https://files.pythonhosted.org/packages/c8/6a/1635b2e40b3299989b0c4d20bab5d8a1ecf10f35d94e6d805fe7fde84f8c/afp_sdk-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9176034db3a83ece7af859d0c874b64f6b86a9466f089b0e4bb6e9abbc493719",
"md5": "f1eaed57a21c5e7be15748553ef5bb68",
"sha256": "f5a0489f64883fa4ca7e01c34962de5c674dc3f0e94b957f39001dcf415c34d3"
},
"downloads": -1,
"filename": "afp_sdk-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f1eaed57a21c5e7be15748553ef5bb68",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 125711,
"upload_time": "2025-08-28T11:52:56",
"upload_time_iso_8601": "2025-08-28T11:52:56.016214Z",
"url": "https://files.pythonhosted.org/packages/91/76/034db3a83ece7af859d0c874b64f6b86a9466f089b0e4bb6e9abbc493719/afp_sdk-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 11:52:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "autonity",
"github_project": "afp-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "afp-sdk"
}
JSON
