WolfMarket API

Getting started

Base URL: https://wolfmarket.freebranch.com. Every data request needs an API key in the X-Api-Key header — create one in the portal. Raw API access is a Data-plan feature — every other plan gets the dashboard: interactive charts of everything you track plus the market commons, company filing and financials pages, and futures-positioning views, no code required. Opt-in email alerts (portal → Account view) notify you within the hour when a tracked company files with the SEC, and a Monday digest summarizes your tracked entities' week. Per-entity data — companies, commodity series, COT markets — is served for entities on your tracked list; economy-wide commons (CPI, Treasury yields, policy rates, FX, headline indexes) are open to every plan.

curl -H "X-Api-Key: wm_..." \
  "https://wolfmarket.freebranch.com/api/v1/series/EIA:PET.RWTC.D/observations?from=2020-01-01"

Every data response uses one envelope: { data, meta, attribution }. The attribution array lists the origin of every source present in the result — see your obligations below.

rate limit 10 requests/second per key (burst 20). Exceeding it returns 429.

Database starter kit (Data plan)

Rather run your own database? The portal generates a personalized kit: name your database, pick SQL Server or PostgreSQL, choose the data domains — and download a ZIP containing the create-database script, the full schema, an automated sync script (initial backfill + re-runnable refresh of everything you're entitled to), and step-by-step instructions.

# SQL Server (nothing to install beyond SQL Server itself)
.\sync.ps1 -ApiKey wm_YOUR_KEY -Init

# PostgreSQL (psql + curl)
./sync.sh --api-key wm_YOUR_KEY --init

Re-running the sync is always safe — every load is an idempotent upsert with incremental watermarks. Your API key is a runtime parameter, never stored in the kit. Attribution obligations ship inside the kit as ATTRIBUTION.md and are collected automatically into an attribution_seen table.

What's inside

No equity prices or exchange market data — every byte served here is verified redistributable (US-government public domain or CC-BY). That verification is the product.

Endpoint reference

All endpoints are GET unless noted. Dates are YYYY-MM-DD. Machine-readable spec: /openapi/v1.json.

/api/v1/catalog/sources

All data sources with license type, terms URL, and attribution requirements.

/api/v1/catalog/datasets?source=&domain=

Datasets per source. domain ∈ macro | commodities | energy | ag | prices | fx | filings | registry.

/api/v1/catalog/series?q=&dataset=&page=&pageSize=

Search the time-series catalog by key or title. Each entry carries units, frequency (D/W/M/Q/A), and first/last observation dates.

/api/v1/series/{seriesKey}/observations?from=&to=&limit=

Observations for one series, oldest first. Series keys are namespaced by source:

/api/v1/companies?q=&covered=

Search all ~8,000 SEC registrants by name or ticker. covered=true limits to companies with collected data. Also /api/v1/companies/{cikOrTicker} for one.

/api/v1/global/companies?registry=&q=&status=&page=&pageSize=

Non-US registries. registry ∈ GB-CH (UK Companies House, ~5.75M live companies) | TW-TWSE (Taiwan listed companies). q is a name prefix match or an exact registry number. One company: /api/v1/global/companies/{registry}/{number} (e.g. /global/companies/GB-CH/00445790, /global/companies/TW-TWSE/2330). Registry data is commons — any plan with API access.

/api/v1/filings?cik=|ticker=&form=&from=&to=&page=&pageSize=

Filing index, newest first. form e.g. 10-K, 8-K. Single filing: /api/v1/filings/{accessionNumber}.

/api/v1/facts?cik=|ticker=&tag=&taxonomy=&unit=&from=&to=&limit=

Raw XBRL facts. Filter by company and/or tag (e.g. tag=RevenueFromContractWithCustomerExcludingAssessedTax, tag=NetIncomeLoss, unit=USD). Duration facts carry periodStart; instant facts don't.

/api/v1/cot/{legacy|disaggregated|tff}?market=&variant=&from=&to=&limit=

COT weekly positions. market = contract code or name search (GOLD, 067651); variant 1 = futures-only, 2 = combined. Market catalog: /api/v1/cot/markets?q=.

POST /api/v1/subscriptions

The auto-collect trigger: subscribe to something and the system starts collecting it — including its full history — automatically (typically live within minutes).

curl -X POST -H "X-Api-Key: wm_..." -H "Content-Type: application/json" \
  -d '{"targetType":"Company","targetKey":"DE"}' \
  https://wolfmarket.freebranch.com/api/v1/subscriptions
# → 202 {"subscriptionId":42,"status":"Requested"}

targetType ∈ Company (ticker or CIK) | Bundle (commodity concept — corn, crude-oil, steel… one slot covers its prices, futures positioning, and cost indexes) | Series (series key) | CotMarket (contract code or name). Tracking an entity is also what entitles your key to query it. Track progress at /api/v1/subscriptions/{id}: Requested → Backfilling → Active. Requests that can't be resolved automatically are queued for operator review (NeedsReview) — nothing silently fails.

Point-in-time (asOf)

Publishers revise. WolfMarket keeps what a value said before it changed, so you can ask what you would have seen on a past date — essential when testing a rule against history. Add asOf= (an ISO timestamp) to /series/{seriesKey}/observations or to any /cot/* endpoint.

curl -H "X-Api-Key: wm_..." \
  "https://wolfmarket.freebranch.com/api/v1/series/JPCPI%3AHEADLINE/observations?asOf=2026-09-10T00:00:00Z"

The response meta then carries asOf, the number of values the request actually changed (restatedPoints, or restatedRows for COT), and vintagesFromUtc — when revision capture began: 2026-09-06 for series and 2026-09-13 for COT. Before those dates today's values are returned, so you can always tell "never revised" from "not yet recording".

Attribution — your obligations

These obligations are contractual: see section 6 of the Terms of Service.

Errors