README & configurable spot markets for sendBatchTx examples

Author: alexvelea

examples/README.md

@@ -19,6 +19,11 @@
   - same flow as `create_modify_cancel_order_http.py`
   - sends TXs over WS instead of HTTP
 
+- `create_market_order_eth_buy.py`
+  - creates a market buy order for 0.1 ETH @ market price
+- `create_market_order_eth_sell.py`
+  - creates a market sell order for 0.1 ETH @ market price
+
 - `create_grouped_ioc_with_attached_sl_tp.py`
   - creates an ask (sell) IoC order for 0.1 ETH
   - along w/ the order, it sets up a Stop Loss (SL) and a Take Profit (TP) order for the whole size of the order
@@ -31,7 +36,7 @@
   - the orders will grow / shrink as you accumulate more position
   - the SL/TP orders are canceled when the sign of your position changes
 
-### On SL/TP orders
+## On SL/TP orders
 SL/TP orders need to be configured beyond just setting the trigger price. When the trigger price is set, 
 the order will just be executed, like a normal order. This means that a market order, for example, might not have enough slippage! \
 Let's say that you have a 1 BTC long position, and the current price is $110'000. \
@@ -43,7 +48,7 @@ What about the order types? Just as normal orders, SL/TP orders trigger an order
 - market order
 - limit IOC / GTC
 
-### Modify leverage / Margin Mode (Cross, Isolated) / Add Collateral to isolated-only positions
+## Modify leverage / Margin Mode (Cross, Isolated) / Add Collateral to isolated-only positions
 - `margin_eth_20x_cross_http`
   - sets ETH market to 20x leverage and cross-margin mode, using HTTP
 - `margin_eth_50x_isolate_ws`
@@ -53,14 +58,51 @@ What about the order types? Just as normal orders, SL/TP orders trigger an order
 - `margin_eth_remove_collateral_ws.py`
   - removes $5 USDC from the ETH position (must be opened and in isolated mode)
 
