eve-esi

# Data Handling

This skill communicates exclusively with the official EVE Online ESI API (`esi.evetech.net`) and EVE SSO (`login.eveonline.com`).
No character data is exfiltrated to third-party servers.
Optional integrations (Telegram, Discord) are user-configured via environment variables and only transmit alerts defined by the user.

# EVE Online ESI

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

- Base URL: `https://esi.evetech.net/latest`
- Spec: `https://esi.evetech.net/latest/swagger.json`
- API Explorer: <https://developers.eveonline.com/api-explorer>

## Skill Location

All scripts live at: `~/.openclaw/workspace/skills/eve-esi/scripts/`

Always use full paths when calling scripts:
```bash
SKILL=~/.openclaw/workspace/skills/eve-esi
```

## Authentication

Tokens are stored in `~/.openclaw/eve-tokens.json` (created by auth_flow.py, chmod 600).
All scripts (`get_token.py`, `esi_query.py`) read from this file directly — **no env vars are required for normal operation.**

**First-time setup** (once per character):
```bash
# 1. Set up SSH tunnel on your local PC:
#    ssh -L 8080:127.0.0.1:8080 user@your-server -N
# 2. Run auth flow on server (pass Client ID directly):
python3 ~/.openclaw/workspace/skills/eve-esi/scripts/auth_flow.py --client-id <YOUR_CLIENT_ID> --char-name main
# 3. Open the shown URL in browser, log in with EVE account
```

**Get a fresh access token** (tokens expire after ~20min, refresh is automatic):
```bash
TOKEN=$(python3 ~/.openclaw/workspace/skills/eve-esi/scripts/get_token.py --char main)
```

**List authenticated characters:**
```bash
python3 ~/.openclaw/workspace/skills/eve-esi/scripts/get_token.py --list
```

For full OAuth2/PKCE details: see `references/authentication.md`.

## Public endpoints (no auth)

```bash
# Character public info
curl -s "https://esi.evetech.net/latest/characters/2114794365/" | python -m json.tool

# Por...

# EVE ESI Skill for OpenClaw

An [OpenClaw](https://openclaw.ai) skill for interacting with the [EVE Online ESI API](https://developers.eveonline.com/api-explorer) (EVE Swagger Interface).

## Features

- **Authentication** — PKCE OAuth2 flow via EVE SSO, auto-refreshing tokens
- **ESI Queries** — reusable Python helper with pagination, error limits, and caching
- **Multi-character** — store and manage tokens for multiple characters
- **Dashboard Config** — modular alert/report/market-tracking config schema
- **Reference docs** — full scope list, endpoint index, auth flow details

## Structure

```
eve-esi/
├── SKILL.md                        # OpenClaw skill instructions
├── README.md                       # This file
├── scripts/
│   ├── auth_flow.py                # One-time EVE SSO OAuth2 authentication
│   ├── get_token.py                # Token refresh helper (auto-rotates)
│   ├── esi_query.py                # ESI query helper with pagination
│   └── validate_config.py          # Dashboard config validator
├── config/
│   ├── schema.json                 # JSON Schema for dashboard config
│   └── example-config.json         # Ready-to-use template
└── references/
    ├── authentication.md           # EVE SSO OAuth2 + PKCE details
    └── endpoints.md                # All character endpoints + scopes
```

## Installation

```bash
cd ~/.openclaw/workspace/skills
git clone https://github.com/burnshall-ui/openclaw-eve-skill eve-esi
```

## Authentication Setup

**Prerequisites:**
1. Register an app at [developers.eveonline.com](https://developers.eveonline.com/applications)
2. Set callback URL to `http://127.0.0.1:8080/callback`
3. Note your **Client ID**

**One-time auth per character** (requires browser access):

```bash
# If on a remote server, set up an SSH tunnel first:
ssh -L 8080:127.0.0.1:8080 user@your-server -N

# Run the auth flow:
python3 scripts/auth_flow.py --client-id <YOUR_CLIENT_ID> --char-name m...