Public API Docs

Vatic API Documentation

Vatic API provides target-price data for supported crypto assets across multiple time intervals. Use timestamp and range endpoints to retrieve point-in-time values, normalized market windows, and provider-specific source data.

Base URLhttps://api.vatic.tradingOpen

This API returns target prices for supported assets across predefined intervals. Some intervals are Chainlink-backed and others Binance-backed. All timestamps can be sent as unix seconds, unix milliseconds, or ISO datetime strings.

Quick Start Endpoint Reference Errors Rate Limits FAQ

Quick Start

GET

curl "https://api.vatic.trading/health"

GET

curl "https://api.vatic.trading/api/v1/targets/active?asset=btc&types=5min,15min,1hour"

GET

curl "https://api.vatic.trading/api/v1/targets/timestamp?asset=eth&type=1hour&timestamp=1771531200"

Authentication

No API key is currently required for read endpoints. Clients should still handle rate limiting and retries gracefully. Rate limiting headers are returned on API responses.

Core Concepts

Assets

Supported assets: btc, eth, sol, xrp, hype, doge, bnb.

Intervals

Canonical: 5min, 15min, 1hour, 4hour, daily. Aliases: 5m, 15m, 1h/1hr, 4h, day.

Provider Mapping

Chainlink intervals: 5min, 15min, 4hour. Binance intervals: 1hour, daily (HYPE 1hour/daily routes to Binance Futures).

Timestamp Formats

Timestamps accept unix seconds, unix milliseconds, or ISO strings.

Boundary alignment: history endpoints align provided timestamps to interval market boundaries.

Endpoint Reference

Timestamp examples currently use 1771531200.

GET

Health

mixed

Service liveness check.

Path/health

Parameters

Name	Required	Type	Allowed Values	Default

Example Request

curl "https://api.vatic.trading/health"

Sample Success Response

{
  "ok": true,
  "service": "vatic-api",
  "now": "2026-02-20T12:00:00.000Z"
}

Sample Error Response

{
  "error": "Service unavailable",
  "hint": "Retry shortly"
}

Common Errors

502 upstream service health dependency issues

GET

Active Target Prices

mixed

Fetch latest active target prices for one asset and one or many intervals.

Path/api/v1/targets/active

Parameters

Name	Required	Type	Allowed Values	Default
asset	No	string	btc\|eth\|sol\|xrp\|hype\|doge\|bnb	btc
types	No	csv	5min,15min,1hour,4hour,daily	—

Example Request

curl "https://api.vatic.trading/api/v1/targets/active?asset=btc&types=5min,15min,1hour"

Sample Success Response

{
  "now": "2026-02-20T12:00:00.000Z",
  "asset": "btc",
  "results": [
    {
      "marketType": "5min",
      "ok": true,
      "windowStart": 1771531200,
      "windowStartIso": "2026-02-20T12:00:00.000Z",
      "source": "chainlink",
      "price": 96420.34
    }
  ]
}

Sample Error Response

{
  "error": "Invalid asset",
  "hint": "Supported assets: btc,eth,sol,xrp,hype,doge,bnb"
}

Common Errors

400 invalid asset
400 invalid types list
502 upstream provider issues

GET

Chainlink Timestamp Lookup

chainlink

Fetch one target price for one timestamp on Chainlink-backed intervals.

Path/api/v1/targets/chainlink

Parameters

Name	Required	Type	Allowed Values	Default
asset	Yes	string	btc\|eth\|sol\|xrp\|hype\|doge\|bnb	—
type	Yes	string	5min\|15min\|4hour	—
timestamp	Yes	string\|number	unix sec/ms or ISO datetime	—

Example Request

curl "https://api.vatic.trading/api/v1/targets/chainlink?asset=btc&type=15min&timestamp=1771531200"

Sample Success Response

{
  "now": "2026-02-20T12:00:00.000Z",
  "asset": "btc",
  "marketType": "15min",
  "requestedTimestamp": 1771531200,
  "requestedTimestampIso": "2026-02-20T12:00:00.000Z",
  "source": "chainlink",
  "price": 96312.8
}

Sample Error Response

{
  "error": "Invalid type for chainlink endpoint",
  "hint": "Supported types: 5min,15min,4hour"
}

Common Errors

400 invalid asset/type/timestamp
502 upstream provider failure

GET

Universal Timestamp Lookup

auto

Single timestamp lookup across all intervals with provider auto-selection.

