Convex Python SDK

The official Python client library for interacting with the Convex decentralised lattice network.

📚 Documentation

Official documentation is available at docs.convex.world/docs/tutorial/client-sdks/python

• Quickstart Guide - Build your first Python app
• Query Guide - Read network state
• Transaction Guide - Submit transactions
• Account Management - Manage keys and accounts

Installation

pip install convex-sdk

Quick Example

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 - Complete SDK guide
• PyPI Package - Python Package Index
• Convex Network - Main website
• Discord Community - 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:

   python -m venv .venv
   

   This creates a virtual environment in a .venv directory.

2. Activate the virtual environment:

   • On Windows (PowerShell or Command Prompt):

     .venv\Scripts\activate
     

   • On Windows (Git Bash):

     source .venv/Scripts/activate
     

   • On Linux/Mac:

     source .venv/bin/activate
     

   When activated, you should see (venv) at the beginning of your command prompt.

3. Upgrade pip (recommended):

   python -m pip install --upgrade pip
   

4. Install the package in development mode with all dependencies:

   Option 1 - Using setup.py extras (recommended):

   pip install -e ".[dev,test,docs]"
   

   Option 2 - Using requirements files:

   pip install -r requirements-dev.txt
   pip install -e .
   

5. Verify the installation:

   pytest tests
   

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

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}