examples/3_perp.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "# Nibiru PERP (Perpetuals) Queries and Transactions\n",
    "Perpetuals is an instrument for margin trading.\n",
    "See documentation here: https://nibiru.fi/docs/ecosystem/nibi-perps/"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### 1. Install Nibiru package"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "!pip install nibiru"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### 2. Create chain client and run queries\n",
    "Using testnet-3 (aka itn-3) endpoint run queiries"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "import json\n",
    "from nibiru import Network, ChainClient, Msg, Coin, TxConfig\n",
    "from nibiru.exceptions import QueryError\n",
    "\n",
    "client = ChainClient(network=Network.testnet(3))"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# Shortcut to print responses\n",
    "def print_json(obj):\n",
    "    print(json.dumps(obj, indent=2))\n",
    "\n",
    "# Pretty print trader positions\n",
    "def print_trader_positions(trader_address):\n",
    "    print(f\"Trader {trader_address} positions:\")\n",
    "    print_json(\n",
    "        client.query.perp.all_positions(trader_address)\n",
    "    )"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# Query perp markets\n",
    "markets = client.query.perp.markets()\n",
    "print_json(markets)"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# Query perp positions of a trader\n",
    "trader_address = \"nibi1jle8khj3aennq24zx6g93aam9rt0fqhgyp4h52\"\n",
    "print_trader_positions(trader_address)"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# Query perp position of a trader on a specific market\n",
    "pair = \"ubtc:unusd\"\n",
    "try:\n",
    "    position = client.query.perp.position(pair, trader_address)\n",
    "    print_json(position)\n",
    "except QueryError:\n",
    "    print(\"Position not found\")"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### 3. Authenticate to run transactions\n",
    "Assuming you have your wallet mnemonic key (or private key) and some test tokens from the faucet.\n",
    "See: https://app.nibiru.fi/faucet"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "mnemonic = \"put your mnemonic here...\"\n",
    "\n",
    "# Let's set high gas multiplier to avoid out of gas errors. Could be customized per tx.\n",
    "tx_config = TxConfig(gas_multiplier=5)\n",
    "client = ChainClient(Network.testnet(3), tx_config=tx_config)\n",
    "client.authenticate(mnemonic=mnemonic)\n",
    "\n",
    "# Balances check\n",
    "balances = client.query.get_bank_balances(client.address)\n",
    "print_json(balances[\"balances\"])"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### 4. Run PERP transactions\n",
    "Open perp position with 5x leverage:"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "pair = \"ubtc:unusd\" # u-prefix means micro (1 unusd = 1/1000_000 NUSD)\n",
    "\n",
    "output = client.tx.execute_msgs(\n",
    "    Msg.perp.open_position(\n",
    "        pair=pair,\n",
    "        is_long=True,\n",
    "        margin=10,\n",
    "        leverage=5,\n",
    "    ),\n",
    "    wait_for_tx_resp=True,  # wait for block and get tx response\n",
    ")\n",
    "# Expected tx response code 0\n",
    "print(f\"tx response Code: {output['code']}\")\n",
    "if output[\"code\"] == 0:\n",
    "    print_trader_positions(client.address)"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Add some margin if position becomes unhealthy (low margin ratio):"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "output = client.tx.execute_msgs(\n",
    "    Msg.perp.add_margin(pair=pair, margin=Coin(1, \"unusd\")),\n",
    "    wait_for_tx_resp=True,\n",
    ")\n",
    "# Expected tx response code 0\n",
    "print(f\"tx response code: {output['code']}\")\n",
    "if output[\"code\"] == 0:\n",
    "    print_trader_positions(client.address)"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Remove margin if needed:"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "output = client.tx.execute_msgs(\n",
    "    Msg.perp.remove_margin(pair=pair, margin=Coin(1, \"unusd\")),\n",
    "    wait_for_tx_resp=True,\n",
    ")\n",
    "# Expected tx response code 0\n",
    "print(f\"tx response code: {output['code']}\")\n",
    "if output[\"code\"] == 0:\n",
    "    print_trader_positions(client.address)"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Close position:"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# Close position\n",
    "output = client.tx.execute_msgs(\n",
    "    Msg.perp.close_position(pair=pair),\n",
    "    wait_for_tx_resp=True,\n",
    ")\n",
    "# Expected tx response code 0\n",
    "print(f\"tx response code: {output['code']}\")\n",
    "if output[\"code\"] == 0:\n",
    "    print_trader_positions(client.address)"
   ],
   "metadata": {
    "collapsed": false
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}