\r \r

Data Handling\r

\r This skill communicates with the following external services:\r \r

• EVE Online ESI API (esi.evetech.net) — all character and universe data queries\r
• EVE SSO (login.eveonline.com) — OAuth2 authentication and token refresh\r
• zKillboard API (zkillboard.com/api/) — optional, for PVP threat assessment data (public, no auth required)\r
• Telegram Bot API — optional, user-configured via TELEGRAM_BOT_TOKEN for alert notifications\r
• Discord Webhooks — optional, user-configured via DISCORD_WEBHOOK_URL for alert notifications\r \r No character data is sent to third-party servers beyond the above. Telegram/Discord only transmit alerts defined by the user.\r \r

EVE Online ESI\r

\r The ESI (EVE Swagger Interface) is the official REST API for EVE Online third-party development.\r \r

• Base URL: https://esi.evetech.net/latest\r
• Spec: https://esi.evetech.net/latest/swagger.json\r
• API Explorer: \x3Chttps://developers.eveonline.com/api-explorer>\r \r

Skill Location\r

\r All scripts live at: ~/.openclaw/workspace/skills/eve-esi/scripts/\r \r Always use full paths when calling scripts:\r

SKILL=~/.openclaw/workspace/skills/eve-esi\r
```\r
\r
## Authentication\r
\r
Tokens are stored in `~/.openclaw/eve-tokens.json` (created by auth_flow.py, chmod 600).\r
All scripts (`get_token.py`, `esi_query.py`) read from this file directly — **no env vars are required for normal operation.**\r
\r
**First-time setup** (once per character):\r
```bash\r
# 1. Set up SSH tunnel on your local PC:\r
#    ssh -L 8080:127.0.0.1:8080 user@your-server -N\r
# 2. Run auth flow on server (pass Client ID directly):\r
python3 ~/.openclaw/workspace/skills/eve-esi/scripts/auth_flow.py --client-id \x3CYOUR_CLIENT_ID> --char-name main\r
# 3. Open the shown URL in browser, log in with EVE account\r
```\r
\r
**Get a fresh access token** (tokens expire after ~20min, refresh is automatic):\r
```bash\r
TOKEN=$(python3 ~/.openclaw/workspace/skills/eve-esi/scripts/get_token.py --char main)\r
```\r
\r
**List authenticated characters:**\r
```bash\r
python3 ~/.openclaw/workspace/skills/eve-esi/scripts/get_token.py --list\r
```\r
\r
For full OAuth2/PKCE details: see `references/authentication.md`.\r
\r
## Public endpoints (no auth)\r
\r
```bash\r
# Character public info\r
curl -s "https://esi.evetech.net/latest/characters/2114794365/" | python -m json.tool\r
\r
# Portrait URLs\r
curl -s "https://esi.evetech.net/latest/characters/2114794365/portrait/"\r
\r
# Corporation history\r
curl -s "https://esi.evetech.net/latest/characters/2114794365/corporationhistory/"\r
\r
# Bulk affiliation lookup\r
curl -s -X POST "https://esi.evetech.net/latest/characters/affiliation/" \\r
  -H "Content-Type: application/json" \\r
  -d '[2114794365, 95538921]'\r
```\r
\r
## Character info (authenticated)\r
\r
```bash\r
TOKEN="\x3Cyour_access_token>"\r
CHAR_ID="\x3Cyour_character_id>"\r
\r
# Online status (scope: esi-location.read_online.v1)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/online/"\r
```\r
\r
## Wallet\r
\r
```bash\r
# Balance (scope: esi-wallet.read_character_wallet.v1)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/wallet/"\r
\r
# Journal (paginated)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/wallet/journal/?page=1"\r
\r
# Transactions\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/wallet/transactions/"\r
```\r
\r
## Assets\r
\r
```bash\r
# All assets (paginated; scope: esi-assets.read_assets.v1)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/assets/?page=1"\r
\r
# Resolve item locations\r
curl -s -X POST -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '[1234567890, 9876543210]' \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/assets/locations/"\r
\r
# Resolve item names\r
curl -s -X POST -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '[1234567890]' \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/assets/names/"\r
```\r
\r
## Skills\r
\r
```bash\r
# All trained skills + total SP (scope: esi-skills.read_skills.v1)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/skills/"\r
\r
# Skill queue (scope: esi-skills.read_skillqueue.v1)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/skillqueue/"\r
\r
# Attributes (intelligence, memory, etc.)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/attributes/"\r
```\r
\r
## Location and ship\r
\r
```bash\r
# Current location (scope: esi-location.read_location.v1)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/location/"\r
\r
# Current ship (scope: esi-location.read_ship_type.v1)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/ship/"\r
```\r
\r
## Clones and implants\r
\r
```bash\r
# Jump clones + home station (scope: esi-clones.read_clones.v1)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/clones/"\r
\r
# Active implants (scope: esi-clones.read_implants.v1)\r
curl -s -H "Authorization: Bearer $TOKEN" \\r
  "https://esi.evetech.net/latest/characters/$CHAR_ID/implants/"\r