Path/api/v1/targets/timestamp

Parameters

Name	Required	Type	Allowed Values	Default
asset	Yes	string	btc\|eth\|sol\|xrp\|hype\|doge\|bnb	—
type	Yes	string	5min\|15min\|1hour\|4hour\|daily	—
timestamp	Yes	string\|number	unix sec/ms or ISO datetime	—

Example Request

curl "https://api.vatic.trading/api/v1/targets/timestamp?asset=eth&type=1hour&timestamp=1771531200"

Sample Success Response

{
  "now": "2026-02-20T12:00:00.000Z",
  "asset": "eth",
  "marketType": "1hour",
  "provider": "binance",
  "requestedTimestamp": 1771531200,
  "requestedTimestampIso": "2026-02-20T12:00:00.000Z",
  "source": "aggTrades",
  "price": 3212.17
}

Sample Error Response

{
  "error": "Invalid timestamp",
  "hint": "Use unix seconds, unix milliseconds, or ISO datetime"
}

Common Errors

400 invalid asset/type/timestamp
429 rate limit exceeded
502 upstream failure

GET

Batch Timestamp Lookup

auto

One timestamp and one interval for multiple assets in one request.

Path/api/v1/targets/timestamp/batch

Parameters

Name	Required	Type	Allowed Values	Default
assets	No	csv	btc,eth,sol,xrp,hype,doge,bnb	all supported assets
type	Yes	string	5min\|15min\|1hour\|4hour\|daily	—
timestamp	Yes	string\|number	unix sec/ms or ISO datetime	—

Example Request

curl "https://api.vatic.trading/api/v1/targets/timestamp/batch?assets=btc,eth,sol,xrp,hype,doge,bnb&type=1hour&timestamp=1771531200"

Sample Success Response

{
  "now": "2026-02-20T12:00:00.000Z",
  "marketType": "1hour",
  "provider": "binance",
  "requestedTimestamp": 1771531200,
  "requestedTimestampIso": "2026-02-20T12:00:00.000Z",
  "results": [
    {
      "asset": "btc",
      "ok": true,
      "source": "aggTrades",
      "price": 96420.34
    },
    {
      "asset": "eth",
      "ok": true,
      "source": "aggTrades",
      "price": 3212.17
    }
  ]
}

Sample Error Response

{
  "error": "Invalid assets list",
  "hint": "Supported assets: btc,eth,sol,xrp,hype,doge,bnb"
}

Common Errors

400 invalid type/timestamp
429 too many requests
502 provider issues

GET

Market Timestamps for UTC Day

mixed

List all market windows for a UTC day with slug and Polymarket URL.

Path/api/v1/markets/timestamps

Parameters

Name	Required	Type	Allowed Values	Default
asset	No	string	btc\|eth\|sol\|xrp\|hype\|doge\|bnb	btc
interval or intervals	No	string\|csv	5min,15min,1hour,4hour,daily or aliases	—
date or day+month+year	Yes	string	date=YYYY-MM-DD OR day/month/year	—

Example Request

curl "https://api.vatic.trading/api/v1/markets/timestamps?asset=xrp&intervals=5m,15m,1hour,4h,daily&date=2026-02-16"

Sample Success Response

{
  "now": "2026-02-20T12:00:00.000Z",
  "asset": "xrp",
  "utc_date": "2026-02-16",
  "day_start_unix": 1771200000,
  "day_end_unix": 1771286399,
  "intervals": [
    "5min",
    "15min",
    "1hour",
    "4hour",
    "daily"
  ],
  "data": {
    "15min": {
      "count": 96,
      "chronological_order": [
        {
          "timestamp_start": 1771200000,
          "timestamp_end": 1771200899,
          "start_iso": "2026-02-16T00:00:00.000Z",
          "end_iso": "2026-02-16T00:14:59.000Z",
          "slug": "xrp-15m-2026-02-16-0000",
          "url": "https://polymarket.com/event/xrp-15m-2026-02-16-0000"
        }
      ]
    }
  }
}

Sample Error Response

{
  "error": "Invalid date input",
  "hint": "Use date=YYYY-MM-DD or day/month/year"
}

Common Errors

400 invalid interval/date
400 unsupported asset

GET

History for Single Market Window

auto

Return one aligned market window and its datapoint.

Path/api/v1/history/market

Parameters

