Metadata-Version: 2.4
Name: convex-sdk
Version: 0.3.2
Summary: Convex api
Home-page: https://github.com/Convex-Dev/convex-api-py
Author: dex-company
Author-email: devops@dex.sg
License: Apache Software License 2.0
Keywords: convex api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography~=39.0
Requires-Dist: requests~=2.28
Requires-Dist: mnemonic~=0.2
Requires-Dist: pydantic~=2.0
Provides-Extra: test
Requires-Dist: flake8; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: isort; extra == "test"
Requires-Dist: mypy; extra == "test"
Provides-Extra: docs
Requires-Dist: Sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinxcontrib-apidoc; extra == "docs"
Requires-Dist: sphinxcontrib-plantuml; extra == "docs"
Requires-Dist: sphinx-automodapi; extra == "docs"
Requires-Dist: pygments; extra == "docs"
Requires-Dist: devtools[pygments]; extra == "docs"
Provides-Extra: dev
Requires-Dist: bumpversion; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: Sphinx; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: sphinxcontrib-apidoc; extra == "dev"
Requires-Dist: sphinxcontrib-plantuml; extra == "dev"
Requires-Dist: sphinx-automodapi; extra == "dev"
Requires-Dist: pygments; extra == "dev"
Requires-Dist: devtools[pygments]; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Convex Python SDK

![](https://github.com/Convex-Dev/convex-api-py/workflows/testing/badge.svg)
[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
[![PyPI version](https://badge.fury.io/py/convex-sdk.svg)](https://badge.fury.io/py/convex-sdk)

The official Python client library for interacting with the [Convex](https://convex.world) decentralised lattice network.

## 📚 Documentation

**Official documentation is available at [docs.convex.world/docs/tutorial/client-sdks/python](https://docs.convex.world/docs/tutorial/client-sdks/python)**

- [Quickstart Guide](https://docs.convex.world/docs/tutorial/client-sdks/python/quickstart) - Build your first Python app
- [Query Guide](https://docs.convex.world/docs/tutorial/client-sdks/python/queries) - Read network state
- [Transaction Guide](https://docs.convex.world/docs/tutorial/client-sdks/python/transactions) - Submit transactions
- [Account Management](https://docs.convex.world/docs/tutorial/client-sdks/python/accounts) - Manage keys and accounts

## Installation

```bash
pip install convex-sdk
```

## Quick Example

```python
from convex_sdk import Convex, KeyPair

# Connect to the network
convex = Convex('https://peer.convex.live')

# Create a new account
key_pair = KeyPair()
account = convex.create_account(key_pair)

# Request test funds
convex.request_funds(100_000_000, account)

# Query balance
balance = convex.get_balance(account)
print(f'Balance: {balance / 1_000_000_000} Convex Coins')
```

## Resources

- **[Official Documentation](https://docs.convex.world/docs/tutorial/client-sdks/python)** - Complete SDK guide
- **[PyPI Package](https://pypi.org/project/convex-sdk/)** - Python Package Index
- **[Convex Network](https://convex.world)** - Main website
- **[Discord Community](https://discord.com/invite/xfYGq4CT7v)** - Get help and share ideas

---

### Development Setup

To set up the project for development, follow these steps:

**Prerequisites:**
- Python 3.10 or higher
- pip (Python package installer)

**Setup Steps:**

1. **Create a virtual environment:**
   ```bash
   python -m venv .venv
   ```
   
   This creates a virtual environment in a `.venv` directory. 

2. **Activate the virtual environment:**
   
   - **On Windows (PowerShell or Command Prompt):**
     ```bash
     .venv\Scripts\activate
     ```
   
   - **On Windows (Git Bash):**
     ```bash
     source .venv/Scripts/activate
     ```
   
   - **On Linux/Mac:**
     ```bash
     source .venv/bin/activate
     ```
   
   When activated, you should see `(venv)` at the beginning of your command prompt.

3. **Upgrade pip (recommended):**
   ```bash
   python -m pip install --upgrade pip
   ```

4. **Install the package in development mode with all dependencies:**
   
   Option 1 - Using setup.py extras (recommended):
   ```bash
   pip install -e ".[dev,test,docs]"
   ```
   
   Option 2 - Using requirements files:
   ```bash
   pip install -r requirements-dev.txt
   pip install -e .
   ```

5. **Verify the installation:**
   ```bash
   pytest tests
   ```

**Deactivating the virtual environment:**
When you're done working, you can deactivate the virtual environment by running:
```bash
deactivate
```

**Note:** Always activate your virtual environment before working on the project. The virtual environment ensures that dependencies are isolated from your system Python installation.

### Quick Start

First you need to download the convex-sdk package from the python package index PyPi.

    pip install convex-sdk

You can now access the convex network, and get a balance from an existing account on the network by doing the following:

    >>> from convex_sdk import Convex, KeyPair
    >>> convex = Convex('https://peer.convex.live')
    >>> convex.get_balance(9)
    99396961137042

You can create a new empty account, with no balance:

    >>> key_pair = KeyPair()
    >>> account = convex.create_account(key_pair)
    >>> account.address
    809

You can request some funds to the new account and then get the account information:

    >>> convex.request_funds(1000000, account)
    1000000
    >>> convex.get_account_info(account)
    AccountDetailsResponse(sequence=0, address=809, memorySize=42, balance=1000000, allowance=0, type='user')


You can export the accounts private key encoded as PKCS8 encrypt the key with a password:

    >>> account.key_pair.export_to_text('secret')
    '-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIGbMFcGCSqGSIb3DQEFDTBKMCkGCSqGSIb3DQEFDDAcBAiMY42UY4PXHAICCAAw\nDAYIKoZIhvcNAgkFADAdBglghkgBZQMEASoEEJpwDMicGbGj2iSJesktIVYEQBsp\nKMTAHzvUyw8jZRr8WSrmxH7938sjma8XWI6lgd9jwTZzcGamog7p3zatw0Wp+jFK\nKruWAZmIqhBZ/2ezDv8=\n-----END ENCRYPTED PRIVATE KEY-----\n'

    >>> account.address
    809

To re-use your account again you need to import the encrypted private key and set the correct account address

    >>> from convex_sdk import Account, KeyPair
    >>> key_pair = KeyPair.import_from_file('my_key.dat', 'secret')
    >>> account = Account(key_pair, 809)

To create a new address with the same account keys in your new or imported account object, you can do:

    >>> new_account = convex.create_account(key_pair)
    >>> account.address
    809
    >>> new_account.address
    934

To use account names, where an account name is resolved to a fixed address. You can create or load
an account based on it's name by doing the following:

    >>> account = convex.setup_account('my-account-name', key_pair)
    >>> account.address
    934

    >>> convex.resolve_account_name('my-account-name')
    934

    >>> same_account = convex.setup_account('my-account-name', key_pair)
    >>> same_account.address
    934

To submit a transaction, use Convex.transact(). This will cost a small amount of juice, and reduce your balance

    >>> convex.request_funds(1000000, account)
    1000000
    >>> convex.transact('(map inc [1 2 3 4])', account)
    {'value': [2, 3, 4, 5]}
    >>> convex.get_balance(account)
    996360

To send a query a transaction, this is free and can be performed by any valid account address.
So for example to query a balance of an account:

    >>> convex.query(f'(balance {account.address})', account)
    {'value': 996360}

    # this is the same as above
    >>> convex.query(f'(balance {account.address})', account.address)
    {'value': 996360}

    # get the balance using one of the standard account addresses (#1)
    >>> convex.query(f'(balance {account.address})', 1)
    {'value': 996360}

