diff --git a/README.md b/README.md
index 8f58924..8ff7c29 100644
--- a/README.md
+++ b/README.md
@@ -34,26 +34,19 @@ The `nibiru` package allows you to index, query, and send transactions on Nibiru
The package is intended to be used by coders, developers, technically-skilled traders and data-scientists for building trading algorithms.
-#### README Contents
+## Try running nibiru sdk online
-- [Python SDK Tutorial](#python-sdk-tutorial)
-- [Installation from `PyPI`](#installation-from-pypi)
-- [Usage](#usage)
- - [Ex: Creating a wallet and SDK client](#ex-creating-a-wallet-and-sdk-client)
- - [Ex: Using the faucet](#ex-using-the-faucet)
- - [Ex: Querying chain state](#ex-querying-chain-state)
- - [Ex: Submitting transactions](#ex-submitting-transactions)
-- [Documentation Website](#documentation-website)
-- [Contributing](#contributing)
+Open the google collab link below to try running Niburu code online:
-## Python SDK Tutorial
-
-
+
+Or go to the [examples folder](examples) to see the codes and run Jupyter notebooks locally.
+
+## Installation
```bash
pip install nibiru # requires Python 3.8+
```
@@ -126,13 +119,12 @@ print(client.query.get_bank_balances(client.address))
```python
output = client.tx.execute_msgs(
- Msg.perp.open_position(
- pair=pair,
- is_long=True,
- quote_asset_amount=10,
- leverage=1,
- base_asset_amount_limit=0,
- )
+ Msg.perp.open_position(
+ pair=pair,
+ is_long=True,
+ margin=10,
+ leverage=2,
+ )
)
print(output)
```
diff --git a/examples/2- My first transaction.ipynb b/examples/2- My first transaction.ipynb
index ebe7ddc..39d4b2f 100644
--- a/examples/2- My first transaction.ipynb
+++ b/examples/2- My first transaction.ipynb
@@ -125,9 +125,8 @@
" Msg.perp.open_position(\n",
" pair=pair,\n",
" is_long=True,\n",
- " quote_asset_amount=10,\n",
+ " margin=10,\n",
" leverage=1,\n",
- " base_asset_amount_limit=0,\n",
" )\n",
")\n",
"print(output)"
diff --git a/examples/colab_notebook.ipynb b/examples/colab_notebook.ipynb
index 423e91d..3092179 100644
--- a/examples/colab_notebook.ipynb
+++ b/examples/colab_notebook.ipynb
@@ -4,48 +4,55 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "# Introduction to py-sdk\n",
- "\n",
- "The python sdk allows you to create queries and transaction to a Nibiru chain.\n",
- "\n",
- "It allows to interact with all of the modules and can be leveraged to automate trading strategies or monitor them.\n",
+ "# Introduction to Nibiru SDK\n",
"\n",
+ "The python sdk allows you to create queries and send transactions to a Nibiru chain.\n",
+ "It allows to interact with all the modules and can be leveraged to automate trading strategies or monitor them.\n",
"This notebook will guide you on opening and closing positions."
]
},
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {},
- "outputs": [],
- "source": [
- "import json\n",
- "\n",
- "from nibiru import Network, ChainClient, Msg, Coin"
- ]
- },
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "Let's set up the chain to which we will be connecting to. If you have a preferred endpoint you can update these values to connect to it. Make sure that the node have the port opens for 1317, 26657 and 9090."
+ "### 1. Prepare wallet mnemonic key (or private key)\n",
+ "If you don't have a mnemonic key, generate it using some online service or run the code below:"
]
},
{
"cell_type": "code",
"execution_count": null,
- "metadata": {},
"outputs": [],
"source": [
- "pair = \"ubtc:unusd\""
- ]
+ "from nibiru import PrivateKey\n",
+ "mnemonic, private_key = PrivateKey.generate()\n",
+ "print(mnemonic)"
+ ],
+ "metadata": {
+ "collapsed": false
+ }
},
{
"cell_type": "markdown",
- "metadata": {},
"source": [
- "Next, let's make sure that the transaction we send are synchronous. This way if no error is raised when running the execute_msgs method, we are sure that the transaction was successful."
- ]
+ "### 2. Get test tokens from the nibiru faucet\n",
+ "Faucet URL: [https://app.nibiru.fi/faucet](https://app.nibiru.fi/faucet)"
+ ],
+ "metadata": {
+ "collapsed": false
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### 3. Create nibiru chain client and authenticate using mnemonic\n",
+ "The client below uses ITN-2 Nibiru testnet chain.\n",
+ "Use your mnemonic key or private key to authenticate.\n",
+ "If you took money from the faucet, your balances should not be empty."
+ ],
+ "metadata": {
+ "collapsed": false
+ }
},
{
"cell_type": "code",
@@ -53,20 +60,32 @@
"metadata": {},
"outputs": [],
"source": [
- "mnemonic = \"exclude rural knife asset egg seminar carry control thought stock topic lens embark about huge obvious reason language ripple clean cousin library punch renew\"\n",
+ "import json\n",
+ "from nibiru import Network, ChainClient, Msg, Coin\n",
+ "\n",
+ "mnemonic = \"put your mnemonic here\"\n",
"client = ChainClient(network=Network.testnet(2))\n",
- "client.authenticate(mnemonic=mnemonic)\n",
+ "client.authenticate(mnemonic=mnemonic) # alternatively use private_key_hex = your_key_hex\n",
"\n",
"# Check balance\n",
- "print(client.query.get_bank_balances(client.address))"
+ "print(json.dumps(client.query.get_bank_balances(client.address)[\"balances\"], indent=2))"
]
},
{
"cell_type": "markdown",
- "metadata": {},
"source": [
- "Now with those fresh token, we can open a long position"
- ]
+ "### 4. Create a tx to open perp trading position\n",
+ "Position is: LONG (=BUY),\n",
+ "\n",
+ "pair = ubtc:unusd: prefix `u` means `μ` or micro. So `unusd = micro unusd = 1/1000_000 nusd`, same for ubtc.\n",
+ "\n",
+ "margin = 10: (value in quote amount which is unusd in our case)\n",
+ "\n",
+ "leverage = 2: your position notional will be 2 * 10"
+ ],
+ "metadata": {
+ "collapsed": false
+ }
},
{
"cell_type": "code",
@@ -74,13 +93,14 @@
"metadata": {},
"outputs": [],
"source": [
+ "pair = \"ubtc:unusd\"\n",
+ "\n",
"output = client.tx.execute_msgs(\n",
" Msg.perp.open_position(\n",
" pair=pair,\n",
" is_long=True,\n",
- " quote_asset_amount=10,\n",
- " leverage=1,\n",
- " base_asset_amount_limit=0,\n",
+ " margin=10,\n",
+ " leverage=2,\n",
" )\n",
")\n",
"print(output)"
@@ -90,7 +110,9 @@
"cell_type": "markdown",
"source": [
"If your TX has succeeded, you should get output something like:\n",
+ "```\n",
"ExecuteTxResp(code=0, tx_hash='946A4252423A0AC183C1BAA2B76CCB25512DC9A18861D8782EFE7F14512CBDF6', log='[]')\n",
+ "```\n",
"Query your TX hash to get TX details:"
],
"metadata": {
@@ -102,7 +124,7 @@
"execution_count": null,
"outputs": [],
"source": [
- "output = client.query.tx_by_hash(\"946A4252423A0AC183C1BAA2B76CCB25512DC9A18861D8782EFE7F14512CBDF6\")\n",
+ "output = client.query.tx_by_hash(\"707F725DA2A04FD865FA6FEAF431DF89459F6A5C076B5AF93C627979C9B6CDF1\")\n",
"print(output)"
],
"metadata": {
@@ -197,16 +219,10 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "## Multi-transactions"
- ]
- },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "We can build multiple messages into a single transactions to be sure that they are executed consecutively.\n",
+ "## Multi-transactions\n",
+ "We can build multiple messages into a single transaction to be sure that they are executed consecutively.\n",
"\n",
- "It can be useful for example to send tokens after removing margins from a position"
+ "It can be useful for example to send tokens after removing margins from a position."
]
},
{
@@ -230,9 +246,8 @@
" Msg.perp.open_position(\n",
" pair=pair,\n",
" is_long=True,\n",
- " quote_asset_amount=10,\n",
+ " margin=10,\n",
" leverage=1,\n",
- " base_asset_amount_limit=0,\n",
" ),\n",
" Msg.perp.add_margin(\n",
" pair=pair,\n",
@@ -245,6 +260,27 @@
")\n",
"print(output)"
]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "outputs": [],
+ "source": [
+ "position = client.query.perp.all_positions(client.address)\n",
+ "print(json.dumps(position, indent=4))"
+ ],
+ "metadata": {
+ "collapsed": false
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "That's it! Good luck and happy Nibiru coding!"
+ ],
+ "metadata": {
+ "collapsed": false
+ }
}
],
"metadata": {
diff --git a/nibiru/msg/perp.py b/nibiru/msg/perp.py
index ad24c40..034d706 100644
--- a/nibiru/msg/perp.py
+++ b/nibiru/msg/perp.py
@@ -32,9 +32,9 @@ class MsgsPerp:
def open_position(
pair: str,
is_long: bool,
- quote_asset_amount: float,
+ margin: float,
leverage: float,
- base_asset_amount_limit: float,
+ base_asset_amount_limit: float = 0,
) -> 'MsgMarketOrder':
"""
Open a posiiton using the specified parameters.
@@ -42,16 +42,16 @@ def open_position(
Attributes:
pair (str): The token pair
is_long (bool): Determines whether to open with long or short exposure.
- quote_asset_amount (float): The quote amount you want to use to buy base
+ margin (float): The margin of the position
leverage (float): The leverage you want to use, typically between 1 and 15, depending on the maintenance
margin ratio of the pool.
- base_asset_amount_limit (float): The minimum amount of base you are willing to receive for this amount of
- quote.
+ base_asset_amount_limit (float): The minimum amount of base you are willing
+ to receive for this amount of quote.
"""
return MsgMarketOrder(
pair=pair,
dir=Direction.LONG if is_long else Direction.SHORT,
- quote_asset_amount=quote_asset_amount,
+ margin=margin,
leverage=leverage,
base_asset_amount_limit=base_asset_amount_limit,
)
@@ -177,7 +177,7 @@ class MsgMarketOrder(PythonMsg):
Attributes:
pair (str): The token pair
side (Side): The side, either Side.BUY or Side.SELL
- quote_asset_amount (float): The quote amount you want to use to buy base
+ margin (float): The quote amount you want to use to buy base
leverage (float): The leverage you want to use, typically between 1 and 15, depending on the maintenance
margin ratio of the pool.
base_asset_amount_limit (float): The minimum amount of base you are willing to receive for this amount of
@@ -186,7 +186,7 @@ class MsgMarketOrder(PythonMsg):
pair: str
dir: Direction
- quote_asset_amount: float
+ margin: float
leverage: float
base_asset_amount_limit: float
@@ -203,7 +203,7 @@ def to_pb(self, sender: str) -> pb.MsgMarketOrder:
if self.dir == Direction.LONG
else state_pb.Direction.SHORT
)
- quote_asset_amount_pb = to_sdk_int(self.quote_asset_amount)
+ quote_asset_amount_pb = to_sdk_int(self.margin)
base_asset_amount_limit_pb = to_sdk_int(self.base_asset_amount_limit)
leverage_pb = to_sdk_dec(self.leverage)
diff --git a/tests/perp_test.py b/tests/perp_test.py
index e13b6d2..9823fa8 100644
--- a/tests/perp_test.py
+++ b/tests/perp_test.py
@@ -27,9 +27,8 @@ def test_open_position(client_validator):
Msg.perp.open_position(
pair=PAIR,
is_long=False,
- quote_asset_amount=10,
+ margin=10,
leverage=10,
- base_asset_amount_limit=0,
)
)
tests.broadcast_tx_must_succeed(res=tx_output)
diff --git a/tests/websocket_test.py b/tests/websocket_test.py
index 855b971..62b0edb 100644
--- a/tests/websocket_test.py
+++ b/tests/websocket_test.py
@@ -40,9 +40,8 @@ def test_websocket_listen(client_validator, network: Network):
sender=client_validator.address,
pair=pair,
is_long=True,
- quote_asset_amount=10,
+ margin=10,
leverage=10,
- base_asset_amount_limit=0,
),
Msg.bank.send(
from_address=client_validator.address,