# OpenOracle Python SDK
Intelligent Oracle Routing for Prediction Markets
[](https://badge.fury.io/py/openoracle)
[](https://pypi.org/project/openoracle/)
[](https://opensource.org/licenses/MIT)
## Overview
The OpenOracle Python SDK provides a comprehensive interface for building prediction markets with intelligent oracle selection and data verification. It automatically routes questions to the most appropriate oracle provider based on AI analysis, supports multiple blockchain networks, and includes built-in Twitter integration for social media prediction markets.
## Key Features
- 🤖 **AI-Powered Oracle Routing** - Automatically selects the best oracle for any question
- 🔗 **Multi-Oracle Support** - Chainlink, Pyth, UMA, Band Protocol, API3, and more
- 🐦 **Twitter Integration** - Create prediction markets from tweets
- ⛓️ **Cross-Chain Compatibility** - Ethereum, Polygon, Flow EVM, Arbitrum
- 🛡️ **Type Safety** - Full Pydantic validation for all data models
- ⚡ **Async/Await Support** - High-performance async operations
- 🔄 **Automatic Retries** - Robust error handling and retry logic
- 📊 **Real-time Data** - Live price feeds and market updates
## Installation
```bash
pip install openoracle
```
For development dependencies:
```bash
pip install openoracle[dev]
```
For all optional features:
```bash
pip install openoracle[all]
```
## Quick Start
### Basic Usage
```python
import asyncio
from openoracle import OpenOracleAPI
async def main():
# Initialize the API client
async with OpenOracleAPI() as api:
# Route a question to the best oracle
routing = await api.route_question(
"Will BTC exceed $100k by end of 2024?"
)
print(f"Selected Oracle: {routing.selected_oracle}")
print(f"Confidence: {routing.confidence_score}")
print(f"Reasoning: {routing.reasoning}")
# Get current BTC price
price = await api.get_price("BTC/USD")
print(f"Current BTC Price: ${price.price}")
# Create a prediction market
market = await api.create_prediction_market(
question="Will BTC exceed $100k by end of 2024?",
poll_id="btc-100k-2024"
)
print(f"Market created: {market['poll_id']}")
asyncio.run(main())
```
### Configuration
Configure the SDK using environment variables:
```bash
# Core API settings
export OPENORACLE_API_KEY="your-api-key"
export OPENORACLE_BASE_URL="https://api.openoracle.ai"
# AI routing (optional)
export OPENROUTER_API_KEY="your-openrouter-key"
export OPENAI_API_KEY="your-openai-key"
# Oracle provider settings
export CHAINLINK_API_KEY="your-chainlink-key"
export PYTH_ENDPOINT="https://hermes.pyth.network"
# Blockchain RPCs
export ETH_RPC_URL="https://eth.llamarpc.com"
export POLYGON_RPC_URL="https://polygon.llamarpc.com"
```
Or use a configuration object:
```python
from openoracle import OracleConfig, OpenOracleAPI
config = OracleConfig(
api_key="your-api-key",
base_url="https://api.openoracle.ai",
openrouter_api_key="your-openrouter-key",
enable_ai_routing=True
)
async with OpenOracleAPI(config) as api:
# Your code here
pass
```
### Twitter Integration
```python
from openoracle import OpenOracleAPI
async with OpenOracleAPI() as api:
# Analyze a tweet for prediction potential
analysis = await api.analyze_tweet(
tweet_text="I predict Tesla stock will hit $300 by Q2 2024",
author="@elonmusk"
)
print(f"Prediction detected: {analysis['has_prediction']}")
print(f"Suggested question: {analysis['suggested_question']}")
# Create market directly from tweet
market = await api.create_market_from_tweet(
tweet_text="I predict Tesla stock will hit $300 by Q2 2024",
poll_id="tesla-300-q2-2024",
author="@elonmusk"
)
```
### Oracle Provider Usage
```python
# Get price from specific oracle
chainlink_price = await api.get_price("ETH/USD", provider="chainlink")
pyth_price = await api.get_price("BTC/USD", provider="pyth")
# Get aggregated price from multiple oracles
aggregated_price = await api.get_price("ETH/USD") # Uses all available oracles
# Check oracle health
health = await api.get_oracle_health()
print(f"Chainlink status: {health['chainlink']['status']}")
# Get supported assets
assets = await api.get_supported_assets()
sports = await api.get_supported_sports()
```
### Advanced Features
```python
# Batch operations
questions = [
"Will BTC hit $100k in 2024?",
"Will ETH hit $10k in 2024?",
"Will DOGE hit $1 in 2024?"
]
routings = await api.batch_route_questions(questions)
prices = await api.batch_price_feeds(["BTC/USD", "ETH/USD", "DOGE/USD"])
# Real-time price monitoring
async def price_callback(price_data):
print(f"New price: {price_data.price}")
# This would use WebSocket connections in a real implementation
await api.subscribe_to_prices(["BTC/USD"], callback=price_callback)
```
## Core Components
### OracleRouter
The main routing engine that selects optimal oracles:
```python
from openoracle import OracleRouter, OracleConfig
config = OracleConfig.from_env()
router = OracleRouter(config)
routing = await router.route_poll_question(
"Will the Fed raise rates in March?",
category_hint="economic"
)
```
### Oracle Providers
Individual oracle provider interfaces:
```python
from openoracle.providers import ChainlinkProvider, PythProvider
# Direct provider usage
chainlink = ChainlinkProvider(rpc_url="https://eth.llamarpc.com")
price_feed = await chainlink.get_price_feed("ETH/USD")
pyth = PythProvider()
pyth_price = await pyth.get_price_feed("BTC/USD")
```
### Schema Validation
Type-safe data models using Pydantic:
```python
from openoracle.schemas import OracleRoutingRequest, OracleProvider
request = OracleRoutingRequest(
question="Will BTC hit $100k?",
category_hint="price",
max_cost_usd=10.0,
preferred_providers=[OracleProvider.CHAINLINK, OracleProvider.PYTH]
)
```
## Supported Oracle Providers
| Provider | Price Feeds | Sports | Weather | Events | Custom |
|----------|-------------|---------|---------|---------|---------|
| **Chainlink** | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Pyth Network** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **UMA Protocol** | ❌ | ❌ | ❌ | ✅ | ✅ |
| **Band Protocol** | ✅ | ❌ | ❌ | ❌ | ✅ |
| **API3** | ✅ | ❌ | ✅ | ❌ | ✅ |
## Supported Blockchains
- Ethereum Mainnet
- Polygon
- Flow EVM
- Arbitrum
- Avalanche
- Base
- Optimism
## Error Handling
The SDK provides comprehensive error handling:
```python
from openoracle.exceptions import (
RoutingError,
ProviderError,
ValidationError,
NetworkError
)
try:
routing = await api.route_question("Invalid question")
except RoutingError as e:
print(f"Routing failed: {e.message}")
print(f"Available providers: {e.available_providers}")
except ProviderError as e:
print(f"Provider {e.provider_name} failed: {e.provider_error}")
except ValidationError as e:
print(f"Validation failed: {e.field_name} = {e.field_value}")
```
## Testing
Run the test suite:
```bash
# Install dev dependencies
pip install -e .[dev]
# Run tests
pytest
# Run tests with coverage
pytest --cov=openoracle
# Run specific tests
pytest tests/test_routing.py
```
## Examples
See the `/examples` directory for complete examples:
- **basic_usage.py** - Getting started examples
- **twitter_integration.py** - Social media prediction markets
- **price_monitoring.py** - Real-time price feeds
- **custom_oracles.py** - Building custom oracle integrations
- **batch_operations.py** - Efficient batch processing
## API Reference
Complete API documentation is available at [docs.openoracle.ai](https://docs.openoracle.ai)
### Main Classes
- `OpenOracleAPI` - Main API client
- `OracleRouter` - Core routing engine
- `TwitterAnalyzer` - Social media integration
- `OracleConfig` - Configuration management
### Key Methods
- `route_question()` - Route questions to optimal oracles
- `get_price()` - Get asset prices
- `create_prediction_market()` - Create new markets
- `analyze_tweet()` - Analyze social media content
- `get_oracle_health()` - Check oracle status
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Development Setup
```bash
git clone https://github.com/openoracle/python-sdk
cd python-sdk
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .[dev]
# Install pre-commit hooks
pre-commit install
# Run tests
pytest
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Documentation**: [docs.openoracle.ai](https://docs.openoracle.ai)
- **Discord**: [discord.gg/openoracle](https://discord.gg/openoracle)
- **Twitter**: [@OpenOracleHQ](https://twitter.com/OpenOracleHQ)
- **Email**: [team@openoracle.ai](mailto:team@openoracle.ai)
## Roadmap
- [ ] Additional oracle providers (DIA, Tellor, Supra)
- [ ] GraphQL API support
- [ ] Advanced analytics and insights
- [ ] Mobile SDK (React Native)
- [ ] Telegram/Discord bot integration
- [ ] Governance token integration
- [ ] Cross-chain message passing
---
**Built with ❤️ by the OpenOracle Team**
Raw data
{
"_id": null,
"home_page": "https://github.com/openoracle/python-sdk",
"name": "openoracle",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "oracle, blockchain, prediction-markets, defi, chainlink, pyth, uma, api3, band-protocol, ai, routing, twitter, social-media",
"author": "OpenOracle Team",
"author_email": "OpenOracle Team <team@openoracle.ai>",
"download_url": "https://files.pythonhosted.org/packages/59/2e/8bacdd2853a7670ec06867f0df037385533cf19596e996886c17f65a3a9b/openoracle-0.1.0.tar.gz",
"platform": null,
"description": "# OpenOracle Python SDK\n\nIntelligent Oracle Routing for Prediction Markets\n\n[](https://badge.fury.io/py/openoracle)\n[](https://pypi.org/project/openoracle/)\n[](https://opensource.org/licenses/MIT)\n\n## Overview\n\nThe OpenOracle Python SDK provides a comprehensive interface for building prediction markets with intelligent oracle selection and data verification. It automatically routes questions to the most appropriate oracle provider based on AI analysis, supports multiple blockchain networks, and includes built-in Twitter integration for social media prediction markets.\n\n## Key Features\n\n- \ud83e\udd16 **AI-Powered Oracle Routing** - Automatically selects the best oracle for any question\n- \ud83d\udd17 **Multi-Oracle Support** - Chainlink, Pyth, UMA, Band Protocol, API3, and more\n- \ud83d\udc26 **Twitter Integration** - Create prediction markets from tweets\n- \u26d3\ufe0f **Cross-Chain Compatibility** - Ethereum, Polygon, Flow EVM, Arbitrum\n- \ud83d\udee1\ufe0f **Type Safety** - Full Pydantic validation for all data models\n- \u26a1 **Async/Await Support** - High-performance async operations\n- \ud83d\udd04 **Automatic Retries** - Robust error handling and retry logic\n- \ud83d\udcca **Real-time Data** - Live price feeds and market updates\n\n## Installation\n\n```bash\npip install openoracle\n```\n\nFor development dependencies:\n```bash\npip install openoracle[dev]\n```\n\nFor all optional features:\n```bash\npip install openoracle[all]\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom openoracle import OpenOracleAPI\n\nasync def main():\n # Initialize the API client\n async with OpenOracleAPI() as api:\n # Route a question to the best oracle\n routing = await api.route_question(\n \"Will BTC exceed $100k by end of 2024?\"\n )\n \n print(f\"Selected Oracle: {routing.selected_oracle}\")\n print(f\"Confidence: {routing.confidence_score}\")\n print(f\"Reasoning: {routing.reasoning}\")\n \n # Get current BTC price\n price = await api.get_price(\"BTC/USD\")\n print(f\"Current BTC Price: ${price.price}\")\n \n # Create a prediction market\n market = await api.create_prediction_market(\n question=\"Will BTC exceed $100k by end of 2024?\",\n poll_id=\"btc-100k-2024\"\n )\n print(f\"Market created: {market['poll_id']}\")\n\nasyncio.run(main())\n```\n\n### Configuration\n\nConfigure the SDK using environment variables:\n\n```bash\n# Core API settings\nexport OPENORACLE_API_KEY=\"your-api-key\"\nexport OPENORACLE_BASE_URL=\"https://api.openoracle.ai\"\n\n# AI routing (optional)\nexport OPENROUTER_API_KEY=\"your-openrouter-key\"\nexport OPENAI_API_KEY=\"your-openai-key\"\n\n# Oracle provider settings\nexport CHAINLINK_API_KEY=\"your-chainlink-key\"\nexport PYTH_ENDPOINT=\"https://hermes.pyth.network\"\n\n# Blockchain RPCs\nexport ETH_RPC_URL=\"https://eth.llamarpc.com\"\nexport POLYGON_RPC_URL=\"https://polygon.llamarpc.com\"\n```\n\nOr use a configuration object:\n\n```python\nfrom openoracle import OracleConfig, OpenOracleAPI\n\nconfig = OracleConfig(\n api_key=\"your-api-key\",\n base_url=\"https://api.openoracle.ai\",\n openrouter_api_key=\"your-openrouter-key\",\n enable_ai_routing=True\n)\n\nasync with OpenOracleAPI(config) as api:\n # Your code here\n pass\n```\n\n### Twitter Integration\n\n```python\nfrom openoracle import OpenOracleAPI\n\nasync with OpenOracleAPI() as api:\n # Analyze a tweet for prediction potential\n analysis = await api.analyze_tweet(\n tweet_text=\"I predict Tesla stock will hit $300 by Q2 2024\",\n author=\"@elonmusk\"\n )\n \n print(f\"Prediction detected: {analysis['has_prediction']}\")\n print(f\"Suggested question: {analysis['suggested_question']}\")\n \n # Create market directly from tweet\n market = await api.create_market_from_tweet(\n tweet_text=\"I predict Tesla stock will hit $300 by Q2 2024\",\n poll_id=\"tesla-300-q2-2024\",\n author=\"@elonmusk\"\n )\n```\n\n### Oracle Provider Usage\n\n```python\n# Get price from specific oracle\nchainlink_price = await api.get_price(\"ETH/USD\", provider=\"chainlink\")\npyth_price = await api.get_price(\"BTC/USD\", provider=\"pyth\")\n\n# Get aggregated price from multiple oracles\naggregated_price = await api.get_price(\"ETH/USD\") # Uses all available oracles\n\n# Check oracle health\nhealth = await api.get_oracle_health()\nprint(f\"Chainlink status: {health['chainlink']['status']}\")\n\n# Get supported assets\nassets = await api.get_supported_assets()\nsports = await api.get_supported_sports()\n```\n\n### Advanced Features\n\n```python\n# Batch operations\nquestions = [\n \"Will BTC hit $100k in 2024?\",\n \"Will ETH hit $10k in 2024?\",\n \"Will DOGE hit $1 in 2024?\"\n]\n\nroutings = await api.batch_route_questions(questions)\nprices = await api.batch_price_feeds([\"BTC/USD\", \"ETH/USD\", \"DOGE/USD\"])\n\n# Real-time price monitoring\nasync def price_callback(price_data):\n print(f\"New price: {price_data.price}\")\n\n# This would use WebSocket connections in a real implementation\nawait api.subscribe_to_prices([\"BTC/USD\"], callback=price_callback)\n```\n\n## Core Components\n\n### OracleRouter\nThe main routing engine that selects optimal oracles:\n\n```python\nfrom openoracle import OracleRouter, OracleConfig\n\nconfig = OracleConfig.from_env()\nrouter = OracleRouter(config)\n\nrouting = await router.route_poll_question(\n \"Will the Fed raise rates in March?\",\n category_hint=\"economic\"\n)\n```\n\n### Oracle Providers\nIndividual oracle provider interfaces:\n\n```python\nfrom openoracle.providers import ChainlinkProvider, PythProvider\n\n# Direct provider usage\nchainlink = ChainlinkProvider(rpc_url=\"https://eth.llamarpc.com\")\nprice_feed = await chainlink.get_price_feed(\"ETH/USD\")\n\npyth = PythProvider()\npyth_price = await pyth.get_price_feed(\"BTC/USD\")\n```\n\n### Schema Validation\nType-safe data models using Pydantic:\n\n```python\nfrom openoracle.schemas import OracleRoutingRequest, OracleProvider\n\nrequest = OracleRoutingRequest(\n question=\"Will BTC hit $100k?\",\n category_hint=\"price\",\n max_cost_usd=10.0,\n preferred_providers=[OracleProvider.CHAINLINK, OracleProvider.PYTH]\n)\n```\n\n## Supported Oracle Providers\n\n| Provider | Price Feeds | Sports | Weather | Events | Custom |\n|----------|-------------|---------|---------|---------|---------|\n| **Chainlink** | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 |\n| **Pyth Network** | \u2705 | \u274c | \u274c | \u274c | \u274c |\n| **UMA Protocol** | \u274c | \u274c | \u274c | \u2705 | \u2705 |\n| **Band Protocol** | \u2705 | \u274c | \u274c | \u274c | \u2705 |\n| **API3** | \u2705 | \u274c | \u2705 | \u274c | \u2705 |\n\n## Supported Blockchains\n\n- Ethereum Mainnet\n- Polygon\n- Flow EVM\n- Arbitrum\n- Avalanche\n- Base\n- Optimism\n\n## Error Handling\n\nThe SDK provides comprehensive error handling:\n\n```python\nfrom openoracle.exceptions import (\n RoutingError,\n ProviderError,\n ValidationError,\n NetworkError\n)\n\ntry:\n routing = await api.route_question(\"Invalid question\")\nexcept RoutingError as e:\n print(f\"Routing failed: {e.message}\")\n print(f\"Available providers: {e.available_providers}\")\nexcept ProviderError as e:\n print(f\"Provider {e.provider_name} failed: {e.provider_error}\")\nexcept ValidationError as e:\n print(f\"Validation failed: {e.field_name} = {e.field_value}\")\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Install dev dependencies\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=openoracle\n\n# Run specific tests\npytest tests/test_routing.py\n```\n\n## Examples\n\nSee the `/examples` directory for complete examples:\n\n- **basic_usage.py** - Getting started examples\n- **twitter_integration.py** - Social media prediction markets \n- **price_monitoring.py** - Real-time price feeds\n- **custom_oracles.py** - Building custom oracle integrations\n- **batch_operations.py** - Efficient batch processing\n\n## API Reference\n\nComplete API documentation is available at [docs.openoracle.ai](https://docs.openoracle.ai)\n\n### Main Classes\n\n- `OpenOracleAPI` - Main API client\n- `OracleRouter` - Core routing engine\n- `TwitterAnalyzer` - Social media integration\n- `OracleConfig` - Configuration management\n\n### Key Methods\n\n- `route_question()` - Route questions to optimal oracles\n- `get_price()` - Get asset prices\n- `create_prediction_market()` - Create new markets\n- `analyze_tweet()` - Analyze social media content\n- `get_oracle_health()` - Check oracle status\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/openoracle/python-sdk\ncd python-sdk\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .[dev]\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npytest\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [docs.openoracle.ai](https://docs.openoracle.ai)\n- **Discord**: [discord.gg/openoracle](https://discord.gg/openoracle) \n- **Twitter**: [@OpenOracleHQ](https://twitter.com/OpenOracleHQ)\n- **Email**: [team@openoracle.ai](mailto:team@openoracle.ai)\n\n## Roadmap\n\n- [ ] Additional oracle providers (DIA, Tellor, Supra)\n- [ ] GraphQL API support\n- [ ] Advanced analytics and insights\n- [ ] Mobile SDK (React Native)\n- [ ] Telegram/Discord bot integration\n- [ ] Governance token integration\n- [ ] Cross-chain message passing\n\n---\n\n**Built with \u2764\ufe0f by the OpenOracle Team**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Intelligent Oracle Routing for Prediction Markets",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://docs.openoracle.ai",
"Homepage": "https://openoracle.ai",
"Issues": "https://github.com/openoracle/python-sdk/issues",
"Repository": "https://github.com/openoracle/python-sdk"
},
"split_keywords": [
"oracle",
" blockchain",
" prediction-markets",
" defi",
" chainlink",
" pyth",
" uma",
" api3",
" band-protocol",
" ai",
" routing",
" twitter",
" social-media"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a66b0940c32778d472069a3671337ceeed91bf73aa31a8775944182e01f7b1e3",
"md5": "cb27e29261ad1c7946f16f42d4698ec4",
"sha256": "6cada3b5ef641fe5b527e3eece36201b112fbf4df5cec6fee13ca4ad45fec0a1"
},
"downloads": -1,
"filename": "openoracle-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cb27e29261ad1c7946f16f42d4698ec4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 123933,
"upload_time": "2025-09-10T14:46:12",
"upload_time_iso_8601": "2025-09-10T14:46:12.680361Z",
"url": "https://files.pythonhosted.org/packages/a6/6b/0940c32778d472069a3671337ceeed91bf73aa31a8775944182e01f7b1e3/openoracle-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "592e8bacdd2853a7670ec06867f0df037385533cf19596e996886c17f65a3a9b",
"md5": "455bb7418a595427b7753d1bafba4f1e",
"sha256": "fb74d5e1bfbcfcfde22f9291819a6a7b6da468b61ac2ee7ecb0eb2a35257e214"
},
"downloads": -1,
"filename": "openoracle-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "455bb7418a595427b7753d1bafba4f1e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 114146,
"upload_time": "2025-09-10T14:46:14",
"upload_time_iso_8601": "2025-09-10T14:46:14.210834Z",
"url": "https://files.pythonhosted.org/packages/59/2e/8bacdd2853a7670ec06867f0df037385533cf19596e996886c17f65a3a9b/openoracle-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 14:46:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openoracle",
"github_project": "python-sdk",
"github_not_found": true,
"lcname": "openoracle"
}
JSON