```\r
\r
## More endpoints\r
\r
For contracts, fittings, mail, industry, killmails, market orders, mining, planetary interaction, loyalty points, notifications, blueprints, standings, and all other character endpoints, see [references/endpoints.md](references/endpoints.md).\r
\r
## Dashboard Config\r
\r
The skill supports a modular dashboard config for alerts, reports, and market tracking. Each user defines what they need in a JSON config file.\r
\r
- **Schema**: [config/schema.json](config/schema.json) — full JSON Schema with all fields, types, and defaults\r
- **Example**: [config/example-config.json](config/example-config.json) — ready-to-use template\r
\r
### Features\r
\r
| Module | Description |\r
|--------|-------------|\r
| **Alerts** | Real-time polling for war decs, structure attacks, skill completions, wallet changes, industry jobs, PI extractors, killmails, contracts, clone jumps, mail |\r
| **Reports** | Cron-scheduled summaries: net worth, skill queue, industry, market orders, wallet, assets |\r
| **Market** | Price tracking with absolute thresholds and trend detection |\r
\r
### Security\r
\r
Tokens should **not** be stored in plain text. Use environment variable references:\r
\r
```json\r
{\r
  "token": "$ENV:EVE_TOKEN_MAIN",\r
  "refresh_token": "$ENV:EVE_REFRESH_MAIN"\r
}\r
```\r
\r
The config file should live outside the workspace (e.g. `~/.openclaw/eve-dashboard-config.json`).\r
\r
### Validate a config\r
\r
```bash\r
python scripts/validate_config.py path/to/config.json\r
\r
# Show example config\r
python scripts/validate_config.py --example\r
\r
# Show JSON schema\r
python scripts/validate_config.py --schema\r
```\r
\r
## Using the query script\r
\r
```bash\r
SKILL=~/.openclaw/workspace/skills/eve-esi\r
# Replace 'main' with your --char-name if you authenticated under a different name.\r
TOKEN=$(python3 $SKILL/scripts/get_token.py --char main)\r
# get_token.py --char-id prints just the character ID for the named character.\r
CHAR_ID=$(python3 $SKILL/scripts/get_token.py --char main --char-id 2>/dev/null) || \\r
CHAR_ID=$(python3 -c "import json, os, pathlib; p = pathlib.Path(os.environ.get('OPENCLAW_STATE_DIR', os.path.expanduser('~/.openclaw'))) / 'eve-tokens.json'; d = json.loads(p.read_text(encoding='utf-8')); chars = d.get('characters', {}); char = chars.get('main') or next(iter(chars.values()), None); print(char['character_id'] if char else '')")\r
\r
# Simple query\r
python3 $SKILL/scripts/esi_query.py --token "$TOKEN" --endpoint "/characters/$CHAR_ID/wallet/" --pretty\r
\r
# Fetch all pages of assets\r
python3 $SKILL/scripts/esi_query.py --token "$TOKEN" --endpoint "/characters/$CHAR_ID/assets/" --pages --pretty\r
\r
# POST request (e.g. asset names)\r
python3 $SKILL/scripts/esi_query.py --token "$TOKEN" --endpoint "/characters/$CHAR_ID/assets/names/" \\r
  --method POST --body '[1234567890]' --pretty\r
