# ContextCol SDK
A comprehensive Python SDK for Binance trading with ContextCol API integration. This SDK provides seamless integration between Binance spot trading and ContextCol's trading bot analytics platform.
## Features
- **Binance Integration**: Complete Binance API wrapper with spot trading capabilities
- **Market Data API**: Comprehensive market data endpoints using requests directly
- **ContextCol API**: Full integration with ContextCol's trading bot activity tracking
- **Secure Configuration**: Environment-based configuration with validation
- **Comprehensive Error Handling**: Custom exceptions for different error scenarios
- **Type Hints**: Full type annotation support for better IDE experience
- **No External Dependencies**: Uses requests directly instead of outdated binance library
## Installation
```bash
pip install contextcol
```
## Quick Start
### Basic Setup
```python
from contextcol import ContextColClient
# Initialize with environment variables
client = ContextColClient()
# Or initialize with direct configuration
client = ContextColClient(
binance_api_key="your_binance_api_key",
binance_api_secret="your_binance_api_secret",
contextcol_api_key="your_contextcol_api_key"
)
```
### Environment Variables
Create a `.env` file in your project root:
```env
BINANCE_API_KEY=your_binance_api_key
BINANCE_API_SECRET=your_binance_api_secret
BINANCE_TESTNET=false
CONTEXTCOL_API_KEY=your_contextcol_api_key
CONTEXTCOL_BASE_URL=https://api.contextcol.com
```
### Simple Trading Example
```python
from contextcol import ContextColClient
# Initialize client
client = ContextColClient()
# Execute a spot trade and log to ContextCol
result = client.execute_spot_trade(
symbol="BTCUSDT",
side="BUY",
quantity="0.001",
type="MARKET",
test=True # Use test mode first
)
print(f"Order result: {result['binance_order']}")
print(f"ContextCol log: {result['contextcol_log']}")
```
## API Reference
### ContextColClient
The main client class that provides access to all SDK functionality.
#### Trading Methods
```python
# Execute spot trade with ContextCol logging
client.execute_spot_trade(symbol, side, quantity, type="MARKET", price=None, test=False)
# Create trading bot activity
client.create_trading_bot_activity(activity_data)
# Test trading bot activity
client.test_trading_bot_activity(activity_id, test_data)
```
#### Binance Methods
```python
# Get account information
account_info = client.binance.get_account_info()
# Get account balance
balance = client.binance.get_balance("BTC")
# Create spot order
order = client.binance.create_spot_order("BTCUSDT", "BUY", "0.001")
# Get ticker price
price = client.binance.get_ticker_price("BTCUSDT")
```
#### Market Data Methods
```python
# Access market data client
market_data = client.binance.market_data
# Get order book
order_book = market_data.get_order_book("BTCUSDT", limit=100)
# Get recent trades
trades = market_data.get_recent_trades("BTCUSDT", limit=500)
# Get historical trades
historical_trades = market_data.get_historical_trades("BTCUSDT", limit=500)
# Get aggregate trades
agg_trades = market_data.get_aggregate_trades("BTCUSDT", limit=500)
# Get klines (candlestick data)
klines = market_data.get_klines("BTCUSDT", "1h", limit=100)
# Get UI klines (optimized for charts)
ui_klines = market_data.get_ui_klines("BTCUSDT", "1h", limit=100)
# Get average price
avg_price = market_data.get_avg_price("BTCUSDT")
# Get 24hr ticker statistics
ticker_24hr = market_data.get_24hr_ticker("BTCUSDT")
# Get trading day ticker
trading_day_ticker = market_data.get_trading_day_ticker("BTCUSDT")
# Get symbol price ticker
price_ticker = market_data.get_symbol_price_ticker("BTCUSDT")
# Get order book ticker
book_ticker = market_data.get_order_book_ticker("BTCUSDT")
# Get rolling window ticker
rolling_ticker = market_data.get_rolling_window_ticker("BTCUSDT", window_size="1d")
```
#### ContextCol API Methods
```python
# Create Binance spot transaction log
client.create_binance_spot_transaction(transaction_data)
# Test Binance spot transaction
client.test_binance_spot_transaction(transaction_data)
# Get trading analytics
analytics = client.get_trading_analytics(start_date="2024-01-01", end_date="2024-01-31")
```
## Configuration
### Config Class
```python
from contextcol import Config
# Create configuration
config = Config(
binance_api_key="your_key",
binance_api_secret="your_secret",
contextcol_api_key="your_contextcol_key",
binance_testnet=True, # Use testnet
timeout=30,
max_retries=3
)
# Initialize client with config
client = ContextColClient(config=config)
```
### Configuration Options
| Parameter | Type | Default | Description |
| --------------------- | ---- | -------------------------- | -------------------------- |
| `binance_api_key` | str | None | Binance API key |
| `binance_api_secret` | str | None | Binance API secret |
| `binance_testnet` | bool | False | Use Binance testnet |
| `contextcol_api_key` | str | None | ContextCol API key |
| `contextcol_base_url` | str | https://api.contextcol.com | ContextCol API base URL |
| `timeout` | int | 30 | Request timeout in seconds |
| `max_retries` | int | 3 | Maximum retry attempts |
## Error Handling
The SDK provides comprehensive error handling with custom exceptions:
```python
from contextcol_binance_spot_sdk.exceptions import (
ContextColError,
APIError,
ConfigError,
BinanceAPIError,
AuthenticationError,
ValidationError
)
try:
result = client.execute_spot_trade("BTCUSDT", "BUY", "0.001")
except BinanceAPIError as e:
print(f"Binance API error: {e.message} (Code: {e.code})")
except APIError as e:
print(f"ContextCol API error: {e} (Status: {e.status_code})")
except ValidationError as e:
print(f"Validation error: {e}")
```
## Advanced Usage
### Context Manager
```python
with ContextColClient() as client:
# Your trading logic here
result = client.execute_spot_trade("BTCUSDT", "BUY", "0.001")
print(result)
# Client connections are automatically closed
```
### Validate Configuration
```python
client = ContextColClient()
validation_result = client.validate_configuration()
if validation_result['binance_connection']:
print("Binance connection successful")
if validation_result['contextcol_connection']:
print("ContextCol connection successful")
for error in validation_result['errors']:
print(f"Error: {error}")
```
### Get Account Summary
```python
summary = client.get_account_summary()
print(f"Binance Account: {summary['binance_account']}")
print(f"ContextCol User: {summary['contextcol_user']}")
print(f"Recent Activities: {summary['recent_activities']}")
```
## ContextCol API Endpoints
The SDK supports all major ContextCol API endpoints:
- `POST /trading-bot-activity` - Create trading bot activity
- `POST /trading-bot-activity/:id/test` - Test trading bot activity
- `POST /binance/spot/transaction` - Create Binance spot transaction
- `POST /binance/spot/transaction/test` - Test Binance spot transaction
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
For support, please contact [khemmapich@gmail.com](mailto:khemmapich@gmail.com) or create an issue on GitHub.
## Changelog
### 0.1.0
- Initial release
- Binance API integration
- ContextCol API integration
- Comprehensive error handling
- Type hints support
- Configuration management
Raw data
{
"_id": null,
"home_page": null,
"name": "contextcol-binance-spot-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "binance, trading, api, contextcol, cryptocurrency, binance, spot",
"author": "khemmapich",
"author_email": "khemmapich@contextcol.com",
"download_url": "https://files.pythonhosted.org/packages/62/67/9545449f81535b07e8dae13be7b558f446d527b4567d81562e7f79747cc8/contextcol_binance_spot_sdk-0.1.11.tar.gz",
"platform": null,
"description": "# ContextCol SDK\n\nA comprehensive Python SDK for Binance trading with ContextCol API integration. This SDK provides seamless integration between Binance spot trading and ContextCol's trading bot analytics platform.\n\n## Features\n\n- **Binance Integration**: Complete Binance API wrapper with spot trading capabilities\n- **Market Data API**: Comprehensive market data endpoints using requests directly\n- **ContextCol API**: Full integration with ContextCol's trading bot activity tracking\n- **Secure Configuration**: Environment-based configuration with validation\n- **Comprehensive Error Handling**: Custom exceptions for different error scenarios\n- **Type Hints**: Full type annotation support for better IDE experience\n- **No External Dependencies**: Uses requests directly instead of outdated binance library\n\n## Installation\n\n```bash\npip install contextcol\n```\n\n## Quick Start\n\n### Basic Setup\n\n```python\nfrom contextcol import ContextColClient\n\n# Initialize with environment variables\nclient = ContextColClient()\n\n# Or initialize with direct configuration\nclient = ContextColClient(\n binance_api_key=\"your_binance_api_key\",\n binance_api_secret=\"your_binance_api_secret\",\n contextcol_api_key=\"your_contextcol_api_key\"\n)\n```\n\n### Environment Variables\n\nCreate a `.env` file in your project root:\n\n```env\nBINANCE_API_KEY=your_binance_api_key\nBINANCE_API_SECRET=your_binance_api_secret\nBINANCE_TESTNET=false\nCONTEXTCOL_API_KEY=your_contextcol_api_key\nCONTEXTCOL_BASE_URL=https://api.contextcol.com\n```\n\n### Simple Trading Example\n\n```python\nfrom contextcol import ContextColClient\n\n# Initialize client\nclient = ContextColClient()\n\n# Execute a spot trade and log to ContextCol\nresult = client.execute_spot_trade(\n symbol=\"BTCUSDT\",\n side=\"BUY\",\n quantity=\"0.001\",\n type=\"MARKET\",\n test=True # Use test mode first\n)\n\nprint(f\"Order result: {result['binance_order']}\")\nprint(f\"ContextCol log: {result['contextcol_log']}\")\n```\n\n## API Reference\n\n### ContextColClient\n\nThe main client class that provides access to all SDK functionality.\n\n#### Trading Methods\n\n```python\n# Execute spot trade with ContextCol logging\nclient.execute_spot_trade(symbol, side, quantity, type=\"MARKET\", price=None, test=False)\n\n# Create trading bot activity\nclient.create_trading_bot_activity(activity_data)\n\n# Test trading bot activity\nclient.test_trading_bot_activity(activity_id, test_data)\n```\n\n#### Binance Methods\n\n```python\n# Get account information\naccount_info = client.binance.get_account_info()\n\n# Get account balance\nbalance = client.binance.get_balance(\"BTC\")\n\n# Create spot order\norder = client.binance.create_spot_order(\"BTCUSDT\", \"BUY\", \"0.001\")\n\n# Get ticker price\nprice = client.binance.get_ticker_price(\"BTCUSDT\")\n```\n\n#### Market Data Methods\n\n```python\n# Access market data client\nmarket_data = client.binance.market_data\n\n# Get order book\norder_book = market_data.get_order_book(\"BTCUSDT\", limit=100)\n\n# Get recent trades\ntrades = market_data.get_recent_trades(\"BTCUSDT\", limit=500)\n\n# Get historical trades\nhistorical_trades = market_data.get_historical_trades(\"BTCUSDT\", limit=500)\n\n# Get aggregate trades\nagg_trades = market_data.get_aggregate_trades(\"BTCUSDT\", limit=500)\n\n# Get klines (candlestick data)\nklines = market_data.get_klines(\"BTCUSDT\", \"1h\", limit=100)\n\n# Get UI klines (optimized for charts)\nui_klines = market_data.get_ui_klines(\"BTCUSDT\", \"1h\", limit=100)\n\n# Get average price\navg_price = market_data.get_avg_price(\"BTCUSDT\")\n\n# Get 24hr ticker statistics\nticker_24hr = market_data.get_24hr_ticker(\"BTCUSDT\")\n\n# Get trading day ticker\ntrading_day_ticker = market_data.get_trading_day_ticker(\"BTCUSDT\")\n\n# Get symbol price ticker\nprice_ticker = market_data.get_symbol_price_ticker(\"BTCUSDT\")\n\n# Get order book ticker\nbook_ticker = market_data.get_order_book_ticker(\"BTCUSDT\")\n\n# Get rolling window ticker\nrolling_ticker = market_data.get_rolling_window_ticker(\"BTCUSDT\", window_size=\"1d\")\n```\n\n#### ContextCol API Methods\n\n```python\n# Create Binance spot transaction log\nclient.create_binance_spot_transaction(transaction_data)\n\n# Test Binance spot transaction\nclient.test_binance_spot_transaction(transaction_data)\n\n# Get trading analytics\nanalytics = client.get_trading_analytics(start_date=\"2024-01-01\", end_date=\"2024-01-31\")\n```\n\n## Configuration\n\n### Config Class\n\n```python\nfrom contextcol import Config\n\n# Create configuration\nconfig = Config(\n binance_api_key=\"your_key\",\n binance_api_secret=\"your_secret\",\n contextcol_api_key=\"your_contextcol_key\",\n binance_testnet=True, # Use testnet\n timeout=30,\n max_retries=3\n)\n\n# Initialize client with config\nclient = ContextColClient(config=config)\n```\n\n### Configuration Options\n\n| Parameter | Type | Default | Description |\n| --------------------- | ---- | -------------------------- | -------------------------- |\n| `binance_api_key` | str | None | Binance API key |\n| `binance_api_secret` | str | None | Binance API secret |\n| `binance_testnet` | bool | False | Use Binance testnet |\n| `contextcol_api_key` | str | None | ContextCol API key |\n| `contextcol_base_url` | str | https://api.contextcol.com | ContextCol API base URL |\n| `timeout` | int | 30 | Request timeout in seconds |\n| `max_retries` | int | 3 | Maximum retry attempts |\n\n## Error Handling\n\nThe SDK provides comprehensive error handling with custom exceptions:\n\n```python\nfrom contextcol_binance_spot_sdk.exceptions import (\n ContextColError,\n APIError,\n ConfigError,\n BinanceAPIError,\n AuthenticationError,\n ValidationError\n)\n\ntry:\n result = client.execute_spot_trade(\"BTCUSDT\", \"BUY\", \"0.001\")\nexcept BinanceAPIError as e:\n print(f\"Binance API error: {e.message} (Code: {e.code})\")\nexcept APIError as e:\n print(f\"ContextCol API error: {e} (Status: {e.status_code})\")\nexcept ValidationError as e:\n print(f\"Validation error: {e}\")\n```\n\n## Advanced Usage\n\n### Context Manager\n\n```python\nwith ContextColClient() as client:\n # Your trading logic here\n result = client.execute_spot_trade(\"BTCUSDT\", \"BUY\", \"0.001\")\n print(result)\n# Client connections are automatically closed\n```\n\n### Validate Configuration\n\n```python\nclient = ContextColClient()\nvalidation_result = client.validate_configuration()\n\nif validation_result['binance_connection']:\n print(\"Binance connection successful\")\nif validation_result['contextcol_connection']:\n print(\"ContextCol connection successful\")\n\nfor error in validation_result['errors']:\n print(f\"Error: {error}\")\n```\n\n### Get Account Summary\n\n```python\nsummary = client.get_account_summary()\nprint(f\"Binance Account: {summary['binance_account']}\")\nprint(f\"ContextCol User: {summary['contextcol_user']}\")\nprint(f\"Recent Activities: {summary['recent_activities']}\")\n```\n\n## ContextCol API Endpoints\n\nThe SDK supports all major ContextCol API endpoints:\n\n- `POST /trading-bot-activity` - Create trading bot activity\n- `POST /trading-bot-activity/:id/test` - Test trading bot activity\n- `POST /binance/spot/transaction` - Create Binance spot transaction\n- `POST /binance/spot/transaction/test` - Test Binance spot transaction\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor support, please contact [khemmapich@gmail.com](mailto:khemmapich@gmail.com) or create an issue on GitHub.\n\n## Changelog\n\n### 0.1.0\n\n- Initial release\n- Binance API integration\n- ContextCol API integration\n- Comprehensive error handling\n- Type hints support\n- Configuration management\n",
"bugtrack_url": null,
"license": null,
"summary": "Python SDK for Binance trading with ContextCol API integration",
"version": "0.1.11",
"project_urls": {
"Bug Tracker": "https://github.com/khemmapichpanyana/contextcol-binance-spot-sdk/issues",
"Documentation": "https://github.com/khemmapichpanyana/contextcol-binance-spot-sdk",
"Homepage": "https://github.com/khemmapichpanyana/contextcol-binance-spot-sdk",
"Repository": "https://github.com/khemmapichpanyana/contextcol-binance-spot-sdk"
},
"split_keywords": [
"binance",
" trading",
" api",
" contextcol",
" cryptocurrency",
" binance",
" spot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8dc2fb0806b5e236668bc87632c6b0678ad1ef7b2bd76d888cc51ea04dca6935",
"md5": "60e15d1fab54a92938d75685ea78adf9",
"sha256": "36aa7a8868475a21c747451b54d3e47a36eb18c5994ae222267149d11e9c124d"
},
"downloads": -1,
"filename": "contextcol_binance_spot_sdk-0.1.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60e15d1fab54a92938d75685ea78adf9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 21569,
"upload_time": "2025-08-04T05:23:43",
"upload_time_iso_8601": "2025-08-04T05:23:43.406890Z",
"url": "https://files.pythonhosted.org/packages/8d/c2/fb0806b5e236668bc87632c6b0678ad1ef7b2bd76d888cc51ea04dca6935/contextcol_binance_spot_sdk-0.1.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "62679545449f81535b07e8dae13be7b558f446d527b4567d81562e7f79747cc8",
"md5": "6daf6e631ae8a932a8422c337cb671f6",
"sha256": "5e846ccc4759539bda1f5e322d365eb44855a9f83c40e1e366daa30594803934"
},
"downloads": -1,
"filename": "contextcol_binance_spot_sdk-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "6daf6e631ae8a932a8422c337cb671f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 19010,
"upload_time": "2025-08-04T05:23:44",
"upload_time_iso_8601": "2025-08-04T05:23:44.864657Z",
"url": "https://files.pythonhosted.org/packages/62/67/9545449f81535b07e8dae13be7b558f446d527b4567d81562e7f79747cc8/contextcol_binance_spot_sdk-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 05:23:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "khemmapichpanyana",
"github_project": "contextcol-binance-spot-sdk",
"github_not_found": true,
"lcname": "contextcol-binance-spot-sdk"
}
JSON