-### Batch orders
+## Batch orders
 - `send_batch_tx_http.py`
   - sends multiple orders in a single HTTP request
 - `send_batch_tx_ws.py`
   - sends multiple orders in a single WS request`
 
 Batch TXs will be executed back to back, without the possibility of other TXs interfering.
 
+## Spot Trading
+To trade spot markets, you need to have spot USDC. USDC used in your perpetual account will be used as collateral for your cross-positions.  
+USDC deposited in the spot account can only be used to buy spot assets.  
+To transfer USDC between spot <> perp balance, or vice verse, check out
+- `spot_self_transfer_perp_spot.py`
+- `spot_self_transfer_spot_perp.py`
+
+Order placement / trades work in the same way as for perpetual markets.  
+The fee will be paid in the received asset for premium spot trades.   
+This means that if you sell ETH, you'll receive less USDC, and if you BUY 1 ETH, you'll receive slightly less than 1 ETH.  
+You can check out the following examples, which should work on spot ETH by changing the market index to 2048 instead of 0.
+- `create_modify_cancel_order_http.py`
+- `create_modify_cancel_order_ws.py`
+- `create_market_order_eth_buy.py`
+- `create_market_order_eth_sell.py`
+- `send_batch_tx_http.py`
+- `send_batch_tx_ws.py`
+
+Trading setup is very similar to perpetual markets.  
+The only difference is that you'll need to hold USDC / ETH before placing an order.  
+For example, on perp markets you can place an order to short (sell) ETH without having to worry that much.    
+The limitation there would be to have enough available collateral to cover the order.  
+On spot orders, you need to have enough assets in your spot account to cover all open orders.  
+If you want to place two orders, to buy 1000 USDC worth of ETH and 1000 USDC worth of ZK, you'll need to have at least 2000 available USDC.  
+
+You can get the order book details (including symbol and market index) as well as quote asset id (ETH) and base asset id (USDC)  
+by following the example below:
+- `spot_get_order_books.py`
+
+Note: you'll need the quote asset id and base asset id to check available balance.  
+Available balance is not locked in open orders.
+
+To keep track of your spot balance, you can use HTTP calls or a websocket subscription.  
+Examples on how to do this can be found here:
+- `spot_get_account_assets_http.py`
+- `spot_get_account_assets_ws.py`
+
 ## Setup steps for mainnet
 - deposit money on Lighter to create an account first
 - change the URL to `mainnet.zklighter.elliot.ai`

examples/send_batch_tx_http.py

@@ -7,9 +7,12 @@
 async def main():
     client, api_client, _ = default_example_setup()
 
+    # Note: change this to 2048 to trade spot ETH. Make sure you have at least 0.1 ETH to trade spot.
+    market_index = 0
+
     api_key_index, nonce = client.nonce_manager.next_nonce()
     ask_tx_type, ask_tx_info, ask_tx_hash, error = client.sign_create_order(
-        market_index=0,
+        market_index=market_index,
         client_order_index=1001,  # Unique identifier for this order
         base_amount=1000,  # 0.1 ETH
         price=5000_00,  # $5000
@@ -30,7 +33,7 @@ async def main():
     # in batch TXs, all TXs must come from the same API key.
     api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
     bid_tx_type, bid_tx_info, bid_tx_hash, error = client.sign_create_order(
-        market_index=0,
+        market_index=market_index,
         client_order_index=1002,  # Different unique identifier
         base_amount=1000,  # 0.1 ETH
         price=1500_00,  # $1500
@@ -63,7 +66,7 @@ async def main():
     # since this is a new batch, we can request a fresh API key
     api_key_index, nonce = client.nonce_manager.next_nonce()
     cancel_tx_type, cancel_tx_info, cancel_tx_hash, error = client.sign_cancel_order(
-        market_index=0,
+        market_index=market_index,
         order_index=1001,  # the index of the order we want cancelled
         nonce=nonce,
         api_key_index=api_key_index,
@@ -77,7 +80,7 @@ async def main():
     # in batch TXs, all TXs must come from the same API key.
     api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
     new_ask_tx_type, new_ask_tx_info, new_ask_tx_hash, error = client.sign_create_order(
-        market_index=0,
+        market_index=market_index,
         client_order_index=1003,  # Different unique identifier
         base_amount=2000,  # 0.2 ETH
         price=5500_00,  # $5500
@@ -110,7 +113,7 @@ async def main():
     # since this is a new batch, we can request a fresh API key
     api_key_index, nonce = client.nonce_manager.next_nonce()
     cancel_1_tx_type, cancel_1_tx_info, cancel_1_tx_hash, error = client.sign_cancel_order(
-        market_index=0,
+        market_index=market_index,
         order_index=1002,  # the index of the order we want cancelled
         nonce=nonce,
         api_key_index=api_key_index,
@@ -122,7 +125,7 @@ async def main():
 
     api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
     cancel_2_tx_type, cancel_2_tx_info, cancel_2_tx_hash, error = client.sign_cancel_order(
-        market_index=0,
+        market_index=market_index,
         order_index=1003,  # the index of the order we want cancelled
         nonce=nonce,
         api_key_index=api_key_index,

examples/send_batch_tx_ws.py

@@ -13,9 +13,12 @@ async def main():
     ws_client: websockets.ClientConnection = await ws_client_promise
     print("Received:", await ws_client.recv())
 
+    # Note: change this to 2048 to trade spot ETH. Make sure you have at least 0.1 ETH to trade spot.
+    market_index = 2048
+
     api_key_index, nonce = client.nonce_manager.next_nonce()
     ask_tx_type, ask_tx_info, ask_tx_hash, error = client.sign_create_order(
-        market_index=0,
+        market_index=market_index,
         client_order_index=1001,  # Unique identifier for this order
         base_amount=1000,  # 0.1 ETH
         price=5000_00,  # $5000
@@ -36,7 +39,7 @@ async def main():
     # in batch TXs, all TXs must come from the same API key.
     api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
     bid_tx_type, bid_tx_info, bid_tx_hash, error = client.sign_create_order(
-        market_index=0,
+        market_index=market_index,
         client_order_index=1002,  # Different unique identifier
         base_amount=1000,  # 0.1 ETH
         price=1500_00,  # $1500
@@ -65,7 +68,7 @@ async def main():
     # since this is a new batch, we can request a fresh API key
     api_key_index, nonce = client.nonce_manager.next_nonce()
     cancel_tx_type, cancel_tx_info, cancel_tx_hash, error = client.sign_cancel_order(
-        market_index=0,
+        market_index=market_index,
         order_index=1001,  # the index of the order we want cancelled
         nonce=nonce,
         api_key_index=api_key_index,
@@ -79,7 +82,7 @@ async def main():
     # in batch TXs, all TXs must come from the same API key.
     api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
     new_ask_tx_type, new_ask_tx_info, new_ask_tx_hash, error = client.sign_create_order(
-        market_index=0,
+        market_index=market_index,
         client_order_index=1003,  # Different unique identifier
         base_amount=2000,  # 0.2 ETH
         price=5500_00,  # $5500
@@ -108,7 +111,7 @@ async def main():
     # since this is a new batch, we can request a fresh API key
     api_key_index, nonce = client.nonce_manager.next_nonce()
     cancel_1_tx_type, cancel_1_tx_info, cancel_1_tx_hash, error = client.sign_cancel_order(
-        market_index=0,
+        market_index=market_index,
         order_index=1002,  # the index of the order we want cancelled
         nonce=nonce,
         api_key_index=api_key_index,
@@ -120,7 +123,7 @@ async def main():
 
     api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
     cancel_2_tx_type, cancel_2_tx_info, cancel_2_tx_hash, error = client.sign_cancel_order(
-        market_index=0,
+        market_index=market_index,
         order_index=1003,  # the index of the order we want cancelled
         nonce=nonce,
         api_key_index=api_key_index,