Name	Required	Type	Allowed Values	Default
asset	No	string	btc\|eth\|sol\|xrp\|hype\|doge\|bnb	btc
type	Yes	string	5min\|15min\|1hour\|4hour\|daily (+ aliases)	—
marketStart\|start\|timestamp	Yes	string\|number	unix sec/ms or ISO datetime	—

Example Request

curl "https://api.vatic.trading/api/v1/history/market?asset=btc&type=15m&marketStart=1771531200"

Sample Success Response

{
  "now": "2026-02-20T12:00:00.000Z",
  "asset": "btc",
  "marketType": "15min",
  "provider": "chainlink",
  "market": {
    "timestamp_start": 1771531200,
    "timestamp_end": 1771532099,
    "start_iso": "2026-02-20T12:00:00.000Z",
    "end_iso": "2026-02-20T12:14:59.000Z",
    "slug": "btc-15m-2026-02-20-1200",
    "url": "https://polymarket.com/event/btc-15m-2026-02-20-1200"
  },
  "datapoint": {
    "source": "chainlink",
    "price": 96418.55
  }
}

Sample Error Response

{
  "error": "Invalid timestamp",
  "hint": "history/market aligns timestamps to interval boundaries"
}

Common Errors

400 invalid type/timestamp
502 provider timeout

GET

History Range (Normalized Market Points)

auto

Return one point per market boundary within a range.

Path/api/v1/history/range

Parameters

Name	Required	Type	Allowed Values	Default
asset	No	string	btc\|eth\|sol\|xrp\|hype\|doge\|bnb	btc
type	Yes	string	5min\|15min\|1hour\|4hour\|daily (+ aliases)	—
start	Yes	string\|number	unix sec/ms or ISO datetime	—
end	Yes	string\|number	unix sec/ms or ISO datetime	—

Example Request

curl "https://api.vatic.trading/api/v1/history/range?asset=btc&type=1hour&start=1771531200&end=1771617600"

Sample Success Response

{
  "now": "2026-02-20T12:00:00.000Z",
  "asset": "btc",
  "marketType": "1hour",
  "provider": "binance",
  "range": {
    "start": 1771531200,
    "end": 1771617600,
    "startIso": "2026-02-20T12:00:00.000Z",
    "endIso": "2026-02-21T12:00:00.000Z"
  },
  "count": 24,
  "history": [
    {
      "timestamp_start": 1771531200,
      "timestamp_end": 1771534799,
      "start_iso": "2026-02-20T12:00:00.000Z",
      "end_iso": "2026-02-20T12:59:59.000Z",
      "slug": "btc-1h-2026-02-20-1200",
      "url": "https://polymarket.com/event/btc-1h-2026-02-20-1200",
      "ok": true,
      "source": "aggTrades",
      "price": 96400.11
    }
  ],
  "timeseries": [
    {
      "timestamp_start": 1771531200,
      "price": 96400.11
    }
  ]
}

Sample Error Response

{
  "error": "Invalid range. end must be greater than start",
  "hint": "Reduce range size if max points exceeded"
}

Common Errors

400 invalid range/type
400 max points exceeded
429 rate limit

GET

Binance-Only History Range

binance

Explicit Binance-only retrieval for 1hour and daily intervals.

Path/api/v1/history/binance/range

Parameters

Name	Required	Type	Allowed Values	Default
asset	No	string	btc\|eth\|sol\|xrp\|hype\|doge\|bnb	btc
type	Yes	string	1hour\|daily	—
start	Yes	string\|number	unix sec/ms or ISO datetime	—
end	Yes	string\|number	unix sec/ms or ISO datetime	—
mode	No	string	market\|source	market
includeOutcomeMeta	No	boolean	true\|false	false

Example Request

curl "https://api.vatic.trading/api/v1/history/binance/range?asset=btc&type=daily&start=1771476781&end=1771563706&mode=source&includeOutcomeMeta=true"

Sample Success Response

{
  "now": "2026-02-20T12:00:00.000Z",
  "asset": "btc",
  "marketType": "daily",
  "provider": "binance",
  "mode": "source",
  "method": "klines_1m",
  "points": [
    {
      "timestamp": 1771476840,
      "timestamp_iso": "2026-02-19T22:14:00.000Z",
      "source": "klines_1m",
      "price": 96102.43
    }
  ]
}

Sample Error Response

{
  "error": "Invalid mode for endpoint",
  "hint": "Use mode=market or mode=source"
}

