{"id":13877852,"url":"https://github.com/kinecosystem/kin-sdk-python","last_synced_at":"2025-07-16T13:32:48.898Z","repository":{"id":57438404,"uuid":"118318494","full_name":"kinecosystem/kin-sdk-python","owner":"kinecosystem","description":"Kin SDK for Python","archived":true,"fork":false,"pushed_at":"2019-12-19T16:50:51.000Z","size":765,"stargazers_count":27,"open_issues_count":2,"forks_count":12,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-06-13T05:18:28.558Z","etag":null,"topics":["blockchain","cryptocurrency","kin","python","stellar"],"latest_commit_sha":null,"homepage":"https://docs.kin.org/python/sdk","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kinecosystem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-21T08:46:24.000Z","updated_at":"2023-06-10T06:34:52.000Z","dependencies_parsed_at":"2022-08-29T08:40:49.302Z","dependency_job_id":null,"html_url":"https://github.com/kinecosystem/kin-sdk-python","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/kinecosystem/kin-sdk-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinecosystem%2Fkin-sdk-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinecosystem%2Fkin-sdk-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinecosystem%2Fkin-sdk-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinecosystem%2Fkin-sdk-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kinecosystem","download_url":"https://codeload.github.com/kinecosystem/kin-sdk-python/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kinecosystem%2Fkin-sdk-python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265426198,"owners_count":23763000,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","cryptocurrency","kin","python","stellar"],"created_at":"2024-08-06T08:01:30.747Z","updated_at":"2025-07-16T13:32:48.536Z","avatar_url":"https://github.com/kinecosystem.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# This branch is deprecated, and no longer maintained. The current branch for the kin-sdk is \"v2-master\". (Will move to master at a later date)\n\n![Kin Logo](kin.png)  ![Stelalr Logo](stellar.png)\n\n# KIN Python SDK for Stellar Blockchain\n[![Build Status](https://travis-ci.org/kinecosystem/kin-core-python.svg?branch=master)](https://travis-ci.org/kinecosystem/kin-core-python) [![Coverage Status](https://codecov.io/gh/kinecosystem/kin-core-python/branch/master/graph/badge.svg)](https://codecov.io/gh/kinecosystem/kin-core-python)\n\n## Disclaimer\n\nThe SDK is still in beta. No warranties are given, use on your own discretion.\n\n## Requirements.\n\nMake sure you have Python 2 \u003e=2.7.9.\n\n## Installation \n\n```bash\npip install git+https://github.com/kinecosystem/kin-core-python.git\n```\n\n## Usage\n\n### Initialization\n\nTo initialize the SDK, you need to provide the following parameters:\n- (optional) the secret key to init the internal SDK wallet with. If not provided, you will NOT be able to use the \n  following functions: `get_address`, `get_native_balance`, `get_kin_balance`, `create_account`, `monitor_kin_payments`.\n- (optional) the endpoint URI of your [Horizon](https://www.stellar.org/developers/horizon/reference/) node. \n  If not provided, a default Horizon endpoint will be used, either a testnet or pubnet, depending on the `network` \n  parameter below.\n- (optional) a network identifier, which is either `PUBLIC` or `TESTNET`, defaults to `PUBLIC`.\n- (optional) a list of channel keys. If provided, the channel accounts will be used to sign transactions instead \n  of the internal SDK wallet. Use it to insure higher concurrency.\n\n\n```python\nimport kin\n\n# Init SDK without a secret key, in the public Stellar network (for generic blockchain queries)\nsdk = kin.SDK()\n\n# Init SDK without a secret key, for Stellar testnet\nsdk = kin.SDK(network='TESTNET')\n\n# Init SDK without a secret key, with specific Horizon server, running on Stellar testnet\nsdk = kin.SDK(horizon_endpoint_uri='http://my.horizon.uri', network='TESTNET')\n\n# Init SDK with wallet secret key, on public network\nsdk = kin.SDK(secret_key='my key')\n\n# Init SDK with several channels, on public network\nsdk = kin.SDK(secret_key='my key', channel_secret_keys=['key1', 'key2', ...])\n```\nFor more examples, see the [SDK test file](test/test_sdk.py).\n\n\n### Getting Wallet Details\n```python\n# Get the address of my wallet account. The address is derived from the secret key the SDK was inited with.\naddress = sdk.get_address()\n```\n\n### Getting Account Balance\n```python\n# Get native (lumen) balance of the SDK wallet\nnative_balance = sdk.get_native_balance()\n\n# Get KIN balance of the SDK wallet\nkin_balance = sdk.get_kin_balance()\n\n# Get native (lumen) balance of some account\nnative_balance = sdk.get_account_native_balance('address')\n\n# Get KIN balance of some account\nkin_balance = sdk.get_account_kin_balance('address')\n```\n\n### Getting Account Data\n```python\n# returns kin.AccountData\naccount_data = sdk.get_account_data('address')\n```\n\n### Checking If Account Exists\n```python\naccount_exists = sdk.check_account_exists('address')\n```\n\n### Creating a New Account\n```python\n# create a new account prefunded with MIN_ACCOUNT_BALANCE lumens\ntx_hash = sdk.create_account('address')\n\n# create a new account prefunded with a specified amount of native currency (lumens).\ntx_hash = sdk.create_account('address', starting_balance=1000)\n\n# create a new activated account\ntx_hash = sdk.create_account('address', starting_balance=1000, activate=True)  \n```\n### Checking if Account is Activated (Trustline established)\n```python\n# check if KIN is trusted by some account\nkin_trusted = sdk.check_account_activated('address')\n```\n\n### Sending Currency\n```python\n# send native currency (lumens) to some address\ntx_hash = sdk.send_native('address', 100, memo_text='order123')\n\n# send KIN to some address\ntx_hash = sdk.send_kin('address', 1000, memo_text='order123')\n```\n\n### Getting Transaction Data\n```python\n# create a transaction, for example a new account\ntx_hash = sdk.create_account('address')\n# get transaction data, returns kin.TransactionData\ntx_data = sdk.get_transaction_data(tx_hash)\n```\n\n### Transaction Monitoring\n```python\n# define a callback function that receives an address and a kin.TransactionData object\ndef print_callback(address, tx_data):\n    print(address, tx_data)\n    \n# start monitoring KIN payments related to the SDK wallet account\nsdk.monitor_kin_payments(print_callback)\n\n# start monitoring KIN payments related to a list of addresses\nsdk.monitor_accounts_kin_payments(['address1', 'address2'], print_callback)\n\n# start monitoring all transactions related to a list of addresses\nsdk.monitor_accounts_transactions(['address1', 'address2'], print_callback)\n```\n\n#### Receiving Payments from Users\nLet us consider a real-life case when you need to receive payments from users for the orders they make.\nIn order to associate a transaction with an order, we will use the `TransactionData.memo` field:\n\n```python\n# setup your orders cache\norders = {}\n\n# define a callback function that validates payments and marks orders as completed\ndef payment_callback(address, tx_data):\n    order_id = tx_data.memo\n    if order_id not in orders:\n        logging.warn('order not found: {}'.format(order_id))\n        return\n    \n    order = orders[order_id]\n    \n    # check that the order is not yet completed\n    if order['completed'] is not None:\n        logging.warn('order {} is already completed'.format(order_id))\n        return\n        \n    # check that the amount matches \n    if tx_data.operations[0].amount != order['amount']:\n        logging.warn('wrong amount paid for order {}: received {}, need {}'\n            .format(order_id, tx_data.operations[0].amount, order['amount']))\n        return\n        \n    # all good\n    order['completed'] = datetime.now()\n\n\n# start monitoring KIN payments related to the SDK wallet account\nsdk.monitor_kin_payments(payment_callback)   \n\n# when an order comes, store its data in the cache\norder_id = generate_order_id()\norders[order_id] = {\n    'user_id': user_id,\n    'product_id': product_id,\n    'amount': product_cost,\n    'created': datetime.now(),\n    'completed': None\n}\n\n# now pass this order_id to the user and have him insert it into the memo field of his transaction.\n# After he submits the transaction, the payment_callback above will catch it and update the order data.\n```\n\n### Checking Status\nThe handy `get_status` method will return some parameters the SDK was configured with, along with Horizon status:\n```python\nstatus = sdk.get_status()\nprint status\n#  {\n#     'sdk_version': '0.2.0',\n#     'channels': {\n#         'all': 5,  \n#         'free': 5  \n#     }, \n#     'kin_asset': {\n#         'code': 'KIN', \n#         'issuer': '\u003cissuer address\u003e'\n#     }, \n#     'network': 'TESTNET', \n#     'horizon': {\n#         'uri': '\u003chorizon uri\u003e', \n#         'online': True,\n#         'error': None \n#     }, \n#     'address': '\u003csdk wallet address\u003e',\n#     'transport': {\n#         'pool_size': 7,\n#         'num_retries': 5,\n#         'request_timeout': 11,\n#         'retry_statuses': [413, 429, 503, 504],\n#         'backoff_factor': 0.5\n#     }\n#   }\n```\n- `sdk_version` - the version of this SDK.\n- `address` - the SDK wallet address.\n- `channels`:\n  - `all` - the number of channels the SDK was configured with.\n  - `free` - the number of currently free channels. If the number is consistently close to zero, it means the channels\n             are always busy, and you might consider adding more channels or more servers.\n- `kin_asset` - the KIN asset the SDK was configured with.\n- `network` - the network the SDK was configured with (PUBLIC/TESTNET/CUSTOM).\n- `horizon`:\n  - `uri` - the endpoint URI of the Horizon server.\n  - `online` - Horizon online status.\n  - `error` - Horizon error (when not `online`) .\n- `transport`:\n  - `pool_size` - number of pooled connections to Horizon.\n  - `num_retries` - number of retries on failed request.\n  - `request_timeout` - single request timeout.\n  - `retry_statuses` - a list of statuses to retry on.\n  - `backoff_factor` - a backoff factor to apply between retry attempts.\n\n\n## Limitations\n\nOne of the most sensitive points in Stellar is [transaction sequence](https://www.stellar.org/developers/guides/concepts/transactions.html#sequence-number).\nIn order for a transaction to be submitted successfully, this number should be correct. However, if you have several \nSDK instances, each working with the same wallet account or channel accounts, sequence collisions will occur. \nThough the SDK makes an effort to retrieve the correct sequence and retry the transaction, this is not a recommended practice. \nInstead, we highly recommend to keep only one SDK instance in your application, having unique channel accounts.\nDepending on the nature of your application, here are our recommendations:\n\n1. You have a simple (command line) script that sends transactions on demand or only once in a while. \nIn this case, the SDK can be instantiated with only the wallet key, the channel accounts are not necessary.\n\n2. You have a single application server that should handle a stream of concurrent transactions. In this case, \nyou need to make sure that only a single instance of SDK is initialized with multiple channel accounts. \nThis is an important point, because if you use a standard `gunicorn/Flask` setup for example, gunicorn will spawn \nseveral *worker processes*, each containing your Flask application, each containing your SDK instance, so mutliple\nSDK instances will exist, having the same channel accounts. The solution is to use gunicorn *thread workers* instead of\n*process workers*, for example run gunicorn with `--threads` switch instead of `--workers` switch, so that only \none Flask application is created, containing a single SDK instance.\n\n3. You have a number of load-balanced application servers. Here, each application server should a) have the setup outlined\nabove, and b) have its own channel accounts. This way, you ensure you will not have any collisions in your transaction\nsequences.\n\n\n## License\nThe code is currently released under [MIT license](LICENSE).\n\n\n## Contributing\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for SDK contributing guidelines. \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkinecosystem%2Fkin-sdk-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkinecosystem%2Fkin-sdk-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkinecosystem%2Fkin-sdk-python/lists"}