https://github.com/xlemmingx/ha-torn
Torn City API-Integration plugin for HomeAssistant
https://github.com/xlemmingx/ha-torn
hacs home-assistant home-assistant-integration homeassistant-custom-component torn torn-city
Last synced: 5 months ago
JSON representation
Torn City API-Integration plugin for HomeAssistant
- Host: GitHub
- URL: https://github.com/xlemmingx/ha-torn
- Owner: xlemmingx
- License: mit
- Created: 2026-01-02T11:56:45.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-12T11:52:23.000Z (6 months ago)
- Last Synced: 2026-01-13T21:33:24.994Z (6 months ago)
- Topics: hacs, home-assistant, home-assistant-integration, homeassistant-custom-component, torn, torn-city
- Language: Python
- Homepage:
- Size: 63.5 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Torn City Integration for Home Assistant
A comprehensive Home Assistant integration for [Torn City](https://www.torn.com), providing real-time access to your player stats, finances, stocks, travel status, cooldowns, and more.
[](https://github.com/custom-components/hacs)
[](https://github.com/xlemmingx/ha-torn/releases)
[](https://github.com/xlemmingx/ha-torn)
[](LICENSE)
## Installation
### HACS (Recommended)
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=xlemmingx&repository=ha-torn&category=integration)
1. Open HACS → Integrations → Custom repositories
2. Add `https://github.com/xlemmingx/ha-torn` as "Integration"
3. Search for "Torn City" and install
4. Restart Home Assistant
### Manual Installation
1. Download from [releases page](https://github.com/xlemmingx/ha-torn/releases)
2. Copy to `config/custom_components/torn/`
3. Restart Home Assistant
## Configuration
1. Settings → Devices & Services → Add Integration
2. Search "Torn City"
3. Enter your [Torn City API key](https://www.torn.com/preferences.php#tab=api) (**Full Access** recommended)
4. Optional: Enable "Throttle API Usage" to reduce API calls if needed
5. Submit
### Customizing API Endpoints
After setup, you can configure which features to enable:
1. Settings → Devices & Services → Torn City → Configure
2. Enable/disable individual features (Money, Travel, Cooldowns, Stats, Skills, Company, Stocks, Refills, Log)
3. Disabled features reduce API usage and remove associated sensors
Profile & Bars are always enabled (core functionality).
## Features
### Player & Stats
- Name, level, status, battle stats (strength, defense, speed, dexterity)
### Bars & Cooldowns
- Energy, Nerve, Happy, Life, Chain with timers
- Chain timeout timer
- Drug, Medical, Booster cooldowns
### Finances
- Wallet, Vault, Banks, Company & Faction funds
- City Bank investments with profit tracking
- Daily networth
### Stocks (All 35 Torn stocks)
- Current prices, market cap, owned shares
- Stock benefit blocks tracking
- Ready-to-claim benefits
### Travel & Activity
- Destination, method, arrival/departure times
- Recent activity log
### Other
- Skills (dynamic sensors)
- Company stats
All sensors prefixed with `sensor.torn_` and `binary_sensor.torn_`.
## API Rate Limiting
The integration uses intelligent caching to minimize API calls:
- High frequency (5s cache): profile, bars, money, travel, log
- Medium frequency (60s cache): cooldowns, stats, company, stocks
- Low frequency (600s cache): skills, refills
**Default usage: ~64 API calls/minute** (64% of the 100/minute limit)
### Reducing API Usage
1. **Disable unused endpoints**: Configure the integration to disable features you don't use (each disabled feature saves 1-2 API calls)
2. **Enable "Throttle API Usage"**: Reduces update frequency by 10x if you're sharing an API key or approaching limits
## Privacy & Security
This integration stores your Torn City API key **locally** in your Home Assistant configuration only.
- No data is sent to external servers
- No data sharing with third parties
- API key is used only for fetching your personal Torn City data
- All data remains on your Home Assistant instance
## Support
- [GitHub Issues](https://github.com/xlemmingx/ha-torn/issues)
- [Torn API Documentation](https://www.torn.com/swagger.php)
## License
MIT License - see LICENSE file for details.
This integration is not affiliated with Torn City Ltd.