Common Errors

400 invalid type or mode
400 invalid range
502 binance upstream issues

mode=market returns normalized windows in history[]. mode=source returns denser provider points in points[]. Method labels: aggTrades (1hour), klines/klines_1m (daily).

GET

Chainlink-Only History Range

chainlink

Explicit Chainlink-only range retrieval.

Path/api/v1/history/chainlink/range

Parameters

Name	Required	Type	Allowed Values	Default
asset	No	string	btc\|eth\|sol\|xrp\|hype\|doge\|bnb	btc
type	Yes	string	5m\|15m\|4h (+ aliases)	—
start	Yes	string\|number	unix sec/ms or ISO datetime	—
end	Yes	string\|number	unix sec/ms or ISO datetime	—
mode	No	string	market\|source	market
includeOutcomeMeta	No	boolean	true\|false	false

Example Request

curl "https://api.vatic.trading/api/v1/history/chainlink/range?asset=btc&type=15m&start=1771531200&end=1771534800&mode=source"

Sample Success Response

{
  "now": "2026-02-20T12:00:00.000Z",
  "asset": "btc",
  "marketType": "15min",
  "provider": "chainlink",
  "mode": "source",
  "method": "getReportsPage",
  "points": [
    {
      "timestamp": 1771531500,
      "timestamp_iso": "2026-02-20T12:05:00.000Z",
      "source": "chainlink",
      "price": 96388.5
    }
  ]
}

Sample Error Response

{
  "error": "Invalid type for chainlink range",
  "hint": "Supported chainlink range types: 5m,15m,4h"
}

Common Errors

400 invalid mode/type
400 invalid range
502 chainlink upstream issues

mode=market returns boundary-aligned history[] via getReportByTimestamp. mode=source returns denser points[] via getReportsPage.

GET

Timeseries Alias Endpoints

mixed

Compatibility aliases that mirror history endpoints.

Path/api/v1/timeseries/market and /api/v1/timeseries/range

Parameters

Name	Required	Type	Allowed Values	Default
(same params)	Yes	same-as-history	market alias -> /history/market, range alias -> /history/range	—

Example Request

curl "https://api.vatic.trading/api/v1/timeseries/range?asset=btc&type=1hour&start=1771531200&end=1771617600"

Sample Success Response

{
  "alias": true,
  "mappedTo": "/api/v1/history/range",
  "behavior": "Same response schema as history endpoints"
}

Sample Error Response

{
  "error": "Bad parameters",
  "hint": "Validate the same fields required by corresponding history endpoint"
}

Common Errors

Same 400/429/502 behaviors as underlying history endpoints

GET

Event Taker-Fee Config (By Event Slug)

mixed

Return whether an event has taker fees and the inferred fee model from event tags.

Path/api/v1/fees/event/slug/:eventSlug

Parameters

Name	Required	Type	Allowed Values	Default
eventSlug	Yes	path	Any valid polymarket event slug	—

Example Request

curl "https://api.vatic.trading/api/v1/fees/event/slug/btc-updown-5m-1771879500"

Sample Success Response

{
  "now": "2026-03-07T12:00:00.000Z",
  "event": {
    "id": "203952",
    "slug": "btc-updown-5m-1771879500",
    "title": "Bitcoin Up or Down - 5m"
  },
  "hasTakerFees": true,
  "type": "crypto",
  "feeRate": 0.25,
  "exponent": 2,
  "makerRebate": "20%",
  "matchedByTag": "5m"
}

Sample Error Response

{
  "error": "Event not found for slug: <slug>",
  "hint": "Failed to fetch event metadata from Gamma API by slug"
}

Common Errors

400 missing eventSlug
502 upstream event lookup failed

Tag matching: anyTags(5m,15m,1h,1hr,hourly,4h,4hour) OR allTags(daily+crypto) OR allTags(weekly+crypto) => crypto fee model (feeRate=0.25, exponent=2, makerRebate=20%). anyTags(sea,seas,ncaab) => feeRate=0.0175, exponent=1, makerRebate=25%. No match => hasTakerFees=false.

GET

Event Taker-Fee Config (By Event ID)

mixed

Same fee-config resolution as slug endpoint, using event id.

Path/api/v1/fees/event/id/:eventId

Parameters

Name	Required	Type	Allowed Values	Default
eventId	Yes	path	Polymarket event id (string or numeric id)	—

Example Request