```\r
\r
## Best practices\r
\r
- **Caching**: respect the `Expires` header; do not poll before it expires.\r
- **Error limits**: monitor `X-ESI-Error-Limit-Remain`; back off when low.\r
- **User-Agent**: always set a descriptive User-Agent with contact info.\r
- **Rate limits**: some endpoints (mail, contracts) have internal rate limits returning HTTP 520.\r
- **Pagination**: check the `X-Pages` response header; iterate with `?page=N`.\r
- **Versioning**: use `/latest/` for current stable routes. `/dev/` may change without notice.\r
\r
## Threat Assessment & Route Planning\r
\r
The skill provides threat intelligence for PI systems in low/null-sec space. Data sources: ESI (kills, jumps, FW, incursions) and zKillboard (PVP activity).\r
\r
### ESI Threat Endpoints\r
\r
```bash\r
SKILL=~/.openclaw/workspace/skills/eve-esi\r
\r
# System kills (last hour) — all or filtered\r
python3 $SKILL/scripts/esi_query.py --action system_kills --pretty\r
python3 $SKILL/scripts/esi_query.py --action system_kills --system-ids 30002537,30045337 --pretty\r
\r
# System jump traffic (last hour)\r
python3 $SKILL/scripts/esi_query.py --action system_jumps --system-ids 30045337 --pretty\r
\r
# System info (name, security status)\r
python3 $SKILL/scripts/esi_query.py --action system_info --system-id 30002537 --pretty\r
\r
# Route planning (flags: secure, shortest, insecure)\r
python3 $SKILL/scripts/esi_query.py --action route_plan --origin 30000142 --destination 30002537 --route-flag secure --pretty\r
\r
# Character location (requires auth)\r
TOKEN=$(python3 $SKILL/scripts/get_token.py --char main)\r
python3 $SKILL/scripts/esi_query.py --action character_location --token "$TOKEN" --character-id $CHAR_ID --pretty\r
\r
# Faction warfare systems\r
python3 $SKILL/scripts/esi_query.py --action fw_systems --pretty\r
\r
# Active incursions\r
python3 $SKILL/scripts/esi_query.py --action incursions --pretty\r
```\r
\r
### Threat Assessment Scripts (Workspace)\r
\r
> **Hinweis:** Die Workspace-Skripte (`threat_query.py`, `cache_threat_data.py`, `cache_market_prices.py`) sind Referenz-Beschreibungen und müssen erst im Agent-Workspace erstellt werden, bevor sie genutzt werden können.\r
\r
These scripts live in `~/.openclaw/workspace/scripts/` (not in the skill repo):\r
\r
```bash\r
# Threat level for specific systems\r
python3 ~/.openclaw/workspace/scripts/threat_query.py --action threat_assessment --system-ids 30002537,30045337\r
\r
# Threat for all PI systems across all characters\r
python3 ~/.openclaw/workspace/scripts/threat_query.py --action threat_assessment_pi\r
\r
# Route with per-system threat annotation\r
python3 ~/.openclaw/workspace/scripts/threat_query.py --action route_annotated --origin 30000142 --destination 30002537\r
\r
# Route from character's current location\r
python3 ~/.openclaw/workspace/scripts/threat_query.py --action route_annotated --character main --destination 30045337\r
\r
# Full PI + Threat morning briefing\r
python3 ~/.openclaw/workspace/scripts/threat_query.py --action pi_briefing\r
```\r
\r
### Threat Levels\r
\r
| Level | Score | Meaning |\r
|-------|-------|---------|\r
| `low` | 0-15 | Normaler PI-Betrieb |\r
| `medium` | 15-40 | Schnell rein, schnell raus |\r
| `high` | 40-80 | Nur mit Scout/Cloak |\r
| `critical` | 80+ | NICHT reinfliegen |\r
\r
### Threat Cache\r
\r
Threat data is cached in Redis (30min TTL for ESI, 1h for zKillboard). The cache is updated every 30 minutes via cron:\r
\r
```bash\r
# Update cache manually\r
python3 ~/.openclaw/workspace/scripts/cache_threat_data.py\r
\r
# Show cached threat data\r
python3 ~/.openclaw/workspace/scripts/cache_threat_data.py --check\r
```\r
\r
## Resolving type IDs\r
\r
ESI returns numeric type IDs (e.g. for ships, items, skills). Resolve names via:\r
\r
```bash\r
# Single type\r
curl -s "https://esi.evetech.net/latest/universe/types/587/"\r
\r
# Bulk names (up to 1000 IDs)\r
curl -s -X POST "https://esi.evetech.net/latest/universe/names/" \\r
  -H "Content-Type: application/json" \\r
  -d '[587, 638, 11393]'\r
```\r