Update futures-v3 general-info documentation

Author: ross-32

docs/futures-v3/general-info.en.md

@@ -154,315 +154,114 @@ print(nonce)
 Instant now = Instant.now();
 long microsecond = now.getEpochSecond() * 1000000 + now.getNano() / 1000;
 ```
-#### Example: The following parameters are business request parameters.
 
-```python
-my_dict = {'symbol': 'SANDUSDT', 'positionSide': 'BOTH', 'type': 'LIMIT', 'side': 'BUY',
-	         'timeInForce': 'GTC', 'quantity': "190", 'price': 0.28694}
-```
-
-#### Example: All parameters are sent via form body (using Python as an example).
-
-> **Step 1: Convert all business parameters to strings, then sort them in ASCII order to generate a string.**
-
-```python
-    #Define all element values as strings.
-    def _trim_dict(my_dict) :
-      for key in my_dict:
-        value = my_dict[key]
-        if isinstance(value, list):
-            new_value = []
-            for item in value:
-                if isinstance(item, dict):
-                    new_value.append(json.dumps(_trim_dict(item)))
-                else:
-                    new_value.append(str(item))
-            my_dict[key] = json.dumps(new_value)
-            continue
-        if isinstance(value, dict):
-            my_dict[key] = json.dumps(_trim_dict(value))
-            continue
-        my_dict[key] = str(value)
-
-    return my_dict
-
-    #Remove elements with null (empty) values.
-    my_dict = {key: value for key, value in my_dict.items() if  value is not None}
-    my_dict['recvWindow'] = 50000
-    my_dict['timestamp'] = int(round(time.time()*1000))
-    # my_dict['timestamp'] = 1749545309665
-    #Convert elements to strings.
-    _trim_dict(my_dict)
-    #Generate a string sorted by ASCII values and remove special characters.
-    json_str = json.dumps(my_dict, sort_keys=True).replace(' ', '').replace('\'','\"')
-    print(json_str)
-    #{"positionSide":"BOTH","price":"0.28694","quantity":"190","recvWindow":"50000","side":"BUY","symbol":"SANDUSDT","timeInForce":"GTC","timestamp":"1749545309665","type":"LIMIT"}
-```
+#### Example: Post an order (using Python as an example).
 
-> **Step 2: Take the string generated in Step 1 and encode it together with the account information and nonce using ABI encoding to generate a hash string.**
 
 ```python
-   from eth_abi import encode
-   from web3 import Web3
-   #Use Web3 ABI to encode the generated string along with user, signer, and nonce.
-   encoded = encode(['string', 'address', 'address', 'uint256'], [json_str, user, signer, nonce])
-   print(encoded.hex())
-   #000000000000000000000000000000000000000000000000000000000000008000000000000000000000000063dd5acc6b1aa0f563956c0e534dd30b6dcf7c4e00000000000000000000000021cf8ae13bb72632562c6fff438652ba1a151bb00000000000000000000000000000000000000000000000000006361457bcec8300000000000000000000000000000000000000000000000000000000000000af7b22706f736974696f6e53696465223a22424f5448222c227072696365223a22302e3238363934222c227175616e74697479223a22313930222c227265637657696e646f77223a223530303030222c2273696465223a22425559222c2273796d626f6c223a2253414e4455534454222c2274696d65496e466f726365223a22475443222c2274696d657374616d70223a2231373439353435333039363635222c2274797065223a224c494d4954227d0000000000000000000000000000000000
-   #keccak hex
-   keccak_hex =Web3.keccak(encoded).hex()
-   print(keccak_hex)
-   #9e0273fc91323f5cdbcb00c358be3dee2854afb2d3e4c68497364a2f27a377fc
-```
-
-> **Step 3: Sign the hash generated in Step 2 using the privateKey.**
-
-```python
-    from eth_account import Account
-    from eth_abi import encode
-    from web3 import Web3, EthereumTesterProvider
-    from eth_account.messages import encode_defunct
-
-    signable_msg = encode_defunct(hexstr=keccak_hex)
-    signed_message = Account.sign_message(signable_message=signable_msg, private_key=priKey)
-    signature =  '0x'+signed_message.signature.hex()
-    print(signature)
-    #0x0337dd720a21543b80ff861cd3c26646b75b3a6a4b5d45805d4c1d6ad6fc33e65f0722778dd97525466560c69fbddbe6874eb4ed6f5fa7e576e486d9b5da67f31b
-```
-
-> **Step 4: Combine all parameters along with the signature generated in Step 3 into the request body.**
-
-```python
-    my_dict['nonce'] = nonce
-    my_dict['user'] = user
-    my_dict['signer'] = signer
-    my_dict['signature'] = '0x'+signed_message.signature.hex()
-    url ='https://fapi.asterdex.com/fapi/v3/order'
-    headers = {
-            'Content-Type': 'application/x-www-form-urlencoded',
-            'User-Agent': 'PythonApp/1.0'
-    }
-    res = requests.post(url,data=my_dict,headers=headers)
-    print(url)
-    #curl  -X POST 'https://fapi.asterdex.com/fapi/v3/order' -d 'symbol=SANDUSDT&positionSide=BOTH&type=LIMIT&side=BUY&timeInForce=GTC&quantity=190&price=0.28694&recvWindow=50000&timestamp=1749545309665&nonce=1748310859508867&user=0x63DD5aCC6b1aa0f563956C0e534DD30B6dcF7C4e&signer=0x21cF8Ae13Bb72632562c6Fff438652Ba1a151bb0&signature=0x0337dd720a21543b80ff861cd3c26646b75b3a6a4b5d45805d4c1d6ad6fc33e65f0722778dd97525466560c69fbddbe6874eb4ed6f5fa7e576e486d9b5da67f31b'
-```
-
-## **Example of GET /fapi/v3/order**
+import time
+import requests
+from eth_account.messages import  encode_structured_data
+from eth_account import Account
 
-#### Example: All parameters are sent through the query string (Python 3.9.6).
+typed_data = {
+  "types": {
+    "EIP712Domain": [
+      {"name": "name", "type": "string"},
+      {"name": "version", "type": "string"},
+      {"name": "chainId", "type": "uint256"},
+      {"name": "verifyingContract", "type": "address"}
+    ],
+    "Message": [
+      { "name": "msg", "type": "string" }
+    ]
+  },
+  "primaryType": "Message",
+  "domain": {
+    "name": "AsterSignTransaction",
+    "version": "1",
+    "chainId": 1666,
+    "verifyingContract": "0x0000000000000000000000000000000000000000"
+  },
+  "message": {
+    "msg": "$msg"
+  }
+}
 
-#### Example: The following parameters are API registration information. user, signer, and privateKey are for demonstration purposes only (where privateKey is the private key of the agent).
+headers = {
+    'Content-Type': 'application/x-www-form-urlencoded',
+    'User-Agent': 'PythonApp/1.0'
+}
+order_url = 'https://fapi.asterdex-testnet.com/fapi/v3/order'
 
-| Key        | Value                                                              |
-| ---------- | ------------------------------------------------------------------ |
-| user       | 0x63DD5aCC6b1aa0f563956C0e534DD30B6dcF7C4e                         |
-| signer     | 0x21cF8Ae13Bb72632562c6Fff438652Ba1a151bb0                         |
-| privateKey | 0x4fd0a42218f3eae43a6ce26d22544e986139a01e5b34a62db53757ffca81bae1 |
+# config your user and agent info here
+user = '*'
+signer = '*'
+private_key = "*"
 
-#### Example: The nonce parameter should be the current system timestamp in microseconds. If it exceeds the current time or lags behind the system time by more than 5 seconds, it will be considered an invalid request.
+def get_url(my_dict) -> str:
+       return '&'.join(f'{key}={str(value)}'for key, value in my_dict.items())
 
-```python
-#python
-nonce = math.trunc(time.time()*1000000)
-print(nonce)
-#1748310859508867
-```
+_last_ms = 0
+_i = 0
 
-```java
-//java
-Instant now = Instant.now();
-long microsecond = now.getEpochSecond() * 1000000 + now.getNano() / 1000;
-```
+def get_nonce():
+    global _last_ms, _i
+    now_ms = int(time.time())
 
-#### Example: The following parameters are business request parameters.
+    if now_ms == _last_ms:
+        _i += 1
+    else:
+        _last_ms = now_ms
+        _i = 0
 
-```python
-my_dict = {'symbol':'SANDUSDT','side':"SELL","type":'LIMIT','orderId':2194215}
-```
+    return now_ms * 1_000_000 + _i
 
-> **Step 1: Convert all business parameters to strings and generate a sorted string based on ASCII order.**
+def send_by_url() :
+    param = 'symbol=ASTERUSDT&side=BUY&type=LIMIT&quantity=10&price=0.6&timeInForce=GTC'
 
-```python
-    #Define all element values as strings.
-    def _trim_dict(my_dict) :
-    # 假设待删除的字典为d
-    for key in my_dict:
-        value = my_dict[key]
-        if isinstance(value, list):
-            new_value = []
-            for item in value:
-                if isinstance(item, dict):
-                    new_value.append(json.dumps(_trim_dict(item)))
-                else:
-                    new_value.append(str(item))
-            my_dict[key] = json.dumps(new_value)
-            continue
-        if isinstance(value, dict):
-            my_dict[key] = json.dumps(_trim_dict(value))
-            continue
-        my_dict[key] = str(value)
-
-    return my_dict
-
-
-    #Remove elements with empty values.
-    my_dict = {key: value for key, value in my_dict.items() if  value is not None}
-    my_dict['recvWindow'] = 50000
-    my_dict['timestamp'] = int(round(time.time()*1000))
-    # my_dict['timestamp'] = 1749545309665
-	#Convert all elements to strings.
-    _trim_dict(my_dict)
-    #Generate a string sorted by ASCII values and remove special characters.
-    json_str = json.dumps(my_dict, sort_keys=True).replace(' ', '').replace('\'','\"')
-    print(json_str)
-    #{"orderId":"2194215","recvWindow":"50000","side":"BUY","symbol":"SANDUSDT","timestamp":"1749545309665","type":"LIMIT"}
-```
+    param += '&nonce=' + str(get_nonce())
+    param += '&user=' + user
+    param += '&signer=' + signer
 
-> **Step 2: Use ABI encoding to combine the string from step 1 with the account information (user, signer) and nonce, then generate a hash string from the encoded result.**
+    typed_data['message']['msg'] = param
+    message = encode_structured_data(typed_data)
+    signed = Account.sign_message(message, private_key=private_key)
+    print(signed.signature.hex())
 
-```python
-   from eth_abi import encode
-   from web3 import Web3
-
-   #Use WEB3 ABI to encode the generated string together with user, signer, and nonce.
-   encoded = encode(['string', 'address', 'address', 'uint256'], [json_str, user, signer, nonce])
-   print(encoded.hex())
-   #000000000000000000000000000000000000000000000000000000000000008000000000000000000000000063dd5acc6b1aa0f563956c0e534dd30b6dcf7c4e00000000000000000000000021cf8ae13bb72632562c6fff438652ba1a151bb00000000000000000000000000000000000000000000000000006361457bcec8300000000000000000000000000000000000000000000000000000000000000767b226f726465724964223a2232313934323135222c227265637657696e646f77223a223530303030222c2273696465223a22425559222c2273796d626f6c223a2253414e4455534454222c2274696d657374616d70223a2231373439353435333039363635222c2274797065223a224c494d4954227d00000000000000000000
-   keccak_hex =Web3.keccak(encoded).hex()
-   print(keccak_hex)
-   #6ad9569ea1355bf62de1b09b33b267a9404239af6d9227fa59e3633edae19e2a
-```
+    url = order_url + '?' + param + '&signature=' + signed.signature.hex()
 
-> **Step 3: Sign the hash generated in Step 2 using the privateKey.**
+    print(url)
+    res = requests.post(url, headers=headers)
 
-```python
-from eth_account import Account
-    from eth_abi import encode
-    from web3 import Web3, EthereumTesterProvider
-    from eth_account.messages import encode_defunct
-
-    signable_msg = encode_defunct(hexstr=keccak_hex)
-    signed_message = Account.sign_message(signable_message=signable_msg, private_key=priKey)
-    signature =  '0x'+signed_message.signature.hex()
-    print(signature)
-    #0x4f5e36e91f0d4cf5b29b6559ebc2c808d3c808ebb13b2bcaaa478b98fb4195642c7473f0d1aa101359aaf278126af1a53bcb482fb05003bfb6bdc03de03c63151b
-```
+    print(res.text)
 
-> **Step 4: Combine all parameters and the signature from Step 3 into the request body.**
+def send_by_body() :
+       my_dict = {"symbol": "ASTERUSDT", "type": "LIMIT", "side": "BUY",
+                  "timeInForce": "GTC", "quantity": "10", "price": "0.6"}
 
-```python
-    my_dict['nonce'] = nonce
-    my_dict['user'] = user
-    my_dict['signer'] = signer
-    my_dict['signature'] = '0x'+signed_message.signature.hex()
+       my_dict['nonce'] = str(get_nonce())
+       my_dict['user'] = user
+       my_dict['signer'] = signer
 
