| Name | ticton JSON |
| Version |
0.1.31
JSON |
| download |
| home_page | |
| Summary | |
| upload_time | 2024-03-08 16:31:17 |
| maintainer | |
| docs_url | None |
| author | alan890104 |
| requires_python | >=3.10,<3.12 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TicTon Python SDK
This is the Python SDK for Tic Ton Oracle on TON blockchain, which is a pure decentralized oracle protocol that can provide latest price with high precision guraranteed by incentive mechanism.
## Installation
Install the SDK using pip:
```bash
pip install ticton
```
## (Optional) Setting the Environment Variables
The SDK requires several environment variables for its operation.You can set the environment variables using the `export` command in your shell. Here are the variables you need to set:
- `TICTON_WALLET_MNEMONICS`: A space-separated list of mnemonics used for wallet authentication and operations.
- `TICTON_WALLET_VERSION`: Specifies the wallet version. Supported values are "v2r1", "v2r2", "v3r1", "v3r2", "v4r1", "v4r2", "hv2". The default is "v4r2".
- `TICTON_ORACLE_ADDRESS`: The address of the oracle smart contract on the TON blockchain.
- `TICTON_TONCENTER_API_KEY`: An API key for accessing TON blockchain data. You can apply for an API key at [@tonapibot](https://t.me/tonapibot).
- `TICTON_THRESHOLD_PRICE`: A float value that sets a threshold price, with a default of 0.7.
```bash
export TICTON_WALLET_MNEMONICS="word1 word2 word3 ... wordN"
export TICTON_WALLET_VERSION="v4r2"
export TICTON_ORACLE_ADDRESS="your_oracle_address"
export TICTON_TONCENTER_API_KEY="your_api_key"
export TICTON_THRESHOLD_PRICE=0.7
```
## Initialization
If you have already set the environment variables by using the `export` command, you can easily initialize the ticton client using the following code:
```python
from ticton import TicTonAsyncClient
client = await TicTonAsyncClient.init()
```
Alternatively, if you prefer not to set global environment variables, you can pass these directly to the initialization function:
```python
from ticton import TicTonAsyncClient
client = await TicTonAsyncClient.init(
wallet_mnemonics="word1 word2 word3 ... wordN",
wallet_version="v4r2",
oracle_address="your_oracle_address",
toncenter_api_key="your_api_key",
threshold_price=0.7
)
```
## Usage Example
[Use Case - Ticton Oracle Automation](https://github.com/Ton-Dynasty/ticton-oracle-automation/tree/main)
### Tick
tick will open a alarm with the given price and timeout, the total amount
of baseAsset and quoteAsset will be calculated automatically.
#### Parameters
- `price` : float
- The price of the alarm quoteAsset/baseAsset
- `timeout` : int (optional, default=1000)
- The timeout of the alarm in seconds
- `extra_ton` : float (optional, default=0.1)
- The extra ton to be sent to the oracle
#### Example
Assume the token pair is TON/USDT, the price is 2.5 USDT per TON
```python
price = 2.5
result = await client.tick(price)
```
### Ring
ring will close the alarm with the given alarm_id
#### Parameters
- `alarm_id` : int
- The alarm_id of the alarm to be closed
#### Example
```python
alarm_id = 1
result = await client.ring(alarm_id)
```
### Wind
wind will arbitrage the alarm with the given alarm_id, buy_num and new_price
#### Parameters
- `alarm_id` : int
- The alarm_id of the alarm to be arbitrage
- `buy_num` : int
- The number of tokens to be bought, at least 1.
- `new_price` : float
- The new price of the alarm quoteAsset/baseAsset
#### Example
Assume the token pair is TON/USDT, the price is 2.5 USDT per TON. The alarm is opened with 1 TON and 2.5 USDT with index 123.
The new price is 5 USDT per TON, the buy_num is 1.
```python
alarm_id = 123
buy_num = 1
new_price = 5
result = await client.wind(alarm_id, buy_num, new_price)
```
### Subscribe
subscribe will subscribe the oracle's transactions, handle the transactions and call the
given callbacks.
#### Parameters
- `on_tick_success`: function
- The callback function to be called when the tick transaction is successful, with the following parameters:
- `watchmaker` : str
- `base_asset_price` : float
- `new_alarm_id` : int
- `created_at` : int
- `on_ring_success`: function
- The callback function to be called when the ring transaction is successful, with the following parameters:
- `alarm_id` : int
- `created_at` : int
- `origin` : str
- `receiver` : str
- `amount` : int
- `on_wind_success`: function
- The callback function to be called when the wind transaction is successful, with the following parameters:
- `timekeeper` : str
- `alarm_id` : int
- `new_base_asset_price` : float
- `remain_scale` : int
- `new_alarm_id` : int
- `created_at` : int
- start_lt: int, "oldest", "latest" (optional, default="oldest")
- From when to yield transaction, default to replay the transaction from the oldest transaction
#### Examples
```python
async def on_tick_success(params: OnTickSuccessParams):
print(f"Tick success", params.model_dump())
async def on_ring_success(params: OnRingSuccessParams):
print(f"Tick success", params.model_dump())
async def on_wind_success(params: OnWindSuccessParams):
print(f"Tick success", params.model_dump())
await client.subscribe(on_tick_success, on_ring_success, on_wind_success)
```
## Development Guide
### Install
1. Make sure [poetry](https://python-poetry.org/docs/#installation) installed on your machine.
> you may need to set the `PATH` environment variable to include the Poetry binary directory, e.g. `export PATH="$HOME/.local/bin:$PATH"`
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
2. Install plugin for poetry
``` bash
poetry self add poetry-bumpversion
poetry self add poetry-plugin-export
```
3. Install dependencies
```bash
make install
```
4. Start your virtual environment
```bash
poetry shell
```
5. Run tests
```bash
poetry run pytest
```
Raw data
{
"_id": null,
"home_page": "",
"name": "ticton",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<3.12",
"maintainer_email": "",
"keywords": "",
"author": "alan890104",
"author_email": "alan890104@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b6/0f/2916887437afffcb31a10070623c81d758d89e441959ef317f3e48ade97f/ticton-0.1.31.tar.gz",
"platform": null,
"description": "# TicTon Python SDK\n\nThis is the Python SDK for Tic Ton Oracle on TON blockchain, which is a pure decentralized oracle protocol that can provide latest price with high precision guraranteed by incentive mechanism.\n\n## Installation\nInstall the SDK using pip:\n```bash\npip install ticton\n```\n\n## (Optional) Setting the Environment Variables\nThe SDK requires several environment variables for its operation.You can set the environment variables using the `export` command in your shell. Here are the variables you need to set:\n- `TICTON_WALLET_MNEMONICS`: A space-separated list of mnemonics used for wallet authentication and operations.\n- `TICTON_WALLET_VERSION`: Specifies the wallet version. Supported values are \"v2r1\", \"v2r2\", \"v3r1\", \"v3r2\", \"v4r1\", \"v4r2\", \"hv2\". The default is \"v4r2\".\n- `TICTON_ORACLE_ADDRESS`: The address of the oracle smart contract on the TON blockchain.\n- `TICTON_TONCENTER_API_KEY`: An API key for accessing TON blockchain data. You can apply for an API key at [@tonapibot](https://t.me/tonapibot).\n- `TICTON_THRESHOLD_PRICE`: A float value that sets a threshold price, with a default of 0.7.\n```bash\nexport TICTON_WALLET_MNEMONICS=\"word1 word2 word3 ... wordN\"\nexport TICTON_WALLET_VERSION=\"v4r2\"\nexport TICTON_ORACLE_ADDRESS=\"your_oracle_address\"\nexport TICTON_TONCENTER_API_KEY=\"your_api_key\"\nexport TICTON_THRESHOLD_PRICE=0.7\n```\n## Initialization\nIf you have already set the environment variables by using the `export` command, you can easily initialize the ticton client using the following code:\n```python\nfrom ticton import TicTonAsyncClient\n\nclient = await TicTonAsyncClient.init()\n```\nAlternatively, if you prefer not to set global environment variables, you can pass these directly to the initialization function:\n```python\nfrom ticton import TicTonAsyncClient\n\nclient = await TicTonAsyncClient.init(\n wallet_mnemonics=\"word1 word2 word3 ... wordN\",\n wallet_version=\"v4r2\",\n oracle_address=\"your_oracle_address\",\n toncenter_api_key=\"your_api_key\",\n threshold_price=0.7\n)\n```\n\n## Usage Example\n[Use Case - Ticton Oracle Automation](https://github.com/Ton-Dynasty/ticton-oracle-automation/tree/main)\n\n### Tick\ntick will open a alarm with the given price and timeout, the total amount\nof baseAsset and quoteAsset will be calculated automatically.\n\n#### Parameters\n- `price` : float\n - The price of the alarm quoteAsset/baseAsset\n- `timeout` : int (optional, default=1000)\n - The timeout of the alarm in seconds\n- `extra_ton` : float (optional, default=0.1)\n - The extra ton to be sent to the oracle\n#### Example\n\nAssume the token pair is TON/USDT, the price is 2.5 USDT per TON\n```python\nprice = 2.5\n\nresult = await client.tick(price)\n```\n### Ring\nring will close the alarm with the given alarm_id\n\n#### Parameters\n- `alarm_id` : int\n - The alarm_id of the alarm to be closed\n#### Example\n```python\nalarm_id = 1\n\nresult = await client.ring(alarm_id)\n```\n### Wind\nwind will arbitrage the alarm with the given alarm_id, buy_num and new_price\n\n#### Parameters\n- `alarm_id` : int\n - The alarm_id of the alarm to be arbitrage\n- `buy_num` : int\n - The number of tokens to be bought, at least 1.\n- `new_price` : float\n - The new price of the alarm quoteAsset/baseAsset\n\n#### Example\nAssume the token pair is TON/USDT, the price is 2.5 USDT per TON. The alarm is opened with 1 TON and 2.5 USDT with index 123.\nThe new price is 5 USDT per TON, the buy_num is 1.\n```python\nalarm_id = 123\nbuy_num = 1\nnew_price = 5\n\nresult = await client.wind(alarm_id, buy_num, new_price)\n```\n### Subscribe\nsubscribe will subscribe the oracle's transactions, handle the transactions and call the\ngiven callbacks.\n\n#### Parameters\n- `on_tick_success`: function\n - The callback function to be called when the tick transaction is successful, with the following parameters:\n - `watchmaker` : str\n - `base_asset_price` : float\n - `new_alarm_id` : int\n - `created_at` : int\n\n- `on_ring_success`: function\n - The callback function to be called when the ring transaction is successful, with the following parameters:\n - `alarm_id` : int\n - `created_at` : int\n - `origin` : str\n - `receiver` : str\n - `amount` : int \n\n- `on_wind_success`: function\n - The callback function to be called when the wind transaction is successful, with the following parameters:\n - `timekeeper` : str\n - `alarm_id` : int\n - `new_base_asset_price` : float\n - `remain_scale` : int\n - `new_alarm_id` : int\n - `created_at` : int\n\n- start_lt: int, \"oldest\", \"latest\" (optional, default=\"oldest\")\n - From when to yield transaction, default to replay the transaction from the oldest transaction\n\n#### Examples\n```python\nasync def on_tick_success(params: OnTickSuccessParams):\n print(f\"Tick success\", params.model_dump())\n\nasync def on_ring_success(params: OnRingSuccessParams):\n print(f\"Tick success\", params.model_dump())\n\nasync def on_wind_success(params: OnWindSuccessParams):\n print(f\"Tick success\", params.model_dump())\n\nawait client.subscribe(on_tick_success, on_ring_success, on_wind_success)\n```\n\n\n## Development Guide\n\n### Install\n\n1. Make sure [poetry](https://python-poetry.org/docs/#installation) installed on your machine.\n\n > you may need to set the `PATH` environment variable to include the Poetry binary directory, e.g. `export PATH=\"$HOME/.local/bin:$PATH\"`\n\n ```bash\n curl -sSL https://install.python-poetry.org | python3 -\n ```\n\n2. Install plugin for poetry\n\n ``` bash\n poetry self add poetry-bumpversion\n poetry self add poetry-plugin-export\n ```\n\n3. Install dependencies\n\n ```bash\n make install\n ```\n\n4. Start your virtual environment\n\n ```bash\n poetry shell\n ```\n\n5. Run tests\n\n ```bash\n poetry run pytest\n ```\n",
"bugtrack_url": null,
"license": "",
"summary": "",
"version": "0.1.31",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f41833818333f41bf9b03c4fd28d81db570ff50750da5a38b791ffdc0107a244",
"md5": "2375b72c0b7d3375077c064070d4519f",
"sha256": "ae1579651e5600ec738e888c66330455c7e0ecab038d0938f0859a37ac37c904"
},
"downloads": -1,
"filename": "ticton-0.1.31-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2375b72c0b7d3375077c064070d4519f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<3.12",
"size": 16746,
"upload_time": "2024-03-08T16:31:15",
"upload_time_iso_8601": "2024-03-08T16:31:15.650154Z",
"url": "https://files.pythonhosted.org/packages/f4/18/33818333f41bf9b03c4fd28d81db570ff50750da5a38b791ffdc0107a244/ticton-0.1.31-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b60f2916887437afffcb31a10070623c81d758d89e441959ef317f3e48ade97f",
"md5": "6abd8ef36d9bf8ae0191dccc9668b77c",
"sha256": "cb65037cbfead435121e0df44983d335ccabfbde4c07d633b1c80d27bcf71abd"
},
"downloads": -1,
"filename": "ticton-0.1.31.tar.gz",
"has_sig": false,
"md5_digest": "6abd8ef36d9bf8ae0191dccc9668b77c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<3.12",
"size": 16580,
"upload_time": "2024-03-08T16:31:17",
"upload_time_iso_8601": "2024-03-08T16:31:17.284138Z",
"url": "https://files.pythonhosted.org/packages/b6/0f/2916887437afffcb31a10070623c81d758d89e441959ef317f3e48ade97f/ticton-0.1.31.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-08 16:31:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ticton"
}
