| Name | orderly-evm-connector JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | This is a lightweight library that works as a connector to Orderly API and Websocket. |
| upload_time | 2024-11-08 17:36:34 |
| maintainer | None |
| docs_url | None |
| author | Orderly Tech |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Orderly Open API Connector Python
[](https://pypi.python.org/pypi/Pypi)
[](https://www.python.org/downloads/)
[](https://github.com/OrderlyNetwork/orderly-evm-connector-python)
[](https://black.readthedocs.io/en/stable/)
[](https://opensource.org/licenses/MIT)
Orderly Open API Connector Python is a connector to [Orderly open API](https://orderly.network/docs/build-on-evm/evm-api/introduction)
- Supported APIs:
- Public API Endpoints
- Private API Endpoints
- Websockets API Endpoints
- Inclusion of test cases and examples
- Client for both Mainnet and Testnet
- Utility methods needed for connecting Orderly Endpoints such as authentication
Note: This connector is for Orderly EVM. It is not compatible with Orderly NEAR.
## Installation
```bash
pip install orderly-evm-connector
```
## Documentation
[https://orderly.network/docs/build-on-evm/building-on-evm](https://orderly.network/docs/build-on-evm/building-on-evm)
## RESTful APIs
Usage examples:
```python
from orderly_evm_connector.rest import Rest as Client
from orderly_evm_connector.lib.utils import get_account_info
(
orderly_key,
orderly_secret,
orderly_account_id,
orderly_testnet,
wallet_secret,
wss_id,
) = get_account_info('config.ini')
client = Client(
orderly_key=orderly_key,
orderly_secret=orderly_secret,
orderly_account_id=orderly_account_id,
orderly_testnet=True,
timeout=5
)
# Orders APIs
response = client.create_order(
symbol="PERP_NEAR_USDC",
order_type="LIMIT",
side="BUY",
order_price=1.95,
order_quantity=1,
)
```
Please find `examples` folder in github to check for more endpoints.
- In order to set your Orderly Key and Orderly Secret for use of the examples, create a file `config.ini` with your keys.
- Eg:
```ini
# examples/config.ini
[keys]
orderly_key=ed25519:xxxx
orderly_secret=ed25519:xxxx
orderly_account_id=0xaaaa
orderly_testnet=False
wallet_secret=xxxx
wss_id=ClientID
debug=False
```
### Display logs
Setting the `debug=True` will log the request URL, payload and response text.
### Authentication
Requests to Orderly API needs to be signed using `orderly-key` and `orderly-secret`.
Orderly Network uses the `ed25519` elliptic curve standard for request authentication. The `lib.utils` class provides methods for signing and generating request signatures.
```python
from orderly_evm_connector.lib.utils import generate_signature
orderly_secret = "YOUR_ORDERLY_SECRET_HERE"
# A normalized orderly request string, see Authentication section of the Orderly API Doc for details
request_str = """1649920583000POST/v1/order{"symbol": "SPOT_NEAR_USDC", "order_type": "LIMIT", "order_price": 15.23, "order_quantity": 23.11, "side": "BUY"}"""
sginature = generate_signature(orderly_secret, request_str)
```
### Heartbeat
Once connected, the websocket server sends a ping frame every 10 seconds and is asked to return a response pong frame within 1 minute. This package automatically handles pong responses.
### Reconnect
Once the connection is abnormal, the websocket connection tries a maximum of 30 times every 5s`(WEBSOCKET_RETRY_SLEEP_TIME = 5`,`WEBSOCKET_FAILED_MAX_RETRIES = 30`). After the connection is established, the subscription is completed again
### Testnet
When creating a Rest or Websocket client, set the `orderly_testnet` parameter to true to use Testnet.
```python
orderly_testnet = True
# Private Websocket Client on Testnet
wss_client = WebsocketPrivateAPIClient(
orderly_testnet=orderly_testnet,
orderly_account_id=orderly_account_id,
wss_id=wss_id,
orderly_key=orderly_key,
orderly_secret=orderly_secret,
on_message=message_handler,
on_close=on_close,
)
# Private REST API Client
client = Client(
orderly_key=orderly_key,
orderly_secret=orderly_secret,
orderly_account_id=orderly_account_id,
orderly_testnet=orderly_testnet,
timeout=5
)
```
### Error
There are 2 types of error returned from the library:
- `orderly_evm_connector.error.ClientError`
- This is thrown when server returns `4XX`, it's an issue from client side.
- It has 5 properties:
- `status_code` - HTTP status code
- `error_code` - Server's error code, e.g. `-1102`
- `error_message` - Server's error message, e.g. `Unknown order sent.`
- `header` - Full response header.
- `error_data`* - Additional detailed data which supplements the `error_message`.
- **Only applicable on select endpoints, eg. `cancelReplace`*
- `orderly_evm_connector.error.ServerError`
- This is thrown when server returns `5XX`, it's an issue from server side.
In addition, there are 3 types of Parameter Error:
- `orderly_evm_connector.error.ParameterRequiredError`
- This error is thrown when a required parameter for the endpoint is not present in the request.
- `orderly_evm_connector.error.ParameterValueError`
- This error is thrown when a value passed in for an ENUM type parameter is invalid. For example the `order_type` parameter is an ENUM with a fixed set of values users could pass in. Passing a value out of the ENUM definition will result in this error.
- `orderly_evm_connector.error.ParameterTypeError`
- This error is thrown when a value passed in is not in consistency with the type definition of the parameter.
Websocket Client has 1 type of Error:
- `WebsocketClientError`
- This error is thrown when there is an exception thrown by the WebsocketClient class.
## Websocket
### Websocket Client
Orderly has two Websocket endpoints, the Market Data Base Endpoint(public endpoint) and the Private User Data Stream Base Endpoint(private endpoint).
`orderly-connector` supports connecting to both endpoints in both Mainnet and Testnet. See below for example:
```python
from orderly_evm_connector.lib.utils import get_account_info
import time, logging
from orderly_evm_connector.websocket.websocket_api import WebsocketPublicAPIClient
(
orderly_key,
orderly_secret,
orderly_account_id,
orderly_testnet,
wallet_secret,
wss_id,
) = get_account_info('config.ini')
def on_close(_):
logging.info("Do custom stuff when connection is closed")
def message_handler(_, message):
logging.info(message)
# Public websocket does not need to pass orderly_key and orderly_secret arguments
wss_client = WebsocketPublicAPIClient(
orderly_testnet=orderly_testnet,
orderly_account_id=orderly_account_id,
wss_id=wss_id,
on_message=message_handler,
on_close=on_close,
debug=True,
)
wss_client.get_24h_tickers()
time.sleep(1000)
wss_client.stop()
```
For private endpoint, user will need to pass in the `orderly_key` and `orderly_secret` to the `orderly.websocket.WebsocketPrivateAPIClient` class.
Private endpoint also requires signature of the message sent using `orderly_key` and `orderly_secret`. This function is encapsulated by the `WebsocketPrivateAPIClient` class. See Orderly API Docs for more detai.
```python
from orderly_evm_connector.websocket.websocket_api import WebsocketPrivateAPIClient
wss_client = WebsocketPrivateAPIClient(
orderly_testnet=orderly_testnet,
orderly_account_id=orderly_account_id,
wss_id=wss_id,
orderly_key=orderly_key,
orderly_secret=orderly_secret,
on_message=message_handler,
on_close=on_close,
debug=True,
)
# wss_client.get_liquidator_liquidations()
wss_client.get_notifications()
time.sleep(1000)
wss_client.stop()
```
#### wss_id
`wss_id` is the request id of included in each of websocket request to orderly. This is defined by user and has a max length of 64 bytes.
## Limitation
## Contributing
Contributions are welcome.<br/>
If you've found a bug within this project, please open an issue to discuss what you would like to change.<br/>
If it's an issue with the API, please open a topic at [Orderly Developer Community]()
Raw data
{
"_id": null,
"home_page": null,
"name": "orderly-evm-connector",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Orderly Tech",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6c/b7/1e6e81752da33a94b1e590d2eb4ef74912992d25fb8cbe58198e8b909f6a/orderly_evm_connector-0.2.1.tar.gz",
"platform": null,
"description": "# Orderly Open API Connector Python\n[](https://pypi.python.org/pypi/Pypi)\n[](https://www.python.org/downloads/)\n[](https://github.com/OrderlyNetwork/orderly-evm-connector-python)\n[](https://black.readthedocs.io/en/stable/)\n[](https://opensource.org/licenses/MIT)\n\nOrderly Open API Connector Python is a connector to [Orderly open API](https://orderly.network/docs/build-on-evm/evm-api/introduction)\n\n- Supported APIs:\n - Public API Endpoints\n - Private API Endpoints\n - Websockets API Endpoints\n- Inclusion of test cases and examples\n- Client for both Mainnet and Testnet\n- Utility methods needed for connecting Orderly Endpoints such as authentication\n\nNote: This connector is for Orderly EVM. It is not compatible with Orderly NEAR.\n\n## Installation\n\n```bash\npip install orderly-evm-connector\n```\n\n## Documentation\n\n[https://orderly.network/docs/build-on-evm/building-on-evm](https://orderly.network/docs/build-on-evm/building-on-evm)\n\n## RESTful APIs\n\nUsage examples:\n```python\nfrom orderly_evm_connector.rest import Rest as Client\nfrom orderly_evm_connector.lib.utils import get_account_info\n\n(\n orderly_key,\n orderly_secret,\n orderly_account_id,\n orderly_testnet,\n wallet_secret,\n wss_id,\n) = get_account_info('config.ini')\nclient = Client(\n orderly_key=orderly_key,\n orderly_secret=orderly_secret,\n orderly_account_id=orderly_account_id,\n orderly_testnet=True,\n timeout=5\n)\n\n# Orders APIs\nresponse = client.create_order(\n symbol=\"PERP_NEAR_USDC\",\n order_type=\"LIMIT\",\n side=\"BUY\",\n order_price=1.95,\n order_quantity=1,\n)\n```\nPlease find `examples` folder in github to check for more endpoints.\n- In order to set your Orderly Key and Orderly Secret for use of the examples, create a file `config.ini` with your keys.\n- Eg:\n ```ini\n # examples/config.ini\n [keys]\n orderly_key=ed25519:xxxx\n orderly_secret=ed25519:xxxx\n orderly_account_id=0xaaaa\n orderly_testnet=False\n wallet_secret=xxxx\n wss_id=ClientID\n debug=False\n ```\n### Display logs\n\nSetting the `debug=True` will log the request URL, payload and response text.\n\n### Authentication\n\nRequests to Orderly API needs to be signed using `orderly-key` and `orderly-secret`. \nOrderly Network uses the `ed25519` elliptic curve standard for request authentication. The `lib.utils` class provides methods for signing and generating request signatures.\n\n```python\nfrom orderly_evm_connector.lib.utils import generate_signature\n\norderly_secret = \"YOUR_ORDERLY_SECRET_HERE\"\n\n# A normalized orderly request string, see Authentication section of the Orderly API Doc for details\nrequest_str = \"\"\"1649920583000POST/v1/order{\"symbol\": \"SPOT_NEAR_USDC\", \"order_type\": \"LIMIT\", \"order_price\": 15.23, \"order_quantity\": 23.11, \"side\": \"BUY\"}\"\"\"\nsginature = generate_signature(orderly_secret, request_str)\n```\n\n### Heartbeat\n\nOnce connected, the websocket server sends a ping frame every 10 seconds and is asked to return a response pong frame within 1 minute. This package automatically handles pong responses.\n\n### Reconnect\n\nOnce the connection is abnormal, the websocket connection tries a maximum of 30 times every 5s`(WEBSOCKET_RETRY_SLEEP_TIME = 5`,`WEBSOCKET_FAILED_MAX_RETRIES = 30`). After the connection is established, the subscription is completed again\n\n\n### Testnet\nWhen creating a Rest or Websocket client, set the `orderly_testnet` parameter to true to use Testnet.\n\n```python\norderly_testnet = True\n\n# Private Websocket Client on Testnet\nwss_client = WebsocketPrivateAPIClient(\n orderly_testnet=orderly_testnet,\n orderly_account_id=orderly_account_id,\n wss_id=wss_id,\n orderly_key=orderly_key,\n orderly_secret=orderly_secret,\n on_message=message_handler,\n on_close=on_close,\n)\n\n# Private REST API Client\nclient = Client(\n orderly_key=orderly_key,\n orderly_secret=orderly_secret,\n orderly_account_id=orderly_account_id,\n orderly_testnet=orderly_testnet,\n timeout=5\n)\n```\n\n### Error\n\nThere are 2 types of error returned from the library:\n- `orderly_evm_connector.error.ClientError`\n - This is thrown when server returns `4XX`, it's an issue from client side.\n - It has 5 properties:\n - `status_code` - HTTP status code\n - `error_code` - Server's error code, e.g. `-1102`\n - `error_message` - Server's error message, e.g. `Unknown order sent.`\n - `header` - Full response header.\n - `error_data`* - Additional detailed data which supplements the `error_message`.\n - **Only applicable on select endpoints, eg. `cancelReplace`*\n- `orderly_evm_connector.error.ServerError`\n - This is thrown when server returns `5XX`, it's an issue from server side.\nIn addition, there are 3 types of Parameter Error:\n- `orderly_evm_connector.error.ParameterRequiredError`\n - This error is thrown when a required parameter for the endpoint is not present in the request.\n- `orderly_evm_connector.error.ParameterValueError`\n - This error is thrown when a value passed in for an ENUM type parameter is invalid. For example the `order_type` parameter is an ENUM with a fixed set of values users could pass in. Passing a value out of the ENUM definition will result in this error.\n- `orderly_evm_connector.error.ParameterTypeError`\n - This error is thrown when a value passed in is not in consistency with the type definition of the parameter.\nWebsocket Client has 1 type of Error:\n- `WebsocketClientError`\n - This error is thrown when there is an exception thrown by the WebsocketClient class.\n\n## Websocket\n\n### Websocket Client\n\nOrderly has two Websocket endpoints, the Market Data Base Endpoint(public endpoint) and the Private User Data Stream Base Endpoint(private endpoint).\n`orderly-connector` supports connecting to both endpoints in both Mainnet and Testnet. See below for example:\n\n```python\nfrom orderly_evm_connector.lib.utils import get_account_info\nimport time, logging\nfrom orderly_evm_connector.websocket.websocket_api import WebsocketPublicAPIClient\n\n(\n orderly_key,\n orderly_secret,\n orderly_account_id,\n orderly_testnet,\n wallet_secret,\n wss_id,\n) = get_account_info('config.ini')\n\n\ndef on_close(_):\n logging.info(\"Do custom stuff when connection is closed\")\n\n\ndef message_handler(_, message):\n logging.info(message)\n\n\n# Public websocket does not need to pass orderly_key and orderly_secret arguments\n\nwss_client = WebsocketPublicAPIClient(\n orderly_testnet=orderly_testnet,\n orderly_account_id=orderly_account_id,\n wss_id=wss_id,\n on_message=message_handler,\n on_close=on_close,\n debug=True,\n)\n\nwss_client.get_24h_tickers()\ntime.sleep(1000)\nwss_client.stop()\n```\n\nFor private endpoint, user will need to pass in the `orderly_key` and `orderly_secret` to the `orderly.websocket.WebsocketPrivateAPIClient` class.\nPrivate endpoint also requires signature of the message sent using `orderly_key` and `orderly_secret`. This function is encapsulated by the `WebsocketPrivateAPIClient` class. See Orderly API Docs for more detai. \n```python\nfrom orderly_evm_connector.websocket.websocket_api import WebsocketPrivateAPIClient\n\nwss_client = WebsocketPrivateAPIClient(\n orderly_testnet=orderly_testnet,\n orderly_account_id=orderly_account_id,\n wss_id=wss_id,\n orderly_key=orderly_key,\n orderly_secret=orderly_secret,\n on_message=message_handler,\n on_close=on_close,\n debug=True,\n)\n# wss_client.get_liquidator_liquidations()\nwss_client.get_notifications()\ntime.sleep(1000)\nwss_client.stop()\n```\n\n\n#### wss_id\n`wss_id` is the request id of included in each of websocket request to orderly. This is defined by user and has a max length of 64 bytes.\n\n\n## Limitation\n\n## Contributing\n\nContributions are welcome.<br/>\nIf you've found a bug within this project, please open an issue to discuss what you would like to change.<br/>\nIf it's an issue with the API, please open a topic at [Orderly Developer Community]()\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This is a lightweight library that works as a connector to Orderly API and Websocket.",
"version": "0.2.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5820fc3bb578e595c00578ae347391c2af2f3c50e677155cf16d3b422fc900d4",
"md5": "478f11f8d7bc4f3a89311697f58e9ea6",
"sha256": "fe47b286d7e0b559544dcaa1cae4ea0628ec687cc47b06bb23a3ab7d2c671d10"
},
"downloads": -1,
"filename": "orderly_evm_connector-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "478f11f8d7bc4f3a89311697f58e9ea6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 46236,
"upload_time": "2024-11-08T17:36:28",
"upload_time_iso_8601": "2024-11-08T17:36:28.429588Z",
"url": "https://files.pythonhosted.org/packages/58/20/fc3bb578e595c00578ae347391c2af2f3c50e677155cf16d3b422fc900d4/orderly_evm_connector-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6cb71e6e81752da33a94b1e590d2eb4ef74912992d25fb8cbe58198e8b909f6a",
"md5": "b9411014d7ad1b53409dcb89a29f093e",
"sha256": "5a9f5213c576f1dfe9914ccc3bc0237ae5604cd084b47a2901ffca3ea38f7253"
},
"downloads": -1,
"filename": "orderly_evm_connector-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "b9411014d7ad1b53409dcb89a29f093e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 35436,
"upload_time": "2024-11-08T17:36:34",
"upload_time_iso_8601": "2024-11-08T17:36:34.117143Z",
"url": "https://files.pythonhosted.org/packages/6c/b7/1e6e81752da33a94b1e590d2eb4ef74912992d25fb8cbe58198e8b909f6a/orderly_evm_connector-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-08 17:36:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "orderly-evm-connector"
}
