From 21ccf45488be9c7b380ad980e05dffabb85643d8 Mon Sep 17 00:00:00 2001 From: Troy Date: Fri, 13 Oct 2023 14:26:40 -0600 Subject: [PATCH 1/2] Add perps trading guide --- docs/source/guides/trade_perps.md | 158 ++++++++++++++++++++++++++++++ docs/source/index.rst | 3 +- src/synthetix/perps/perps.py | 2 + 3 files changed, 162 insertions(+), 1 deletion(-) create mode 100644 docs/source/guides/trade_perps.md diff --git a/docs/source/guides/trade_perps.md b/docs/source/guides/trade_perps.md new file mode 100644 index 0000000..5605361 --- /dev/null +++ b/docs/source/guides/trade_perps.md @@ -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/", + NETWORK=84531, + ADDRESS="", + 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/ +NETWORK=84531 +ADDRESS= +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 section of the docs. diff --git a/docs/source/index.rst b/docs/source/index.rst index 3f118b9..eaaf81d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,10 +4,11 @@ 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: 2 + :maxdepth: 1 :caption: User Guides guides/quickstart + guides/trade_perps .. toctree:: :maxdepth: 1 diff --git a/src/synthetix/perps/perps.py b/src/synthetix/perps/perps.py index 30e759c..1d6ffe2 100644 --- a/src/synthetix/perps/perps.py +++ b/src/synthetix/perps/perps.py @@ -346,6 +346,8 @@ def get_account_ids(self, address: str = None): self.snx, self.account_proxy, 'tokenOfOwnerByIndex', inputs) self.account_ids = account_ids + if len(account_ids) > 0: + self.default_account_id = account_ids[0] return account_ids def get_margin_info(self, account_id: int = None): From 2d931ae2685a5e1be567b39de17d23e2f7baaf4b Mon Sep 17 00:00:00 2001 From: Troy Date: Fri, 13 Oct 2023 14:31:34 -0600 Subject: [PATCH 2/2] update link --- docs/source/guides/trade_perps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/guides/trade_perps.md b/docs/source/guides/trade_perps.md index 5605361..25f9a28 100644 --- a/docs/source/guides/trade_perps.md +++ b/docs/source/guides/trade_perps.md @@ -155,4 +155,4 @@ After an order is executed, you can check your position using `get_open_position ## 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 section of the docs. +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.