curl "https://api.vatic.trading/api/v1/fees/event/id/203952"

Sample Success Response

{
  "now": "2026-03-07T12:00:00.000Z",
  "event": {
    "id": "203952",
    "slug": "example-event-slug",
    "title": "Example Event"
  },
  "hasTakerFees": true,
  "type": "crypto",
  "feeRate": 0.0175,
  "exponent": 1,
  "makerRebate": "25%",
  "matchedByTag": "ncaab"
}

Sample Error Response

{
  "error": "Event not found for id: <id>",
  "hint": "Failed to fetch event metadata from Gamma API by id"
}

Common Errors

400 missing eventId
502 upstream event lookup failed

Same tag rules as slug endpoint. If no matching rule, response is { hasTakerFees: false } (plus event metadata).

POST

Trade Fee Estimate (Fee + Net Executable)

mixed

Estimate taker fee and net executable amount for BUY/SELL trades using event fee config.

Path/api/v1/fees/trade-estimate

Parameters

Name	Required	Type	Allowed Values	Default
eventId or eventSlug	Yes	json-body	One is required to resolve fee model	—
side	Yes	json-body	BUY\|SELL	—
makingAmount	Yes	json-body number	positive number	—
takingAmount	Yes	json-body number	positive number	—

Example Request

curl -X POST "https://api.vatic.trading/api/v1/fees/trade-estimate" \
  -H "Content-Type: application/json" \
  -d '{"eventSlug":"btc-updown-5m-1771879500","side":"BUY","makingAmount":1.999999,"takingAmount":4.651161}'

Sample Success Response

{
  "now": "2026-03-07T12:00:00.000Z",
  "event": {
    "id": "203952",
    "slug": "btc-updown-5m-1771879500",
    "title": "Bitcoin Up or Down - 5m"
  },
  "feeConfig": {
    "hasTakerFees": true,
    "type": "crypto",
    "feeRate": 0.25,
    "exponent": 2,
    "makerRebate": "20%",
    "matchedByTag": "5m"
  },
  "side": "BUY",
  "inputs": {
    "makingAmount": 1.999999,
    "makingAmountUnit": "usdc",
    "takingAmount": 4.651161,
    "takingAmountUnit": "shares"
  },
  "averagePrice": 0.4299,
  "fee": {
    "chargedIn": "shares",
    "feeEquivalent": 0.0107,
    "feeInUsdcRaw": 0.0046,
    "minFeeThresholdUsdc": 0.0001
  },
  "result": {
    "grossShares": 4.651161,
    "netShares": 4.6405
  }
}

Sample Error Response

{
  "error": "Provide eventId or eventSlug",
  "hint": "Failed to resolve event fee configuration from Gamma API"
}

Common Errors

400 missing eventId/eventSlug
400 invalid side (BUY|SELL)
400 invalid/non-positive amounts
502 upstream event lookup failed

BUY: makingAmount=USDC, takingAmount=shares, fee charged in shares. SELL: makingAmount=shares, takingAmount=USDC, fee charged in USDC. Formula uses feeRate and exponent from matched event fee rule. If feeInUsdcRaw < 0.0001, fee is treated as 0.

Response & Error Conventions

Shared response fields

Common fields include now, asset, marketType, provider, requestedTimestamp, requestedTimestampIso, source, price, history, and timeseries.

Error model

{
  "error": "...",
  "hint": "..."
}

400 bad parameters (asset/type/timestamp/range)
429 rate limit exceeded
502 upstream/provider issues

Range limits: large start/end spans can fail with max-points or range-size errors.

Source vs Market mode: source mode can return denser payloads than market mode.

Rate Limits & Caching

Rate limiting is enforced per client IP. Inspect response headers (X-RateLimit-*) to monitor remaining quota.

Header	Description
X-Request-Id	Unique request identifier for tracing.
X-RateLimit-Limit	Quota limit for the current window.
X-RateLimit-Remaining	Remaining requests in current window.
X-RateLimit-Reset	Unix timestamp when the limit window resets.
X-Cache	Cache status indicator (HIT or MISS).

FAQ / Integration Notes

Timestamp tips: Prefer unix seconds for compact URLs; use ISO strings when debugging readability.

Choosing market vs source mode: use market for aligned window outcomes and source for raw, denser provider output.

Range sizing guidance: request smaller ranges first, then page or chunk for larger backfills to avoid max-point limits.