API reference

Read-only JSON access to every public EVE contract we ingest, plus the analytics derived from them. No key, no sign-in, no registration — just GET requests.

OpenAPI 3.1 spec llms.txt llms-full.txt Service index

Getting started

curl 'https://contracts.tovdc.com/api/v1/contracts?region_id=10000002&category=ship&sort=price&dir=asc'

Base URL https://contracts.tovdc.com. Every endpoint is a GET returning JSON.
Success bodies are { data, meta }; errors are { error: { code, message } } with a matching HTTP status.
List parameters accept repetition (?type=a&type=b) or commas (?type=a,b).
Field names are snake_case and timestamps are ISO-8601 UTC, matching ESI's conventions.
CORS is open, so browser clients can call the API directly without a proxy.

Rate limits

120 requests per 60 seconds per IP. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Exceeding the limit returns 429 with a Retry-After header — please honour it rather than retrying immediately.

What's in scope

Only contracts ingested from CCP's public per-region endpoints are served. Contracts polled with a signed-in user's ESI token are private to that user and never appear in the API. Regions are polled on a staggered 30-minute cycle, so first_seen_at can lag CCP's date_issued by up to half an hour — use first_seen_at when you want “what's new”.

Contracts

Search and read public contracts.

GET/api/v1/contractscached 30s

Paginated search over every public contract we have ingested, across all EVE regions. Filters combine with AND. `q` matches the contract title OR the name of any included item, which is usually what you want — EVE contract titles are frequently blank or generic.

Parameter	Type	Description
region_id	integer[]	Region id. Repeat or comma-separate for multiple. Also accepted as `region`.
type	string[]	Contract type. Repeatable.One of: unknown, item_exchange, auction, courier, loan
status	string[]	Contract status. Repeatable. Omitted means everything except deleted/cancelled/reversed.One of: outstanding, in_progress, finished_issuer, finished_contractor, finished, cancelled, rejected, failed, deleted, reversed
availability	string[]	Contract availability. Repeatable.One of: public, personal, corporation, alliance
category	string	Match contracts containing at least one included item in this item category. Full list at /api/v1/categories.One of: ship, blueprint_original, blueprint_copy, blueprint, module, charge, drone, implant, skill, commodity, structure, structure_module, deployable, subsystem, fighter, skin, planetary, special_edition
q	string	Case-insensitive substring match on contract title or included item names.
price_min	number	Minimum price in ISK.
price_max	number	Maximum price in ISK.
issuer_corporation_id	integer	Only contracts issued by this corporation. Also accepted as `issuer_corp`.
sort	string	Sort column.One of: date_issued, date_expired, price, volume, collateralDefault: date_issued
dir	string	Sort direction.One of: asc, descDefault: desc
page	integer	1-based page number.Default: 1
page_size	integer	Results per page, 10–200. Also accepted as `limit`.Default: 50

Response

{ data: ContractSummary[], meta: { page, page_size, total, total_pages } }

curl 'https://contracts.tovdc.com/api/v1/contracts?region_id=10000002&type=item_exchange&category=ship&sort=price&dir=asc'

GET/api/v1/contracts/{contract_id}cached 60s

Full contract record including the item list with blueprint metadata (runs, ME, TE, BPC/BPO) and resolved location names. 404s for contracts that are not public.

Parameter	Type	Description
contract_id*	integer	EVE contract id.

Response

{ data: ContractDetail }

curl 'https://contracts.tovdc.com/api/v1/contracts/234567890'

Analytics

Derived price, volume, and activity series.

GET/api/v1/analytics/pricescached 300s

Min/median/max unit price per hour, derived from outstanding single-item item_exchange contracts. Multi-item bundles are excluded — their total price says nothing about the unit value of any one item in them.

Parameter	Type	Description
type*	string	Item type id or name.
region*	string	Region id or name.
days	integer	Lookback window, 1–30.Default: 7

Response

{ data: [{ captured_at, min_price, median_price, max_price, sample_count, volume }], meta: {…} }

curl 'https://contracts.tovdc.com/api/v1/analytics/prices?type=PLEX&region=10000002&days=7'

GET/api/v1/analytics/volumecached 900s

Long-form daily counts of newly seen public contracts for the busiest regions. One row per (day, region).

Parameter	Type	Description
days	integer	Lookback window, 1–30.Default: 30
top_regions	integer	How many regions to include, ranked by activity. 1–50.Default: 8

Response

{ data: [{ day, region_id, region_name, contracts }], meta: {…} }

curl 'https://contracts.tovdc.com/api/v1/analytics/volume?days=14&top_regions=5'

GET/api/v1/analytics/issuerscached 900s

Leaderboard of public-contract issuers over a rolling window.

Parameter	Type	Description
days	integer	Lookback window, 1–30.Default: 7
by	string	Group by corporation or by character.One of: corp, characterDefault: corp
limit	integer	Max rows, 1–200.Default: 100

Response

{ data: [{ corporation_id | character_id, name, contracts, total_value }] }

curl 'https://contracts.tovdc.com/api/v1/analytics/issuers?days=7&by=corp&limit=25'

GET/api/v1/analytics/depthcached 60s

Currently outstanding single-item item_exchange contracts for one type, cheapest unit price first. This is the live view; /analytics/prices is the historical rollup.

Parameter	Type	Description
type*	string	Item type id or name.
region	string	Optional region id or name filter.
limit	integer	Max rows, 1–200.Default: 100

Response

{ data: [{ contract_id, region_id, region_name, quantity, price, unit_price, url }], meta: {…} }

curl 'https://contracts.tovdc.com/api/v1/analytics/depth?type=PLEX&limit=20'

Reference

Static lookups: regions, item types, filter codes.

GET/api/v1/regionscached 3600s

Every region id and name. Use `q` to search by name.

Parameter	Type	Description
q	string	Name substring filter.

Response

{ data: [{ region_id, name }] }

curl 'https://contracts.tovdc.com/api/v1/regions?q=Forge'

GET/api/v1/typescached 3600s

Resolve an item name to a `type_id` (or a `type_id` back to a name). Backed by the EVE Static Data Export, so it covers every published type.

Parameter	Type	Description
q	string	Name search, minimum 2 characters. Required unless `id` is given.
id	integer	Exact type id lookup.
limit	integer	Max results, 1–100.Default: 25

Response

{ data: [{ type_id, name }] }

curl 'https://contracts.tovdc.com/api/v1/types?q=Skill%20Extractor'

GET/api/v1/categoriescached 86400s

Accepted values for the `category` parameter on /api/v1/contracts.

Response

{ data: [{ code, label, category_ids, is_blueprint_copy }] }

curl 'https://contracts.tovdc.com/api/v1/categories'

Getting started

Rate limits

What's in scope

Contracts

Analytics

Reference

Meta