-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit ffb5519
Showing
54 changed files
with
7,638 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Sphinx build info version 1 | ||
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. | ||
config: 452c69ae286c196f21ef2c329f09db0a | ||
tags: 645f666f9bcd5a90fca523b33c5a78b7 |
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,87 @@ | ||
# Getting started | ||
|
||
This library provides an interface for interacting with the [Synthetix](https://synthetix.io/) protocol. This guide is intended to show the basics of initializing the library and calling a few functions. | ||
|
||
If your use case requires a more in-depth understanding of the protocol, please refer to the [Synthetix documentation](https://docs.synthetix.io/). | ||
|
||
## Requirements | ||
|
||
This library requires Python 3.8 or higher. It makes heavy use of the [web3.py](https://github.com/ethereum/web3.py) library for interacting with smart contracts. | ||
|
||
It is recommended to use a virtual environment to install the library and its dependencies. Use [venv](https://docs.python.org/3/library/venv.html) to create and manage this virtual environment: | ||
|
||
```bash | ||
python3 -m venv env | ||
source env/bin/activate | ||
|
||
# optionally upgrade pip | ||
pip install --upgrade pip | ||
``` | ||
|
||
## Installation | ||
|
||
The library is available from the PyPI package repository and can be installed using `pip`: | ||
|
||
```bash | ||
pip install synthetix | ||
``` | ||
|
||
## Initializing the client | ||
|
||
To use the library, initialize the `Synthetix` object that can be used to interact with the protocol. At minimum, you must provide an RPC endpoint and specify the intended network id. | ||
|
||
```python | ||
from synthetix import Synthetix | ||
|
||
# Base Goerli | ||
snx = Synthetix( | ||
provider_url="https://base-goerli.infura.io/v3/<your-infura-project-id>", | ||
network=84531, | ||
) | ||
|
||
# Optimism Mainnet | ||
snx = Synthetix( | ||
provider_url="https://optimism-mainnet.infura.io/v3/<your-infura-project-id>", | ||
network=10, | ||
) | ||
|
||
# Optimism Goerli | ||
snx = Synthetix( | ||
provider_url="https://optimism-goerli.infura.io/v3/<your-infura-project-id>", | ||
network=420, | ||
) | ||
``` | ||
|
||
This will initialize an `snx` object which you can use to interact with the protocol. Any warnings or errors will be logged to the console. | ||
|
||
## Basic usage | ||
|
||
After initialization, you can use the `snx` object to interact with the different modules in the protocol. Here are some common functions you may want to use: | ||
|
||
```python | ||
snx.perps.get_markets() # fetch all perps market summaries | ||
snx.perps.get_accounts() # fetch all perps accounts for the specified address | ||
snx.perps.get_margin_info(1) # get the margin balances for account_id 1 | ||
``` | ||
|
||
Here is an example of calling the `get_markets` function with sample output: | ||
```python | ||
>>> markets_by_id, markets_by_name = snx.perps.get_markets() | ||
>>> markets_by_name | ||
{ | ||
'ETH': { | ||
'market_id': 100, | ||
'market_name': 'ETH', | ||
'skew': -3308.71, | ||
'size': 14786.42 | ||
'max_open_interest': 100000, | ||
'current_funding_rate': 0.00196 | ||
'current_funding_velocity': -0.02977 | ||
'index_price': 1560.37 | ||
}, | ||
'BTC': { | ||
... | ||
}, | ||
... | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,158 @@ | ||
# Trade Perps | ||
|
||
This guide will help you get started trading Synthetix Perps. If you complete the steps in this guide you will be able to: | ||
1. Initialize the Synthetix client | ||
1. Create an account | ||
1. Manage your account margin | ||
1. Make trades | ||
1. Monitor your positions | ||
|
||
## Setting Up | ||
|
||
First, ensure you have the latest version of `synthetix` installed in your environment. Execute the following command in your terminal: | ||
|
||
```bash | ||
pip install --upgrade synthetix | ||
``` | ||
|
||
If you need additional help installing the library, refer to the quickstart guide. | ||
|
||
### Initializing the Client | ||
|
||
Initialize the client using the following code: | ||
|
||
```python | ||
from synthetix import Synthetix | ||
|
||
snx = Synthetix( | ||
PROVIDER_RPC="https://base-goerli.g.alchemy.com/v2/<api key>", | ||
NETWORK=84531, | ||
ADDRESS="<your address>", | ||
PRIVATE_KEY="<your private key>" | ||
) | ||
``` | ||
|
||
To avoid storing these secrets directly in your scripts, you can use a `.env` file and the `load_dotenv` library. Install it using the following command: | ||
|
||
```bash | ||
pip install python-dotenv | ||
``` | ||
|
||
Next, create a `.env` file in your project directory and add the following lines: | ||
|
||
``` | ||
PROVIDER_RPC=https://base-goerli.g.alchemy.com/v2/<api key> | ||
NETWORK=84531 | ||
ADDRESS=<your address> | ||
PRIVATE_KEY=<your private key> | ||
``` | ||
|
||
Finally, initialize the client with the following code: | ||
|
||
```python | ||
from synthetix import Synthetix | ||
from dotenv import load_dotenv | ||
|
||
load_dotenv() | ||
|
||
snx = Synthetix( | ||
PROVIDER_RPC=os.getenv("PROVIDER_RPC"), | ||
NETWORK=os.getenv("NETWORK"), | ||
ADDRESS=os.getenv("ADDRESS"), | ||
PRIVATE_KEY=os.getenv("PRIVATE_KEY") | ||
) | ||
``` | ||
|
||
### Creating an Account | ||
|
||
To begin, you'll need to create an account. Each perps account is minted as an NFT to your address. The account will be used to track your margin balances and open positions. Here's how you can create an account: | ||
|
||
```python | ||
>>> account_tx = snx.perps.create_account(submit=True) | ||
``` | ||
|
||
The newly created account will be used as the default for all future transactions. | ||
|
||
## Managing Account Margin | ||
|
||
Before you can make trades, you'll need to deposit collateral into your account. Here's how you can check the current balances in your perps account, and in your wallet: | ||
|
||
```python | ||
>>> snx.perps.get_collateral_balances() | ||
{'sUSD': 0.0, 'BTC': 0.0, 'ETH': 0.0, 'LINK': 0.0} | ||
|
||
>>> snx.get_susd_balance() | ||
{'balance': 1000.0} | ||
``` | ||
|
||
In this example you can see the wallet has 1000 sUSD, but the perps account has no collateral balances. Let's deposit 100 sUSD into the account, but first we need to make sure to approve sUSD transfers to the perps contract: | ||
|
||
```python | ||
>>> perps_address = snx.perps.market_proxy.address | ||
>>> approve_tx = snx.spot.approve(perps_address, market_name='sUSD', submit=True) | ||
``` | ||
|
||
Then you can deposit the sUSD into the perps account: | ||
|
||
```python | ||
>>> deposit_tx = snx.perps.modify_collateral(100, market_name='sUSD', submit=True) | ||
``` | ||
|
||
Check your balance again to confirm the successful deposit: | ||
|
||
```python | ||
>>> snx.perps.get_collateral_balances() | ||
{'sUSD': 100.0, 'BTC': 0.0, 'ETH': 0.0, 'LINK': 0.0} | ||
``` | ||
|
||
## Submitting an Order | ||
|
||
All trades on Synthetix perps are executed in two steps: first, the user commits an order; then, following a delay, the order is executed. Orders are filled at the price at execution time. | ||
|
||
Commit an order: | ||
|
||
```python | ||
>>> snx.perps.commit_order(0.1, market_name='ETH', submit=True) | ||
``` | ||
|
||
After an order is submitted, you can check its status: | ||
```python | ||
>>> order = snx.perps.get_order() | ||
>>> order | ||
{ | ||
'market_id': 100, | ||
'account_id': 1, | ||
'settlement_time': 1697215535, | ||
'size_delta': 0.1, | ||
'settlement_strategy_id': 1, | ||
'acceptable_price': 1533.6071692221237, | ||
... | ||
} | ||
``` | ||
|
||
Note: | ||
* The `settlement_time` represents the unix timestamp when this order is eligible to be executed. | ||
* The `size_delta` is set to 0 after the order is executed. If it shows 0, check the position to confirm it was filled. | ||
* You don't need to specify the market name when checking the order status, because accounts are limited to 1 open order at a time. | ||
|
||
### Checking Your Position | ||
|
||
After an order is executed, you can check your position using `get_open_positions`. This function will fetch all positions with nonzero sizes. If you have no open positions, it will return an empty dictionary: | ||
|
||
```python | ||
>>> positions = snx.perps.get_open_positions() | ||
>>> positions | ||
{ | ||
'ETH': { | ||
'market_id': 100, | ||
'market_name': 'ETH', | ||
'pnl': 1.52, | ||
'accrued_funding': 0.002245, | ||
'position_size': 0.1 | ||
} | ||
} | ||
``` | ||
|
||
## Conclusion | ||
|
||
Congratulations! You have now mastered the basics of trading Synthetix perps. To see the full API reference for the perps module, check out the full [API Reference](https://synthetixio.github.io/python-sdk/modules/synthetix.html) section of the docs. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
Synthetix Documentation | ||
======================= | ||
|
||
The ``synthetix`` library provides an interface for interacting with the Synthetix_ protocol smart contracts. Learn more about the Synthetix protocol in the documentation_. | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
:caption: User Guides | ||
|
||
guides/quickstart | ||
guides/trade_perps | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
:caption: Reference | ||
|
||
modules/synthetix | ||
modules/utils | ||
|
||
Links | ||
----- | ||
|
||
- `Python SDK Github <https://github.com/Synthetixio/python-sdk>`_ | ||
- `Synthetix V3 Github <https://github.com/Synthetixio/synthetix-v3>`_ | ||
- `Synthetix website <https://synthetix.io/>`_ | ||
- `Synthetix documentation <https://docs.synthetix.io/>`_ | ||
|
||
.. _Synthetix: https://synthetix.io/ | ||
.. _documentation: https://docs.synthetix.io/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
Multicall | ||
=========================== | ||
|
||
.. automodule:: synthetix.utils.multicall | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
Synthetix | ||
=========================== | ||
|
||
.. autoclass:: synthetix.Synthetix | ||
:members: | ||
:private-members: | ||
|
||
.. autoclass:: synthetix.perps.Perps | ||
:members: | ||
:private-members: | ||
|
||
.. autoclass:: synthetix.pyth.Pyth | ||
:members: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
Utils | ||
=========================== | ||
|
||
.. automodule:: synthetix.utils | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
Oops, something went wrong.