cdp-sdk 0.12.0__tar.gz

cdp_sdk-0.12.0/LICENSE.md

@@ -0,0 +1,15 @@
+Apache-2.0 License
+
+Copyright 2024 Coinbase
+    
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

cdp_sdk-0.12.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.1
+Name: cdp-sdk
+Version: 0.12.0
+Summary: CDP Python SDK
+License: LICENSE.md
+Author: John Peterson
+Author-email: john.peterson@coinbase.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+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-Dist: bip-utils (>=2.9.3,<3.0.0)
+Requires-Dist: coincurve (>=20.0.0,<21.0.0)
+Requires-Dist: cryptography (>=44.0.0,<45.0.0)
+Requires-Dist: pydantic (>=2.10.3,<3.0.0)
+Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
+Requires-Dist: urllib3 (>=2.2.3,<3.0.0)
+Requires-Dist: web3 (>=7.6.0,<8.0.0)
+Description-Content-Type: text/markdown
+
+# CDP Python SDK
+
+The CDP Python SDK enables the simple integration of crypto into your app.
+By calling Coinbase's CDP APIs, the SDK allows you to provision crypto wallets,
+send crypto into/out of those wallets, track wallet balances, and trade crypto from
+one asset into another.
+
+**CDP SDK v0 is a pre-alpha release, which means that the APIs and SDK methods are subject to change. We will continuously release updates to support new capabilities and improve the developer experience.**
+
+## Documentation
+
+- [CDP API Documentation](https://docs.cdp.coinbase.com/platform-apis/docs/welcome)
+- [CDP SDK Python Documentation](https://coinbase.github.io/cdp-sdk-python/)
+
+## Requirements
+
+- Python 3.10+
+- Poetry for package management and tooling
+  - [Poetry Installation Instructions](https://python-poetry.org/docs/#installation)
+
+### Checking Python Version
+
+Before using the SDK, ensure that you have the correct version of Python installed. The SDK requires Python 3.10 or higher. You can check your Python version by running the following code:
+
+```bash
+python --version
+pip --version
+```
+
+If you need to upgrade your Python version, you can download and install the latest version of Python from the [official Python website](https://www.python.org/downloads/).
+For `pip`, refer to the [official pip documentation](https://pip.pypa.io/en/stable/installation/) for installation instructions.
+
+## Installation
+
+```bash
+pip install cdp-sdk
+```
+
+if you prefer to manage dependencies with Poetry:
+```bash
+poetry add cdp-sdk
+```
+
+### Starting a Python REPL
+
+To start a Python REPL:
+
+```bash
+python
+```
+
+## Quickstart
+
+### Creating a Wallet
+
+To start, [create a CDP API key](https://portal.cdp.coinbase.com/access/api). Then, initialize the CDP SDK by passing your API key name and API key's private key via the `configure` method:
+
+```python
+from cdp import *
+
+api_key_name = "Copy your API key name here."
+
+api_key_private_key = "Copy your API key's private key here."
+
+Cdp.configure(api_key_name, api_key_private_key)
+
+print("CDP SDK has been successfully configured with CDP API key.")
+```
+
+Another way to initialize the SDK is by sourcing the API key from the JSON file that contains your API key,
+downloaded from the CDP portal.
+
+```python
+Cdp.configure_from_json("~/Downloads/cdp_api_key.json")
+
+print("CDP SDK has been successfully configured from JSON file.")
+```
+
+This will allow you to authenticate with the Platform APIs.
+
+If you are using a CDP [Server-Signer](https://docs.cdp.coinbase.com/mpc-wallet/docs/serversigners) to manage your private keys, enable it with
+
+```python
+Cdp.use_server_signer = True
+```
+
+Now create a wallet. Wallets are created with a single default address.
+
+```python
+# Create a wallet with one address by default.
+wallet1 = Wallet.create()
+
+print(f"Wallet successfully created: {wallet1}")
+```
+
+Wallets come with a single default address, accessible via `default_address`:
+
+```python
+# A wallet has a default address.
+address = wallet1.default_address
+```
+
+### Funding a Wallet
+
+Wallets do not have funds on them to start. For Base Sepolia testnet, we provide a `faucet` method to fund your wallet with
+testnet ETH. You are allowed one faucet claim per 24-hour window.
+
+```python
+# Fund the wallet with a faucet transaction.
+faucet_tx = wallet1.faucet()
+
+# Wait for the faucet transaction to complete.
+faucet_tx.wait()
+
+print(f"Faucet transaction successfully completed: {faucet_tx}")
+```
+
+### Transferring Funds
+
+See [Transfers](https://docs.cdp.coinbase.com/wallets/docs/transfers) for more information.
+
+Now that your faucet transaction has successfully completed, you can send the funds in your wallet to another wallet.
+The code below creates another wallet, and uses the `transfer` function to send testnet ETH from the first wallet to
+the second:
+
+```python
+# Create a new wallet wallet2 to transfer funds to.
+wallet2 = Wallet.create()
+
+print(f"Wallet successfully created: {wallet2}")
+
+transfer = wallet1.transfer(0.00001, "eth", wallet2).wait()
+
+print(f"Transfer successfully completed: {transfer}")
+```
+
+#### Gasless USDC Transfers
+
+To transfer USDC without needing to hold ETH for gas, you can use the `transfer` method with the `gasless` option set to `True`.
+
+```python
+# Create a new wallet wallet3 to transfer funds to.
+wallet3 = Wallet.create()
+
+print(f"Wallet successfully created: {wallet3}")
+
+# Fund the wallet with USDC with a faucet transaction.
+usdc_faucet_tx = wallet1.faucet("usdc")
+
+# Wait for the faucet transaction to complete.
+usdc_faucet_tx.wait()
+
+print(f"Faucet transaction successfully completed: {usdc_faucet_tx}")
+
+transfer = wallet1.transfer(0.00001, "usdc", wallet3, gasless=True).wait()
+```
+
+### Listing Transfers
+
+```python
+# Return list of all transfers. This will paginate and fetch all transfers for the address.
+list(address.transfers())
+```
+
+### Trading Funds
+
+See [Trades](https://docs.cdp.coinbase.com/wallets/docs/trades) for more information.
+
+```python
+wallet = Wallet.create("base-mainnet")
+
+print(f"Wallet successfully created: {wallet}")
+print(f"Send `base-mainnet` ETH to wallets default address: {wallet.default_address.address_id}")
+
+trade = wallet.trade(0.00001, "eth", "usdc").wait()
+
+print(f"Trade successfully completed: {trade}")
+```
+
+### Listing Trades
+
+```python
+# Return list of all trades. This will paginate and fetch all trades for the address.
+list(address.trades())
+```
+
+### Re-Instantiating Wallets
+
+The SDK creates wallets with [Developer-Managed (1-1)](https://docs.cdp.coinbase.com/mpc-wallet/docs/wallets#developer-managed-wallets) keys by default, which means you are responsible for securely storing the keys required to re-instantiate wallets. The below code walks you through how to export a wallet and store it in a secure location.
+
+```python
+# Export the data required to re-instantiate the wallet. The data contains the seed and the ID of the wallet.
+data = wallet.export_data()
+```
+
+In order to persist the data for the wallet, you will need to implement a store method to store the data export in a secure location. If you do not store the wallet in a secure location you will lose access to the wallet and all of the funds on it.
+
+```python
+# You should implement the "store" method to securely persist the data object,
+# which is required to re-instantiate the wallet at a later time. For ease of use,
+# the data object is converted to a dictionary first.
+store(data.to_dict())
+```
+
+For convenience during testing, we provide a `save_seed` method that stores the wallet's seed in your local file system. This is an insecure method of storing wallet seeds and should only be used for development purposes.
+
+To encrypt the saved data, set encrypt to `True`. Note that your CDP API key also serves as the encryption key for the data persisted locally. To re-instantiate wallets with encrypted data, ensure that your SDK is configured with the same API key when invoking `save_seed` and `load_seed`.
+
+```python
+# Pick a file to which to save your wallet seed.
+file_path = "my_seed.json"
+
+# Set encrypt=True to encrypt the wallet seed with your CDP secret API key.
+wallet.save_seed(file_path, encrypt=True)
+
+print(f"Seed for wallet {wallet.id} successfully saved to {file_path}.")
+```
+
+The below code demonstrates how to re-instantiate a wallet from the data export.
+
+```python
+# You should implement the "fetch" method to retrieve the securely persisted data object,
+# keyed by the wallet ID.
+fetched_data = fetch(wallet.id)
+
+# imported_wallet will be equivalent to wallet.
+imported_wallet = Wallet.import_data(fetched_data)
+```
+
+To import Wallets that were persisted to your local file system using `save_seed`, use the below code.
+
+```python
+# Get the unhydrated wallet from the server.
+fetched_wallet = Wallet.fetch(wallet.id)
+
+# You can now load the seed into the wallet from the local file.
+# fetched_wallet will be equivalent to imported_wallet.
+fetched_wallet.load_seed(file_path)
+```
+
+### Creating a Webhook
+A webhook is a way to provide other applications with real-time information from the blockchain. When an event occurs on a blockchain address, it can send a POST request to a URL you specify. You can create a webhook to receive notifications about events that occur in your wallet or crypto address, such as when a user makes a transfer.
+```python
+from cdp.client.models.webhook import WebhookEventType
+from cdp.client.models.webhook import WebhookEventFilter
+
+wh1 = Webhook.create(
+    notification_uri="https://your-app.com/callback",
+    event_type=WebhookEventType.ERC20_TRANSFER,
+    event_filters=[WebhookEventFilter(from_address="0x71d4d7d5e9ce0f41e6a68bd3a9b43aa597dc0eb0")]
+)
+print(wh1)
+```
+
+### Creating a Webhook On A Wallet
+A webhook can be attached to an existing wallet to monitor events that occur on the wallet, i.e. all addresses associated with this wallet. A list of supported blockchain events can be found [here](https://docs.cdp.coinbase.com/get-started/docs/webhooks/event-types).
+```python
+import cdp
+
+wallet1 = Wallet.create()
+wh1 = wallet1.create_webhook("https://your-app.com/callback")
+print(wh1)
+```
+
+## Examples
+Examples, demo apps, and further code samples can be found in the [CDP SDK Python Documentation](https://docs.cdp.coinbase.com/cdp-apis/docs/welcome).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
+
+

cdp_sdk-0.12.0/README.md

@@ -0,0 +1,271 @@
+# CDP Python SDK
+
+The CDP Python SDK enables the simple integration of crypto into your app.
+By calling Coinbase's CDP APIs, the SDK allows you to provision crypto wallets,
+send crypto into/out of those wallets, track wallet balances, and trade crypto from
+one asset into another.
+
+**CDP SDK v0 is a pre-alpha release, which means that the APIs and SDK methods are subject to change. We will continuously release updates to support new capabilities and improve the developer experience.**
+
+## Documentation
+
+- [CDP API Documentation](https://docs.cdp.coinbase.com/platform-apis/docs/welcome)
+- [CDP SDK Python Documentation](https://coinbase.github.io/cdp-sdk-python/)
+
+## Requirements
+
+- Python 3.10+
+- Poetry for package management and tooling
+  - [Poetry Installation Instructions](https://python-poetry.org/docs/#installation)
+
+### Checking Python Version
+
+Before using the SDK, ensure that you have the correct version of Python installed. The SDK requires Python 3.10 or higher. You can check your Python version by running the following code:
+
+```bash
+python --version
+pip --version
+```
+
+If you need to upgrade your Python version, you can download and install the latest version of Python from the [official Python website](https://www.python.org/downloads/).
+For `pip`, refer to the [official pip documentation](https://pip.pypa.io/en/stable/installation/) for installation instructions.
+
+## Installation
+
+```bash
+pip install cdp-sdk
+```
+
+if you prefer to manage dependencies with Poetry:
+```bash
+poetry add cdp-sdk
+```
+
+### Starting a Python REPL
+
+To start a Python REPL:
+
+```bash
+python
+```
+
+## Quickstart
+
+### Creating a Wallet
+
+To start, [create a CDP API key](https://portal.cdp.coinbase.com/access/api). Then, initialize the CDP SDK by passing your API key name and API key's private key via the `configure` method:
+
+```python
+from cdp import *
+
+api_key_name = "Copy your API key name here."
+
+api_key_private_key = "Copy your API key's private key here."
+
+Cdp.configure(api_key_name, api_key_private_key)
+
+print("CDP SDK has been successfully configured with CDP API key.")
+```
+
+Another way to initialize the SDK is by sourcing the API key from the JSON file that contains your API key,
+downloaded from the CDP portal.
+
+```python
+Cdp.configure_from_json("~/Downloads/cdp_api_key.json")
+
+print("CDP SDK has been successfully configured from JSON file.")
+```
+
+This will allow you to authenticate with the Platform APIs.
+
+If you are using a CDP [Server-Signer](https://docs.cdp.coinbase.com/mpc-wallet/docs/serversigners) to manage your private keys, enable it with
+
+```python
+Cdp.use_server_signer = True
+```
+
+Now create a wallet. Wallets are created with a single default address.
+
+```python
+# Create a wallet with one address by default.
+wallet1 = Wallet.create()
+
+print(f"Wallet successfully created: {wallet1}")
+```
+
+Wallets come with a single default address, accessible via `default_address`:
+
+```python
+# A wallet has a default address.
+address = wallet1.default_address
+```
+
+### Funding a Wallet
+
+Wallets do not have funds on them to start. For Base Sepolia testnet, we provide a `faucet` method to fund your wallet with
+testnet ETH. You are allowed one faucet claim per 24-hour window.
+
+```python
+# Fund the wallet with a faucet transaction.
+faucet_tx = wallet1.faucet()
+
+# Wait for the faucet transaction to complete.
+faucet_tx.wait()
+
+print(f"Faucet transaction successfully completed: {faucet_tx}")
+```
+
+### Transferring Funds
+
+See [Transfers](https://docs.cdp.coinbase.com/wallets/docs/transfers) for more information.
+
+Now that your faucet transaction has successfully completed, you can send the funds in your wallet to another wallet.
+The code below creates another wallet, and uses the `transfer` function to send testnet ETH from the first wallet to
+the second:
+
+```python
+# Create a new wallet wallet2 to transfer funds to.
+wallet2 = Wallet.create()
+
+print(f"Wallet successfully created: {wallet2}")
+
+transfer = wallet1.transfer(0.00001, "eth", wallet2).wait()
+
+print(f"Transfer successfully completed: {transfer}")
+```
+
+#### Gasless USDC Transfers
+
+To transfer USDC without needing to hold ETH for gas, you can use the `transfer` method with the `gasless` option set to `True`.
+
+```python
+# Create a new wallet wallet3 to transfer funds to.
+wallet3 = Wallet.create()
+
+print(f"Wallet successfully created: {wallet3}")
+
+# Fund the wallet with USDC with a faucet transaction.
+usdc_faucet_tx = wallet1.faucet("usdc")
+
+# Wait for the faucet transaction to complete.
+usdc_faucet_tx.wait()
+
+print(f"Faucet transaction successfully completed: {usdc_faucet_tx}")
+
+transfer = wallet1.transfer(0.00001, "usdc", wallet3, gasless=True).wait()
+```
+
+### Listing Transfers
+
+```python
+# Return list of all transfers. This will paginate and fetch all transfers for the address.
+list(address.transfers())
+```
+
+### Trading Funds
+
+See [Trades](https://docs.cdp.coinbase.com/wallets/docs/trades) for more information.
+
+```python
+wallet = Wallet.create("base-mainnet")
+
+print(f"Wallet successfully created: {wallet}")
+print(f"Send `base-mainnet` ETH to wallets default address: {wallet.default_address.address_id}")
+
+trade = wallet.trade(0.00001, "eth", "usdc").wait()
+
+print(f"Trade successfully completed: {trade}")
+```
+
+### Listing Trades
+
+```python
+# Return list of all trades. This will paginate and fetch all trades for the address.
+list(address.trades())
+```
+
+### Re-Instantiating Wallets
+
+The SDK creates wallets with [Developer-Managed (1-1)](https://docs.cdp.coinbase.com/mpc-wallet/docs/wallets#developer-managed-wallets) keys by default, which means you are responsible for securely storing the keys required to re-instantiate wallets. The below code walks you through how to export a wallet and store it in a secure location.
+
+```python
+# Export the data required to re-instantiate the wallet. The data contains the seed and the ID of the wallet.
+data = wallet.export_data()
+```
+
+In order to persist the data for the wallet, you will need to implement a store method to store the data export in a secure location. If you do not store the wallet in a secure location you will lose access to the wallet and all of the funds on it.
+
+```python
+# You should implement the "store" method to securely persist the data object,
+# which is required to re-instantiate the wallet at a later time. For ease of use,
+# the data object is converted to a dictionary first.
+store(data.to_dict())
+```
+
+For convenience during testing, we provide a `save_seed` method that stores the wallet's seed in your local file system. This is an insecure method of storing wallet seeds and should only be used for development purposes.
+
+To encrypt the saved data, set encrypt to `True`. Note that your CDP API key also serves as the encryption key for the data persisted locally. To re-instantiate wallets with encrypted data, ensure that your SDK is configured with the same API key when invoking `save_seed` and `load_seed`.
+
+```python
+# Pick a file to which to save your wallet seed.
+file_path = "my_seed.json"
+
+# Set encrypt=True to encrypt the wallet seed with your CDP secret API key.
+wallet.save_seed(file_path, encrypt=True)
+
+print(f"Seed for wallet {wallet.id} successfully saved to {file_path}.")
+```
+
+The below code demonstrates how to re-instantiate a wallet from the data export.
+
+```python
+# You should implement the "fetch" method to retrieve the securely persisted data object,
+# keyed by the wallet ID.
+fetched_data = fetch(wallet.id)
+
+# imported_wallet will be equivalent to wallet.
+imported_wallet = Wallet.import_data(fetched_data)
+```
+
+To import Wallets that were persisted to your local file system using `save_seed`, use the below code.
+
+```python
+# Get the unhydrated wallet from the server.
+fetched_wallet = Wallet.fetch(wallet.id)
+
+# You can now load the seed into the wallet from the local file.
+# fetched_wallet will be equivalent to imported_wallet.
+fetched_wallet.load_seed(file_path)
+```
+
+### Creating a Webhook
+A webhook is a way to provide other applications with real-time information from the blockchain. When an event occurs on a blockchain address, it can send a POST request to a URL you specify. You can create a webhook to receive notifications about events that occur in your wallet or crypto address, such as when a user makes a transfer.
+```python
+from cdp.client.models.webhook import WebhookEventType
+from cdp.client.models.webhook import WebhookEventFilter
+
+wh1 = Webhook.create(
+    notification_uri="https://your-app.com/callback",
+    event_type=WebhookEventType.ERC20_TRANSFER,
+    event_filters=[WebhookEventFilter(from_address="0x71d4d7d5e9ce0f41e6a68bd3a9b43aa597dc0eb0")]
+)
+print(wh1)
+```
+
+### Creating a Webhook On A Wallet
+A webhook can be attached to an existing wallet to monitor events that occur on the wallet, i.e. all addresses associated with this wallet. A list of supported blockchain events can be found [here](https://docs.cdp.coinbase.com/get-started/docs/webhooks/event-types).
+```python
+import cdp
+
+wallet1 = Wallet.create()
+wh1 = wallet1.create_webhook("https://your-app.com/callback")
+print(wh1)
+```
+
+## Examples
+Examples, demo apps, and further code samples can be found in the [CDP SDK Python Documentation](https://docs.cdp.coinbase.com/cdp-apis/docs/welcome).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
+

cdp_sdk-0.12.0/cdp/__init__.py

@@ -0,0 +1,42 @@
+from cdp.__version__ import __version__
+from cdp.address import Address
+from cdp.asset import Asset
+from cdp.balance import Balance
+from cdp.balance_map import BalanceMap
+from cdp.cdp import Cdp
+from cdp.contract_invocation import ContractInvocation
+from cdp.faucet_transaction import FaucetTransaction
+from cdp.hash_utils import hash_message, hash_typed_data_message
+from cdp.payload_signature import PayloadSignature
+from cdp.smart_contract import SmartContract
+from cdp.sponsored_send import SponsoredSend
+from cdp.trade import Trade
+from cdp.transaction import Transaction
+from cdp.transfer import Transfer
+from cdp.wallet import Wallet
+from cdp.wallet_address import WalletAddress
+from cdp.wallet_data import WalletData
+from cdp.webhook import Webhook
+
+__all__ = [
+    "__version__",
+    "Cdp",
+    "ContractInvocation",
+    "Wallet",
+    "WalletAddress",
+    "WalletData",
+    "Webhook",
+    "Asset",
+    "Transfer",
+    "Address",
+    "Transaction",
+    "Balance",
+    "BalanceMap",
+    "FaucetTransaction",
+    "Trade",
+    "SponsoredSend",
+    "PayloadSignature",
+    "SmartContract",
+    "hash_message",
+    "hash_typed_data_message",
+]

cdp_sdk-0.12.0/cdp/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.12.0"