-    url ='https://fapi.asterdex.com/fapi/v3/order'
+       content = get_url(my_dict)
+       typed_data['message']['msg'] = content
+       message = encode_structured_data(typed_data)
 
-    res = requests.get(url, params=my_dict)
-    print(url)
-    #curl  -X GET 'https://fapi.asterdex.com/fapi/v3/order?symbol=SANDUSDT&side=BUY&type=LIMIT&orderId=2194215&recvWindow=50000&timestamp=1749545309665&nonce=1748310859508867&user=0x63DD5aCC6b1aa0f563956C0e534DD30B6dcF7C4e&signer=0x21cF8Ae13Bb72632562c6Fff438652Ba1a151bb0&signature=0x4f5e36e91f0d4cf5b29b6559ebc2c808d3c808ebb13b2bcaaa478b98fb4195642c7473f0d1aa101359aaf278126af1a53bcb482fb05003bfb6bdc03de03c63151b'
-```
+       signed = Account.sign_message(message, private_key=private_key)
+       print(signed.signature.hex())
 
-## **python script**
+       my_dict['signature'] = signed.signature.hex()
 
-```python
-#Python 3.9.6
-#Python 3.9.6
-#eth-account~=0.13.7
-#eth-abi~=5.2.0
-#web3~=7.11.0
-#requests~=2.32.3
-
-import json
-import math
-import time
-import requests
+       print(my_dict)
+       res = requests.post(order_url, data=my_dict, headers=headers)
 
