Metadata-Version: 2.4
Name: circle-web3-sdk-util
Version: 9.3.0
Summary: The Python SDK Utility for Circle Web3 Services
Home-page: https://github.com/crcl-main/circle-web3-python-sdk
Author: Circle Technology Inc
Author-email: bohan.li@circle.com
License: MIT License
Project-URL: Source, https://github.com/crcl-main/circle-web3-python-sdk
Project-URL: Developer Doc, https://developers.circle.com/w3s/
Keywords: Circle,Web3,Python,Developer Controlled Wallets,User Controlled Wallets,Smart Contract Platform
Requires-Python: >=3.10,<4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pycryptodome>=3.20.0
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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](https://developers.circle.com/w3s/reference/getping). 
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):
```sh
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

```sh
# Install via Homebrew
brew install pyenv
```

### Installing pyenv-virtualenv

```sh
brew install pyenv-virtualenv
```

### Shell Configuration

Add the following to your `~/.zshrc` ([source](https://github.com/pyenv/pyenv?tab=readme-ov-file#zsh)):

```sh
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`):
   ```sh
   pyenv install
   ```

2. **Create a virtual environment** for this project:
   ```sh
   pyenv virtualenv $(basename $(pwd))
   ```

3. **Set the virtualenv for this project directory** (enables auto-activation):
   ```sh
   pyenv local $(basename $(pwd))
   ```

4. **Verify the setup**:
   ```sh
   # 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](#environment-setup-for-development) section above before proceeding.

### Building the SDK

1. **Initialize git submodules**:
   ```sh
   git submodule update --init --recursive
   ```

2. **Build the OpenAPI specifications**:
   ```sh
   (cd w3s-openapi-internal && npm ci && make bundle)
   ```

3. **Install Node dependencies**:
   ```sh
   npm ci
   ```

4. **Generate the SDK code** from OpenAPI specifications:
   ```sh
   npm run build
   ```

5. **Install built SDK distribution packages**:
   ```sh
   npm run install-dist
   ```

### Running Tests

```sh
# 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](https://developers.circle.com/w3s/docs/entity-secret-management)

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

```python
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.

```python
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][convencomms] format for all commits when creating a contributing pull request for this repo.

[convencomms]: https://www.conventionalcommits.org/en/v1.0.0/
