circle-web3-sdk-util 9.3.0

The Python SDK Utility for Circle Web3 Services

Circle Web3 APIs Python SDK

The Circle Web3 Python SDK provides convenient access to the Circle Web3 APIs for applications written in Python. For the API reference, see the Circle Web3 API Docs. Also see this project's PyPI Package Page [TODO].

Requirements

Python 3.10+.

Java 11 and Node 10+ (optional for contributing and development).

Installation

The recommended way of installation is using the Python Package Index (PyPI):

pip install circle-developer-controlled-wallets
pip install circle-smart-contract-platform
pip install circle-user-controlled-wallets

Environment Setup (for Development)

We recommend using pyenv with pyenv-virtualenv for managing Python versions and virtual environments.

Installing pyenv

# Install via Homebrew
brew install pyenv

Installing pyenv-virtualenv

brew install pyenv-virtualenv

Shell Configuration

Add the following to your ~/.zshrc (source):

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"
eval "$(pyenv virtualenv-init -)"

After adding these lines, restart your terminal or run source ~/.zshrc.

Setting Up Your Development Environment

1. Install Python (reads version from .python-version):

   pyenv install
   

2. Create a virtual environment for this project:

   pyenv virtualenv $(basename $(pwd))
   

3. Set the virtualenv for this project directory (enables auto-activation):

   pyenv local $(basename $(pwd))
   

4. Verify the setup:

   # Should show the virtualenv name
   pyenv version
   
   # Should show Python 3.10.x
   python --version
   

The virtualenv will auto-activate when you enter the project directory (requires eval "$(pyenv virtualenv-init -)" in your shell config above).

Installing Python Dependencies

Python dependencies will be installed after building the SDK (see Development section below).

Development

Prerequisites

Complete the Environment Setup section above before proceeding.

Building the SDK

1. Initialize git submodules:

   git submodule update --init --recursive
   

2. Build the OpenAPI specifications:

   (cd w3s-openapi-internal && npm ci && make bundle)
   

3. Install Node dependencies:

   npm ci
   

4. Generate the SDK code from OpenAPI specifications:

   npm run build
   

5. Install built SDK distribution packages:

   npm run install-dist
   

Running Tests

# Run all tests
npm run test:all

# Run only unit tests
npm run test

# Run only e2e tests
npm run test:e2e

Usage

Initialize circle web3 API clients. To secure your entity secret and circle API key. Set the API key and entity secret as environment variables. Learn more about entity secret management here

export CIRCLE_ENTITY_SECRET="Your entity secret"
export CIRCLE_WEB3_API_KEY="Your API KEY"

from circle.web3 import utils

dcw_client = utils.init_developer_controlled_wallets_client(api_key="Your API KEY", entity_secret="Your entity secret")
scp_client = utils.init_smart_contract_platform_client(api_key="Your API KEY", entity_secret="Your entity secret")
ucw_client = utils.init_user_controlled_wallets_client(api_key="Your API KEY")

Using client to make a transaction.

from circle.web3 import user_controlled_wallets

# Create a API instance
ucw_client = utils.init_user_controlled_wallets_client(api_key="<your-api-key>")

api_instance = user_controlled_wallets.PINAuthenticationApi(ucw_client)
try:
    api_request = user_controlled_wallets.UserTokenRequest.from_dict({"userId": "test-user"})
    api_response = api_instance.get_user_token(api_request)
    print(api_response.data.user_token)
except user_controlled_wallets.ApiException as e:
    print("Exception when calling PINAuthenticationApi->get_user_token: %s\n" % e)

Contributions

Please follow the Conventional Commits format for all commits when creating a contributing pull request for this repo.