The official Python connector for Tanx's API
Project description
tanX Connector Python
The official Python connector for tanX's API 🚀
Features
- Complete endpoints including REST and WebSockets
- Methods return parsed JSON.
- High level abstraction for ease of use.
- Easy authentication
- Automatically sets JWT token internally
- Auto refresh tokens when access token expires
Tanx-connector-python includes utility/connector functions which can be used to interact with the Tanx API. It uses requests internally to handle all requests.
Table of Contents
- Features
- Table of Contents
- Installation
- Quickstart
- Getting Started
- Workflow
- L2 Key Pair
- Rest Client
- General Endpoints
- Test Connectivity
- 24hr Price
- Kline/Candlestick Data
- Order Book
- Recent trades
- Login
- Refresh Token
- Logout
- Profile Information (Private 🔒)
- Balance details (Private 🔒)
- Profit and Loss Details (Private 🔒)
- Create order (Private 🔒)
- Get Order (Private 🔒)
- List Orders (Private 🔒)
- Cancel Order (Private 🔒)
- List Trades (Private 🔒)
- WebSocket Client
- Error Handling
- Internal Transfer
- Deposit
- Withdrawal
Installation
First go to the tanX Website and create an account with your wallet.
Install the package using pip.
pip install tanx-connector
Quickstart
Make sure that tanxconnector is installed and up-to-date. Also make sure you have an account on the mainnet or testnet website.
To get quickly started, try running the simple example for creating and fetching the order once logged in.
from tanxconnector import Client
ETH_ADDRESS = "(your eth wallet address)"
PRIVATE_KEY = "(your wallet's private key)"
client = Client()
# login to the network
login = client.complete_login(ETH_ADDRESS, PRIVATE_KEY)
# create an order nonce
nonce: CreateOrderNonceBody = {'market': 'ethusdc', 'ord_type':'market', 'price': 29580.51, 'side': 'sell', 'volume': 0.0005}
# create the order
order = client.create_complete_order(nonce, stark_private_key)
print(order)
# fetch the details of the order just created
order_id = order['payload']['id']
fetch_order = client.get_order(order_id)
print(fetch_order)
Getting Started
The default base url for mainnet is https://api.tanx.fi and testnet is https://api-testnet.tanx.fi. You can choose between mainnet and testnet by providing it through the constructor. The default is mainnet. All REST apis, WebSockets are handled by Client, WsClient classes respectively.
Workflow
Check out the example files to see an example workflow.
L2 Key Pair
L2 Key Pair generation isn't currently available in the TanX Python SDK.
To get the L2 Key Pair, follow any of the two steps:
- Get the Key Pair from the TanX official website's Account Settings Tab once wallet is connected. Refer to the image below for more reference. Click on
Settings -> tanX key -> Show Keys
and Sign the request to get the keys. Copy these keys and store it securely.
- Generate the L2 key pair using the TanX Nodejs SDK. For generation using the Node SDK, refer to this section in the documentation of the Nodejs SDK.
Rest Client
Import the REST Client
from tanxconnector import Client
Create a new instance
client = Client()
# or
client = Client()
# default is mainnet
General Endpoints
Test connectivity
GET /sapi/v1/health/
client.test_connection()
24hr Price
GET /sapi/v1/market/tickers/
client.get_24h_price('btcusdt')
Kline/Candlestick Data
GET /sapi/v1/market/kline/
client.get_candlestick('btcusdt')
Order Book
GET /sapi/v1/market/orderbook/
client.get_orderbook('btcusdt')
Recent trades
GET /sapi/v1/market/trades/
client.get_recent_trades('btcusdt')
Login
Both login() and complete_Login() sets tokens internally. Optionally, set_access_token() and set_refresh_token() can be used to set tokens directly.
getNonce: POST /sapi/v1/auth/nonce/
login: POST /sapi/v1/auth/login/
from tanxconnector import sign_msg, Client
client = Client()
client.complete_login(ETH_ADDRESS, PRIVATE_KEY)
# calls below functions internally, use this for ease
# or
nonce = client.get_nonce(ETH_ADDRESS)
user_signature = sign_msg(nonce['payload'], PRIVATE_KEY)
login = client.login(ETH_ADDRESS, user_signature)
# or
client.set_access_token(access_token)
client.set_refresh_token(refresh_token)
# these functions are called internally when you use login or complete_login
Refresh Token
POST /sapi/v1/auth/token/refresh/
If refresh token is set (manually or by using login functions), the refresh endpoint is called automatically when access token expires. Optionally, you can call refresh_tokens
manually by passing in refresh_token (passing it is optional, it'll work if has been set before).
res = client.refresh_tokens(refresh_token)
Logout
Sets tokens to null
client.logout()
Profile Information (Private 🔒)
GET /sapi/v1/user/profile/
client.get_profile_info()
Balance details (Private 🔒)
GET /sapi/v1/user/balance/
client.get_balance()
Profit and Loss Details (Private 🔒)
GET /sapi/v1/user/pnl/
client.get_profit_and_loss()
Create order (Private 🔒)
Order is created in 2 steps:
- Create the order nonce body
- Process the order nonce body with the stark private key to create the order
Create Nonce Body
from tanxconnector.typings import CreateOrderNonceBody
nonce: CreateOrderNonceBody = {'market': 'btcusdt', 'ord_type': 'market',
'price': 29580.51, 'side': 'buy', 'volume': 0.0001}
Create Order
create_order_nonce: POST /sapi/v1/orders/nonce/
create_new_order: POST /sapi/v1/orders/create/
For getting the L2 Key Pairs (Stark Keys) refer to the above section in the documentation.
stark_private_key = '(Your Stark Private Key Here)'
order = client.create_complete_order(nonce, stark_private_key)
# calls below functions internally, we recommend using createCompleteOrder for ease of use
# or
from tanxconnector import sign_order_with_stark_private_key
nonce_res = client.create_order_nonce(nonce)
msg_hash = sign_order_with_stark_private_key(stark_private_key, nonce_res['payload'])
order = client.create_new_order(msg_hash)
Get Order (Private 🔒)
GET /sapi/v1/orders/{order_id}/
client.get_order(order_id)
List Orders (Private 🔒)
GET /sapi/v1/orders/
client.list_orders(
limit=50,
page=1,
market='btcusdc',
state='wait',
base_unit='btc',
quote_unit='usdc',
start_time=1694785739,
end_time=1694785839,
side='buy'
)
Cancel Order (Private 🔒)
POST /sapi/v1/orders/cancel/
client.cancel_order(order_id)
List Trades (Private 🔒)
GET /sapi/v1/trades/
client.list_trades()
WebSocket Client
Import the WebSocket Client. All WsClient methods are asynchronous (use async/await method).
from tanxconnector import WsClient
import asyncio
Create a new instance
ws_client = WsClient('public')
// or
ws_client = WsClient('public', 'mainnet')
// default is mainnet
// or
login = client.complete_login(ETH_ADDRESS, PRIVATE_KEY)
ws_client = WsClient('private', 'mainnet', login['token']['access'])
Connect
await ws_client.connect()
Subscribe
streams = [
'btcusdc.trades',
'btcusdc.ob-inc',
'btcusdc.kline-5m',
]
await ws_client.subscribe(streams)
# or for private
await ws_client.subscribe(['trade', 'order'])
Unsubscribe
streams = [
'btcusdc.trades',
'btcusdc.ob-inc',
'btcusdc.kline-5m',
]
await ws_client.unsubscribe(streams)
# or for private
await ws_client.unsubscribe(['trade', 'order'])
Disconnect
ws_client.disconnect()
Usage
WsClient includes a member called websocket which is initialized with websockets.connect(). You may use it to handle WebSocket operations.
async for message in ws_client.websocket:
print(message)
Error Handling
Errors thrown are of types AuthenticationError or requests.exceptions.HTTPError
.
Example
try:
# call methods
except tanxconnector.exception.AuthenticationError as exc:
print(exc)
except requests.exceptions.HTTPError as exc:
print(exc.response.json())
Internal Transfer
Users will be able to seamlessly transfer assets from their CEXs or other chains with minimal fees.
To get started with the feature, follow these two steps:
-
Reach out to tanX (support@tanx.fi) to get the organization key and API key.
-
Generate the L2 key pair with your private key
Available methods:
- To process the internal transfer, call the
intiate_and_process_internal_transfers
method and pass the necessary arguments:
key_pair = {
'stark_public_key': '(your stark public key here)'
'stark_private_key': '(your stark private key here)'
}
ETH_ADDRESS_2 = '(destination Eth wallet address here)'
internal_transfer_response = client.intiate_and_process_internal_transfers(
key_pair=key_pair,
organization_key=TANX_ORGANIZATION_KEY,
api_key=TANX_API_KEY,
currency='usdc',
amount=1,
destination_address=ETH_ADDRESS_2,
client_reference_id=1
)
- Retrieve a list of transfers initiated by the authenticated user:
internal_trasnfers_list = client.list_internal_transfers({
'limit': 10,
'offset': 10
})
- Retrieve an internal transfer using its client reference id:
internal_transfer_by_id = client.get_internal_transfer_by_client_id(client_reference_id)
- Check if a user exists by their destination address.
check_user_res = client.check_internal_transfer_user_exists(
TANX_ORGANIZATION_KEY,
TANX_API_KEY,
destination_address,
)
Deposit
Ethereum Network Deposit
This method involves using a custom provider and signer, which can be created using the web3.py library. The stark_public_key
mentioned in the code should be obtained using the steps described in the L2 Key Pair section of the documentation. Here's the code snippet for this method:
# Note: Please use web3 version 5.25.0
from web3 import Web3, Account
provider = Web3(Web3.HTTPProvider(RPC_PROVIDER))
signer = Account.from_key(PRIVATE_KEY)
deposit_res_with_stark_keys = client.deposit_from_ethereum_network_with_stark_key(
signer,
provider,
f'0x{stark_public_key}',
0.0001,
'usdc'
)
Polygon Network Deposit
There are two ways to make a deposit on the Polygon network:
- Using ETH Private Key and RPC URL:
In this method, you will use an ETH private key and an RPC URL to execute a Polygon deposit. You'll also need to create an RPC URL using services like Infura, Alchemy, etc. Here's the code snippet for this method:
deposit_res = client.deposit_from_polygon_network(
RPC_PROVIDER_FOR_POLYGON, # Use 'Polygon Mumbai' for the testnet and 'Polygon mainnet' for the mainnet.
PRIVATE_KEY, # ETH Private Key
'matic', # Coin Symbol
0.00001 # Amount to be deposited
)
- Using Custom Provider and Signer:
This method involves using a custom provider and signer, which can be created using the web3.py library. Also, its important to inject a middleware at the 0th layer of the middleware onion for the provider (See Reference). Here's the code snippet for this method:
# Note: Please use ethers version 5.25.0.
from web3 import Web3, Account
from web3.middleware.geth_poa import geth_poa_middleware
provider = Web3(Web3.HTTPProvider(RPC_PROVIDER_FOR_POLYGON))
provider.middleware_onion.inject(geth_poa_middleware, layer=0)
signer = Account.from_key(PRIVATE_KEY)
polygon_deposit_res = client.deposit_from_polygon_network_with_signer(
signer, # Signer Created above
provider, # Provider created above
'btc', # Enter the coin symbol
0.0001, # Amount to be deposited
)
List Deposits
To get the deposit history, you can use the following code:
deposit_list = client.list_deposits({
'page': 1, # This field is optional
'limit': 1, # This field is optional
'network': 'ETHEREUM' # Network for which you want to list the deposit history. Allowed networks are ETHEREUM & POLYGON
})
Withdrawal
Generally, we have two modes of withdrawal: Normal Withdrawal and Fast Withdrawal. For withdrawal methods that require a signer and provider, please refer to the deposit method mentioned above.
Normal Withdrawal (Only for ETHEREUM Network)
With Normal Withdrawal, your requested funds will be processed within a standard time frame (24 hours). This mode is suitable for users who are not in a rush to access their funds and are comfortable with the regular processing time. The stark keys (L2 Key Pair)
can be generated with the help of this section of the documentation.
from web3 import Web3, Account
provider = Web3(Web3.HTTPProvider(RPC_PROVIDER))
signer = Account.from_key(PRIVATE_KEY)
gas_price = provider.eth.gas_price # or any custom value
key_pair = {
'stark_public_key': stark_public_key,
'stark_private_key': stark_private_key
}
# Withdrawals
# Normal withdrawal:
# 1. Initiate your withdrawal request by calling the "initiateNormalWithdrawal" function.
withdrawal_res = client.initiate_normal_withdrawal(
key_pair, # The keyPair created for stark keys
0.0001, # Enter the amount you want to deposit
'usdc', # Enter the coin symbol
)
# 2. WAIT for up to 24 hours.
# 3. Check whether the withdrawn balance is pending by calling the "getPendingNormalWithdrawalAmountByCoin" function with the required parameters.
pending_balance = client.get_pending_normal_withdrawal_amount_by_coin(
'eth', # Enter the coin symbol
eth_address, # User public eth address
signer, # The signer created above
provider, # The provider created above
gas_price, # max gas price for the transaction
)
# 4. In the final step, if you find the balance is more than 0, you can use the "completeNormalWithdrawal" function to withdraw the cumulative amount to your ETH wallet.
complete_normal_withdrawal_res = client.complete_normal_withdrawal(
'eth', # Enter the coin symbol
ethAddress, # User public eth address
signer, # The signer created above
provider, # The provider created above
)
#Get a list of withdrawals
withdrawals_list = client.list_normal_withdrawals({
page: 2, # This is an optional field
})
Fast Withdrawal
With Fast Withdrawal, your funds will be processed in an expedited timeframe, often within a few minutes. This mode is ideal for users who require immediate access to their funds and are comfortable with paying a fee. The stark keys (L2 Key Pair)
can be generated with the help of this section of the documentation.
- Ethereum Network
key_pair = {
'stark_public_key': stark_public_key,
'stark_private_key': stark_private_key
}
fast_withdrawal_res = client.fast_withdrawal(
key_pair, # The keyPair created above
0.0001, # Enter the amount you want to deposit
'usdc', # Enter the coin symbol
'ETHEREUM', # Allowed networks are POLYGON & ETHEREUM
)
- Polygon network
const fastWithdrawalRes = await client.fastWithdrawal(
key_pair, # The keyPair created above
0.001, # Enter the amount you want to deposit
'btc', # Enter the coin symbol
'POLYGON', # Allowed networks are POLYGON & ETHEREUM
)
- Get a list of fast withdrawals
fast_withdrawals_list = client.list_fast_withdrawals({
'page': 2, # This is an optional field
'network': 'POLYGON' # This is an optional field
})
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for tanx_connector-2.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e9854119568bbb97db8d9a6d16ade4a5da391c75c2c7ff28d6b579737564425b |
|
MD5 | 822e3692ff7ccb4eed5455d714b8f362 |
|
BLAKE2b-256 | 4eaf9273b7f149a1f22aa46b8abd11585cf207343face9792acb8401d6ccdc75 |