An HTTP proxy specifically designed for the ESI API for EVE Online.
The ESI API is a great resource, but can be difficult to work with. The features below are all things you have to be acutely aware of. With CCP being trigger-happy about banning IPs from accessing the API, using this proxy will let you get on with writing your application and not worry about the minutiae of ESI lore.
Join us on Discord.
Fly safe o7
- Character login is supported and OAuth is handled automatically, see below
- Cache responses to disk to improve request times and reduce load on the ESI itself. Authed requests are not currently cached
- Conditional requests to refresh objects in the cache
- Rate limiting to help avoid being banned, including different limits for the endpoints which have special undocumented limits
- Handle ESI error limit headers to stop all requests if the limit is reached
- Retry failed requests if a 5xx is returned
- User agent header is automatically handled
- Fetching multiple pages concurrently if no page (or page 0) is set in the request, merging all pages into a single response
Caching, rate limiting, retries, etc. are all handled transparently.
Run via Docker (installation):
docker run -it -v eve-esi-proxy:/data -p 8182:8182 -m 2g -e "ESI_USER_AGENT=<your email>" autonomouslogic/eve-esi-proxy:latestThen you request data as you would on the ESI, just from localhost instead:
curl "http://localhost:8182/latest/status/"or
curl "http://localhost:8182/latest/markets/10000002/orders/?order_type=all"The proxy is configured via environment variables set via docker run -e:
PROXY_PORT- The port the proxy listens on - defaults to8182PROXY_HOST- The host the proxy listens on - defaults to0.0.0.0ESI_BASE_URL- The base URL of the ESI API - defaults tohttps://esi.evetech.netESI_USER_AGENT- The user agent to use when making requests to the ESI API - if this is not set and no user agent is supplied on the request, the proxy will return a400 Bad RequestHTTP_CACHE_DIR- The directory to store cached responses inHTTP_CACHE_MAX_SIZE- The maximum size of the cache in bytes - defaults to 1 GiBHTTP_MAX_TRIES- Maximum number of times to try a single request - defaults to3HTTP_RETRY_DELAY- Delay between retries - defaults toPT2SESI_RATE_LIMIT_PER_S- The number of requests allowed per second for endpoints without a special rate limit - defaults to100ESI_MARKET_HISTORY_RATE_LIMIT_PER_S- The number of requests allowed per second for market history - defaults to5- increasing this could get you bannedESI_CHARACTER_CORPORATION_HISTORY_RATE_LIMIT_PER_S- The number of requests allowed per second for character corporation history - defaults to5- increasing this could get you bannedLOG_LEVEL- How much logging to do - defaults toINFO- options areTRACE,DEBUG,INFO,WARN,ERROR, orFATALEVE_OAUTH_CLIENT_ID- The client ID of the application you created on the EVE Developer PortalEVE_OAUTH_SECRET_KEY- The secret key of the application you created on the EVE Developer PortalEVE_OAUTH_CALLBACK_URL- The callback URL of the application you created on the EVE Developer Portal - defaults tohttp://localhost:8182/esiproxy/login/callbackEVE_OAUTH_AUTHORIZATION_URL- defaults tohttps://login.eveonline.com/v2/oauth/authorizeEVE_OAUTH_TOKEN_URL- defaults tohttps://login.eveonline.com/v2/oauth/tokenHTTP_CONNECT_TIMEOUT- defaults toPT5SHTTP_READ_TIMEOUT- defaults toPT60SHTTP_WRITE_TIMEOUT- defaults toPT60SHTTP_CALL_TIMEOUT- defaults toPT60SHTTP_MAX_CONCURRENT_PAGES- Maximum number of pages to fetch concurrently per request - defaults to8
To login with a character, open the proxy interface at http://localhost:8182/ and click "Add character". After a successful login, you'll be shown a "Proxy key". Use this key in-place of your normal OAuth access token, like:
curl "http://localhost:8182/latest/characters/{character_id}/blueprints/?token=<proxy key>"The proxy will request an OAuth access token in the background and use that for you.
The proxy does not send any auth data to anyone other than EVE Online. Refresh tokens are stored unencrypted on disk in a Docker volume.
If you want the proxy to use your own client ID and secret, you can configure them via EVE_OAUTH_CLIENT_ID and EVE_OAUTH_SECRET_KEY.
You will have to do this if you want to use a port other than 8182.
Create an application in the the EVE Developer Portal:
- Select "Authentication & API Access"
- Select whatever scopes you want to use
- Set the callback URL to
http://localhost:8182/esiproxy/login/callback- be sure to change the port number if you're not using the default
Copy the "Client ID" and "Secret Key" and set them on the EVE_OAUTH_CLIENT_ID and EVE_OAUTH_SECRET_KEY environment variables respectively.
For instance:
docker run -e "EVE_OAUTH_CLIENT_ID=<your client id>" -e "EVE_OAUTH_CLIENT_SECRET=<your secret key>"The EVE ESI Proxy is built on Helidon, a fast HTTP server stack for Java 21, and OkHttp, a fast HTTP client for Java. It'll easily handle tens of thousands of requests per second without breaking a sweat, way more than you'd ever need. See this ticket for some very basic load testing.
The EVE ESI Proxy itself is licensed under the MIT-0 license.
EVE Online and all assets related to it are owned by CCP hf.:
