Supra Core API — Public Client Documentation

Chapter 08 — Market Current Endpoint

1. Purpose

GET /api/v1/market/current returns a bounded list of current token/quote market snapshots.

Typical uses:

• market overview tables;
• token discovery;
• activity and volume rankings;
• price-change dashboards;
• selecting a pair for a focused lookup.

It is a derived snapshot endpoint, not a streaming feed.

---

2. Request

GET /api/v1/market/current
X-API-Key: <api-key>

2.1 Query parameters

Values above the documented limit and offset caps are clamped. Invalid integer values return 400.

2.2 Allowed sort values

Unsupported sort values return 400.

---

3. Curl Examples

Latest rows:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/market/current?limit=<limit>&offset=<offset>&sort=latest_desc'

Exact token and quote:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/market/current?token=<token-address>&quote=<quote-token-address>'

---

4. Response Shape

The data value is an array. It can be empty.

Illustrative shortened response:

{
  "ok": true,
  "data": [
    {
      "network": "mainnet",
      "token_metadata": "<token-address>",
      "token_symbol": "<token-symbol>",
      "quote_token_metadata": "<quote-token-address>",
      "quote_token_symbol": "<quote-token-symbol>",
      "latest_price": "<decimal-string>",
      "change_24h_pct": "<decimal-string-or-null>",
      "latest_price_usd": "<decimal-string-or-null>",
      "change_24h_usd_pct": "<decimal-string-or-null>",
      "change_24h_usd_available": true,
      "change_24h_usd_reason": "available",
      "price_usd_confidence": "external_derived",
      "price_usd_reason": "available",
      "usd_valuation_as_of_unix": 0,
      "usd_valuation_as_of_utc": "<utc-timestamp-or-null>",
      "supra_usd_pair_key": "SUPRA_USDT",
      "supra_usd_quote_symbol": "USDT",
      "current_supply_onchain": "<decimal-string-or-null>",
      "market_cap_usd": "<decimal-string-or-null>",
      "fdv_usd": "<decimal-string-or-null>",
      "swaps_24h": 0,
      "volume_quote_24h": "<decimal-string-or-null>",
      "latest_event_time_utc": "<utc-timestamp-or-null>",
      "price_time_unix": "<integer-or-null>",
      "price_time_utc": "<utc-timestamp-or-null>",
      "age_seconds": "<integer-or-null>",
      "stale": "<boolean-or-null>",
      "stats_as_of_utc": "<utc-timestamp>"
    }
  ],
  "meta": {
    "api_version": "v1",
    "endpoint": "market/current",
    "network": "mainnet",
    "limit": 50,
    "offset": 0,
    "sort": "volume_24h_desc",
    "count": 1
  }
}

---

5. Public Row Fields

Rows can include:

• network;
• token_metadata, token_symbol, token_decimals;
• quote_token_metadata, quote_token_symbol, quote_token_decimals;
• source_scope, dex_scope;
• latest_price;
• latest_price_usd, reference_price_usd_24h, change_24h_usd_pct;
• change_24h_usd_available, change_24h_usd_reason;
• price_usd_confidence, price_usd_reason, price_usd_pair_stale;
• usd_valuation_as_of_unix, usd_valuation_as_of_utc, usd_valuation_age_seconds;
• current SUPRA USD-target evidence: supra_usd_price, supra_usd_pair_key, supra_usd_quote_symbol, supra_usd_source, supra_usd_source_confidence, supra_usd_provider_time_unix, supra_usd_observed_at_unix, supra_usd_stale;
• 24-hour reference evidence: reference_pair_stale_24h, reference_supra_usd_pair_key_24h, reference_supra_usd_quote_symbol_24h, reference_supra_usd_stale_24h, reference_price_usd_confidence_24h;
• change_15m_pct, change_1h_pct, change_4h_pct, change_24h_pct, change_7d_pct;
• swaps_24h, buys_24h, sells_24h;
• volume_token_24h, volume_quote_24h;
• latest_event_time_utc, price_time_unix, price_time_utc, age_seconds, stale;
• latest_block_height, latest_tx_hash;
• stats_as_of_utc;
• supply evidence: current_supply_onchain, current_supply_onchain_as_of_unix, current_supply_onchain_as_of_utc, current_supply_onchain_age_seconds, current_supply_onchain_stale, current_supply_onchain_confidence, current_supply_onchain_reason, maximum_supply, maximum_supply_available, maximum_supply_reason;
• valuation results: market_cap_usd, market_cap_available, market_cap_reason, market_cap_supply_basis, fdv_usd, fdv_available, fdv_reason, fdv_supply_basis.

Decimal values can be strings. Fields can be nullable.

---

6. Interpretation

6.1 Price orientation

latest_price is a pair-derived value that expresses the token in units of the quote token for the represented scopes. It is not a universal token price and is not automatically a fiat or true USD price.

It is the newest positive, structurally valid exact token/quote price. Volume thresholds and stale age do not replace it silently with an older candle. If no structurally valid candidate exists, latest_price and price-time fields can be null. Internal volume thresholds remain quality diagnostics rather than public price-selection rules.

A quote symbol containing USD, USDC, USDT, or similar text identifies an on-chain quote asset. The symbol alone does not establish that the value equals off-chain USD.

6.2 Freshness

• latest_event_time_utc describes the newest represented source event.
• price_time_unix and price_time_utc identify the effective timestamp used for the public price.
• age_seconds is calculated when the API response is produced.
• stale is true when that age exceeds the documented 72-hour quality threshold.
• stats_as_of_utc is the network-wide rolling-market calculation clock; it is not the pair's last-trade time.
• usd_valuation_as_of_* is the separate USD-target valuation clock.
• current_supply_onchain_as_of_* is the separate on-chain supply observation clock.

Handle a stale price as real but old evidence and a missing structurally valid price as unavailable rather than zero.

The USD-target value combines the persisted pair price with persisted external SUPRA anchor evidence. The current logical anchor identity can be SUPRA_USDT; this does not declare USD and USDT universally equivalent. Use the pair/quote provenance fields and confidence/reason fields exactly as returned.

6.3 Scope

Rows can include source_scope and dex_scope. This endpoint does not currently filter by those parameters. Use market/pair for an exact scoped lookup.

6.4 Percentage changes and external displays

change_24h_pct is pair-denominated. change_24h_usd_pct is the USD-target change and is the appropriate field for a USD-denominated page. The API never substitutes the pair change when the USD-target change is unavailable. The two values can legitimately differ because the external SUPRA anchor can change.

market_cap_usd uses current_supply_onchain; market_cap_supply_basis states that basis explicitly. fdv_usd uses maximum_supply. It does not fall back to current or total supply. Missing price or supply leaves the result null with its availability and reason fields.

---

7. Pagination

Use limit and offset. Do not use page_token.

Stop when:

• data is empty; or
• the returned row count is less than limit.

Changing activity can affect offset-based pagination. Avoid treating it as an immutable historical snapshot.

---

8. Empty and Error Results

data=[] with HTTP 200 is a valid result.

---

9. Client Recommendations

• Cache common pages briefly.
• Keep the key on a trusted backend.
• Preserve decimal strings.
• Show quote symbol and freshness context.
• Do not treat a USD-like quote symbol as proof of true USD valuation.
• Treat nullable market cap and FDV as unavailable, never as zero.
• Do not infer current liquidity or TVL; reserve-backed liquidity is not part of this endpoint.
• Do not poll every row independently.

---

10. Scope and Data Exposure

The endpoint returns documented current-market rows together with availability, confidence, and freshness fields. Unavailable values remain null or explicitly flagged according to the field contract.

---

11. Chapter Summary

Use /api/v1/market/current for bounded current-market listings. Apply exact filters, choose an allowlisted sort, paginate with limit and offset, preserve decimal precision, and interpret event time separately from snapshot as-of time.