# Firefly Client Library
[<img alt="Firefly logo" src="https://raw.githubusercontent.com/fireflyprotocol/firefly_exchange_client/main/res/banner.png" />](#)
<div align="center">
[](https://pypi.org/project/firefly_exchange_client/)
[](https://opensource.org/licenses/Apache-2.0)
</div>
Python Client for the Firefly Exchange API and Smart Contracts.
### Install
The package can be installed from [PyPi](https://pypi.org/project/firefly-exchange-client/) using pip:
```
pip install firefly-exchange-client
```
Alternatively, you could run:
```
pip install .
```
The package currently supports python `>=3.8`. Find complete documentation on the library at https://docs.firefly.exchange/.
### Getting Started
When initializing the client, users must accept [terms and conditions](https://firefly.exchange/terms-of-use) and define network object containing the following values:
```json
{
"url": "https://goerli-rollup.arbitrum.io/rpc",
"chainId": 421613,
"apiGateway": "https://dapi-testnet.firefly.exchange",
"socketURL": "wss://dapi-testnet.firefly.exchange",
"webSocketURL": "",
"onboardingUrl": "https://testnet.firefly.exchange",
},
```
Users can import predefined networks from [constants](https://github.com/fireflyprotocol/firefly_exchange_client/blob/main/src/firefly_exchange_client/constants.py):
```python
from firefly_exchange_client import Networks
```
For testing purposes use `Networks[TESTNET_ARBITRUM]` and for production please use `Networks[MAINNET_ARBITRUM]`
## Initialization example
```python
from config import TEST_ACCT_KEY, TEST_NETWORK
from firefly_exchange_client import FireflyClient, Networks
from pprint import pprint
import asyncio
async def main():
# initialize client
client = FireflyClient(
True, # agree to terms and conditions
Networks[TEST_NETWORK], # network to connect with
TEST_ACCT_KEY, # private key of wallet
)
# initialize the client
# on boards user on firefly. Must be set to true for first time use
await client.init(True)
print('Account Address:', client.get_public_address())
# # gets user account data on-chain
data = await client.get_user_account_data()
# close aio http connection
await client.apis.close_session()
pprint(data)
if __name__ == "__main__":
loop = asyncio.new_event_loop()
loop.run_until_complete(main())
loop.close()
```
**Read-only Initialization:**
Firefly-client can also be initialized in `read-only` mode, below is the example:
```python
from config import TEST_ACCT_KEY, TEST_NETWORK
from firefly_exchange_client import FireflyClient, Networks
from pprint import pprint
import asyncio
async def main():
# initialize client without providing private_key
client = FireflyClient(
True, # agree to terms and conditions
Networks[TEST_NETWORK], # network to connect with
)
# Initializing client for the private key provided. The second argument api_token is optional
await client.init(True,"54b0bfafc9a48728f76e52848a716e96d490263392e3959c2d44f05dea960761")
# close aio http connection
await client.apis.close_session()
await client.dmsApi.close_session()
pprint(data)
if __name__ == "__main__":
loop = asyncio.new_event_loop()
loop.run_until_complete(main())
loop.close()
```
Here is the [list](https://docs.bluefin.io/8/2.readonly-access-data) of APIs that can be accessed in `read-only` mode.
**Placing Orders:**
```python
from config import TEST_ACCT_KEY, TEST_NETWORK
from firefly_exchange_client import FireflyClient, Networks, MARKET_SYMBOLS, ORDER_SIDE, ORDER_TYPE, OrderSignatureRequest
import asyncio
async def main():
# initialize client
client = FireflyClient(
True, # agree to terms and conditions
Networks[TEST_NETWORK], # network to connect with
TEST_ACCT_KEY, # private key of wallet
)
await client.init(True)
# add market that you wish to trade on ETH/BTC are supported currently
client.add_market(MARKET_SYMBOLS.ETH)
user_leverage = await client.get_user_leverage(MARKET_SYMBOLS.ETH)
# creates a LIMIT order to be signed
signature_request = OrderSignatureRequest(
symbol=MARKET_SYMBOLS.ETH, # market symbol
price=1900, # price at which you want to place order
quantity=0.01, # quantity
side=ORDER_SIDE.SELL,
orderType=ORDER_TYPE.LIMIT,
leverage=user_leverage
)
# create signed order
signed_order = client.create_signed_order(signature_request)
print("Placing a limit order")
# place signed order on orderbook
resp = await client.post_signed_order(signed_order)
# returned order with PENDING state
print(resp)
await client.apis.close_session()
if __name__ == "__main__":
loop = asyncio.new_event_loop()
loop.run_until_complete(main())
loop.close()
```
**Listening To Events Using Socket.io:**
```python
from config import TEST_ACCT_KEY, TEST_NETWORK
from firefly_exchange_client import FireflyClient, Networks, SOCKET_EVENTS
import asyncio
import time
def callback(event):
print("Event data:", event)
async def main():
# initialize
client = FireflyClient(
True, # agree to terms and conditions
Networks[TEST_NETWORK], # network to connect with
TEST_ACCT_KEY, # private key of wallet
)
await client.init(True)
# make connection with firefly exchange
await client.socket.open()
# subscribe to local user events
await client.socket.subscribe_user_update_by_token()
# listen to exchange health updates and trigger callback
await client.socket.listen(SOCKET_EVENTS.EXCHANGE_HEALTH.value, callback)
time.sleep(10)
# unsubscribe from user events
await client.socket.unsubscribe_user_update_by_token()
# close socket connection
await client.socket.close()
if __name__ == "__main__":
loop = asyncio.new_event_loop()
loop.run_until_complete(main())
loop.close()
```
Look at the [example](https://github.com/fireflyprotocol/firefly_exchange_client/tree/main/examples) directory to see more examples on how to use this library.
**Listening To Events Using Web Sockets:**
```python
from config import TEST_ACCT_KEY, TEST_NETWORK
from firefly_exchange_client import FireflyClient, Networks, SOCKET_EVENTS, MARKET_SYMBOLS
import time
import asyncio
def callback(event):
print("Event data:", event)
async def main():
# initialize
client = FireflyClient(
True, # agree to terms and conditions
Networks[TEST_NETWORK], # network to connect with
TEST_ACCT_KEY, # private key of wallet
)
await client.init(True)
def on_open(ws):
# subscribe to global events
resp = client.webSocketClient.subscribe_global_updates_by_symbol(symbol=MARKET_SYMBOLS.ETH)
if resp:
print("Subscribed to global updates")
resp = client.webSocketClient.subscribe_user_update_by_token()
if resp:
print("Subscribed to user updates")
# make connection with firefly exchange
client.webSocketClient.initialize_socket(on_open=on_open)
# listen to user order updates and trigger callback
client.webSocketClient.listen(SOCKET_EVENTS.EXCHANGE_HEALTH.value, callback)
time.sleep(60)
# unsubscribe from global events
client.webSocketClient.unsubscribe_global_updates_by_symbol(symbol=MARKET_SYMBOLS.ETH)
client.webSocketClient.stop()
if __name__ == "__main__":
loop = asyncio.new_event_loop()
loop.run_until_complete(main())
loop.close()
```
Raw data
{
"_id": null,
"home_page": "",
"name": "firefly-exchange-client",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "firefly,exchange,decentralized,perpetuals,blockchain",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/03/25/bfae1f06344eb0f22296c32e74a452443079d18cb08ca2cfd60080650b29/firefly_exchange_client-0.10.13.tar.gz",
"platform": null,
"description": "# Firefly Client Library\n\n[<img alt=\"Firefly logo\" src=\"https://raw.githubusercontent.com/fireflyprotocol/firefly_exchange_client/main/res/banner.png\" />](#)\n\n<div align=\"center\">\n\n\n[](https://pypi.org/project/firefly_exchange_client/)\n[](https://opensource.org/licenses/Apache-2.0)\n\n</div>\n\nPython Client for the Firefly Exchange API and Smart Contracts.\n\u200b\n\n### Install\n\nThe package can be installed from [PyPi](https://pypi.org/project/firefly-exchange-client/) using pip:\n\n```\npip install firefly-exchange-client\n```\n\nAlternatively, you could run:\n\n```\npip install .\n```\n\nThe package currently supports python `>=3.8`. Find complete documentation on the library at https://docs.firefly.exchange/.\n\n### Getting Started\n\nWhen initializing the client, users must accept [terms and conditions](https://firefly.exchange/terms-of-use) and define network object containing the following values:\n\n```json\n{\n \"url\": \"https://goerli-rollup.arbitrum.io/rpc\",\n \"chainId\": 421613,\n \"apiGateway\": \"https://dapi-testnet.firefly.exchange\",\n \"socketURL\": \"wss://dapi-testnet.firefly.exchange\",\n \"webSocketURL\": \"\",\n \"onboardingUrl\": \"https://testnet.firefly.exchange\",\n},\n```\n\nUsers can import predefined networks from [constants](https://github.com/fireflyprotocol/firefly_exchange_client/blob/main/src/firefly_exchange_client/constants.py):\n\n```python\nfrom firefly_exchange_client import Networks\n```\n\nFor testing purposes use `Networks[TESTNET_ARBITRUM]` and for production please use `Networks[MAINNET_ARBITRUM]`\n\n## Initialization example\u200b\n\n```python\nfrom config import TEST_ACCT_KEY, TEST_NETWORK\nfrom firefly_exchange_client import FireflyClient, Networks\nfrom pprint import pprint\nimport asyncio\n\nasync def main():\n # initialize client\n client = FireflyClient(\n True, # agree to terms and conditions\n Networks[TEST_NETWORK], # network to connect with\n TEST_ACCT_KEY, # private key of wallet\n )\n\n # initialize the client\n # on boards user on firefly. Must be set to true for first time use\n await client.init(True)\n\n print('Account Address:', client.get_public_address())\n\n # # gets user account data on-chain\n data = await client.get_user_account_data()\n\n # close aio http connection\n await client.apis.close_session()\n\n pprint(data)\n\nif __name__ == \"__main__\":\n loop = asyncio.new_event_loop()\n loop.run_until_complete(main())\n loop.close()\n```\n\n**Read-only Initialization:**\nFirefly-client can also be initialized in `read-only` mode, below is the example:\n```python\nfrom config import TEST_ACCT_KEY, TEST_NETWORK\nfrom firefly_exchange_client import FireflyClient, Networks\nfrom pprint import pprint\nimport asyncio\n\nasync def main():\n # initialize client without providing private_key\n client = FireflyClient(\n True, # agree to terms and conditions\n Networks[TEST_NETWORK], # network to connect with\n )\n\n # Initializing client for the private key provided. The second argument api_token is optional\n await client.init(True,\"54b0bfafc9a48728f76e52848a716e96d490263392e3959c2d44f05dea960761\") \n\n # close aio http connection\n await client.apis.close_session()\n await client.dmsApi.close_session()\n\n pprint(data)\n\nif __name__ == \"__main__\":\n loop = asyncio.new_event_loop()\n loop.run_until_complete(main())\n loop.close()\n```\n\u200bHere is the [list](https://docs.bluefin.io/8/2.readonly-access-data) of APIs that can be accessed in `read-only` mode.\n\n**Placing Orders:**\n\n```python\nfrom config import TEST_ACCT_KEY, TEST_NETWORK\nfrom firefly_exchange_client import FireflyClient, Networks, MARKET_SYMBOLS, ORDER_SIDE, ORDER_TYPE, OrderSignatureRequest\nimport asyncio\n\nasync def main():\n # initialize client\n client = FireflyClient(\n True, # agree to terms and conditions\n Networks[TEST_NETWORK], # network to connect with\n TEST_ACCT_KEY, # private key of wallet\n )\n\n await client.init(True)\n\n # add market that you wish to trade on ETH/BTC are supported currently\n client.add_market(MARKET_SYMBOLS.ETH)\n\n user_leverage = await client.get_user_leverage(MARKET_SYMBOLS.ETH)\n\n # creates a LIMIT order to be signed\n signature_request = OrderSignatureRequest(\n symbol=MARKET_SYMBOLS.ETH, # market symbol\n price=1900, # price at which you want to place order\n quantity=0.01, # quantity\n side=ORDER_SIDE.SELL,\n orderType=ORDER_TYPE.LIMIT,\n leverage=user_leverage\n )\n\n # create signed order\n signed_order = client.create_signed_order(signature_request)\n\n print(\"Placing a limit order\")\n # place signed order on orderbook\n resp = await client.post_signed_order(signed_order)\n\n # returned order with PENDING state\n print(resp)\n\n await client.apis.close_session()\n\n\nif __name__ == \"__main__\":\n loop = asyncio.new_event_loop()\n loop.run_until_complete(main())\n loop.close()\n```\n\n\u200b\n**Listening To Events Using Socket.io:**\n\n```python\nfrom config import TEST_ACCT_KEY, TEST_NETWORK\nfrom firefly_exchange_client import FireflyClient, Networks, SOCKET_EVENTS\nimport asyncio\nimport time\n\ndef callback(event):\n print(\"Event data:\", event)\n\nasync def main():\n # initialize\n client = FireflyClient(\n True, # agree to terms and conditions\n Networks[TEST_NETWORK], # network to connect with\n TEST_ACCT_KEY, # private key of wallet\n )\n await client.init(True)\n # make connection with firefly exchange\n await client.socket.open()\n\n # subscribe to local user events\n await client.socket.subscribe_user_update_by_token()\n\n # listen to exchange health updates and trigger callback\n await client.socket.listen(SOCKET_EVENTS.EXCHANGE_HEALTH.value, callback)\n time.sleep(10)\n # unsubscribe from user events\n await client.socket.unsubscribe_user_update_by_token()\n # close socket connection\n await client.socket.close()\n\nif __name__ == \"__main__\":\n loop = asyncio.new_event_loop()\n loop.run_until_complete(main())\n loop.close()\u200b\n```\n\nLook at the [example](https://github.com/fireflyprotocol/firefly_exchange_client/tree/main/examples) directory to see more examples on how to use this library.\n\n**Listening To Events Using Web Sockets:**\n\n```python\nfrom config import TEST_ACCT_KEY, TEST_NETWORK\nfrom firefly_exchange_client import FireflyClient, Networks, SOCKET_EVENTS, MARKET_SYMBOLS\nimport time\nimport asyncio\n\ndef callback(event):\n print(\"Event data:\", event)\n\nasync def main():\n # initialize\n client = FireflyClient(\n True, # agree to terms and conditions\n Networks[TEST_NETWORK], # network to connect with\n TEST_ACCT_KEY, # private key of wallet\n )\n\n await client.init(True)\n\n def on_open(ws):\n # subscribe to global events\n resp = client.webSocketClient.subscribe_global_updates_by_symbol(symbol=MARKET_SYMBOLS.ETH)\n if resp:\n print(\"Subscribed to global updates\")\n resp = client.webSocketClient.subscribe_user_update_by_token()\n if resp:\n print(\"Subscribed to user updates\")\n\n # make connection with firefly exchange\n client.webSocketClient.initialize_socket(on_open=on_open)\n # listen to user order updates and trigger callback\n client.webSocketClient.listen(SOCKET_EVENTS.EXCHANGE_HEALTH.value, callback)\n\n time.sleep(60)\n\n # unsubscribe from global events\n client.webSocketClient.unsubscribe_global_updates_by_symbol(symbol=MARKET_SYMBOLS.ETH)\n client.webSocketClient.stop()\n\n\nif __name__ == \"__main__\":\n loop = asyncio.new_event_loop()\n loop.run_until_complete(main())\n loop.close()\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Library to interact with firefly exchange protocol including its off-chain api-gateway and on-chain contracts",
"version": "0.10.13",
"project_urls": {
"Bug Reports": "https://github.com/fireflyprotocol/firefly_exchange_client/issues",
"Homepage": "https://github.com/fireflyprotocol/firefly_exchange_client",
"Source": "https://github.com/fireflyprotocol/firefly_exchange_client/"
},
"split_keywords": [
"firefly",
"exchange",
"decentralized",
"perpetuals",
"blockchain"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9ef90bfadc908e628d1bbcf407fc0f3347d37c2b8b2490e662daa68866341694",
"md5": "ff39ef0a6af2d7db3227e5fec066362f",
"sha256": "4db1192b26cd3a55d169c517d0efbeb243e2feb4df4715153e68b6d7bdfbaad0"
},
"downloads": -1,
"filename": "firefly_exchange_client-0.10.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff39ef0a6af2d7db3227e5fec066362f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 39271,
"upload_time": "2023-12-26T09:19:54",
"upload_time_iso_8601": "2023-12-26T09:19:54.154639Z",
"url": "https://files.pythonhosted.org/packages/9e/f9/0bfadc908e628d1bbcf407fc0f3347d37c2b8b2490e662daa68866341694/firefly_exchange_client-0.10.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0325bfae1f06344eb0f22296c32e74a452443079d18cb08ca2cfd60080650b29",
"md5": "5b8c1b6c68334f05480e153c08786834",
"sha256": "2c1f9f576785ef7b267cbc9ab1d7b124e472d7f95fb31d7bca47257e4dde4226"
},
"downloads": -1,
"filename": "firefly_exchange_client-0.10.13.tar.gz",
"has_sig": false,
"md5_digest": "5b8c1b6c68334f05480e153c08786834",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36819,
"upload_time": "2023-12-26T09:19:56",
"upload_time_iso_8601": "2023-12-26T09:19:56.832687Z",
"url": "https://files.pythonhosted.org/packages/03/25/bfae1f06344eb0f22296c32e74a452443079d18cb08ca2cfd60080650b29/firefly_exchange_client-0.10.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-26 09:19:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fireflyprotocol",
"github_project": "firefly_exchange_client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "firefly-exchange-client"
}
JSON