-from eth_abi import encode
-from eth_account import Account
-from eth_account.messages import encode_defunct
-from web3 import Web3
-
-user = '0x63DD5aCC6b1aa0f563956C0e534DD30B6dcF7C4e'
-signer='0x21cF8Ae13Bb72632562c6Fff438652Ba1a151bb0'
-priKey = "0x4fd0a42218f3eae43a6ce26d22544e986139a01e5b34a62db53757ffca81bae1"
-host = 'https://fapi.asterdex.com'
-placeOrder = {'url': '/fapi/v3/order', 'method': 'POST',
-              'params':{'symbol': 'SANDUSDT', 'positionSide': 'BOTH', 'type': 'LIMIT', 'side': 'BUY',
-	         'timeInForce': 'GTC', 'quantity': "30", 'price': 0.325,'reduceOnly': True}}
-getOrder = {'url':'/fapi/v3/order','method':'GET','params':{'symbol':'SANDUSDT','side':"BUY","type":'LIMIT','orderId':2194215}}
-
-def call(api):
-    nonce = math.trunc(time.time() * 1000000)
-    my_dict = api['params']
-    send(api['url'],api['method'],sign(my_dict,nonce))
-
-def sign(my_dict,nonce):
-    my_dict = {key: value for key, value in my_dict.items() if  value is not None}
-    my_dict['recvWindow'] = 50000
-    my_dict['timestamp'] = int(round(time.time()*1000))
-    msg = trim_param(my_dict,nonce)
-    signable_msg = encode_defunct(hexstr=msg)
-    signed_message = Account.sign_message(signable_message=signable_msg, private_key=priKey)
-    my_dict['nonce'] = nonce
-    my_dict['user'] = user
-    my_dict['signer'] = signer
-    my_dict['signature'] = '0x'+signed_message.signature.hex()
-
-    print(my_dict['signature'])
-    return  my_dict
-
-def trim_param(my_dict,nonce) -> str:
-    _trim_dict(my_dict)
-    json_str = json.dumps(my_dict, sort_keys=True).replace(' ', '').replace('\'','\"')
-    print(json_str)
-    encoded = encode(['string', 'address', 'address', 'uint256'], [json_str, user, signer, nonce])
-    print(encoded.hex())
-    keccak_hex =Web3.keccak(encoded).hex()
-    print(keccak_hex)
-    return keccak_hex
-
-def _trim_dict(my_dict) :
-    for key in my_dict:
-        value = my_dict[key]
-        if isinstance(value, list):
-            new_value = []
-            for item in value:
-                if isinstance(item, dict):
-                    new_value.append(json.dumps(_trim_dict(item)))
-                else:
-                    new_value.append(str(item))
-            my_dict[key] = json.dumps(new_value)
-            continue
-        if isinstance(value, dict):
-            my_dict[key] = json.dumps(_trim_dict(value))
-            continue
-        my_dict[key] = str(value)
-
-    return my_dict
-
-def send(url, method, my_dict):
-    url = host + url
-    print(url)
-    print(my_dict)
-    if method == 'POST':
-        headers = {
-            'Content-Type': 'application/x-www-form-urlencoded',
-            'User-Agent': 'PythonApp/1.0'
-        }
-        res = requests.post(url, data=my_dict, headers=headers)
-        print(res.text)
-    if method == 'GET':
-        res = requests.get(url, params=my_dict)
-        print(res.text)
-    if method == 'DELETE':
-        res = requests.delete(url, data=my_dict)
-        print(res.text)
+       print(res.text)
 
 if __name__ == '__main__':
-    call(placeOrder)
-    # call(getOrder)
+    send_by_url()
+    # send_by_body()
 ```
-
 ## **Public Endpoints Info**
 
 ### Terminology