Supra Core API — Public Client Documentation

Chapter 09 — Market Pair Endpoint

1. Purpose

GET /api/v1/market/pair returns one current market snapshot for an exact token, quote token, source scope, venue scope, and network.

Typical uses:

• token detail pages;
• focused price widgets;
• portfolio calculations;
• exact pair checks;
• scoped analytics comparisons.

---

2. Request

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

Missing token or quote returns 400.

---

3. Curl Examples

Default scope:

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

Explicit scope:

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

---

4. Successful Match

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>",
    "source_scope": "all",
    "dex_scope": "all",
    "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,
    "price_usd_confidence": "external_derived",
    "usd_valuation_as_of_utc": "<utc-timestamp-or-null>",
    "current_supply_onchain": "<decimal-string-or-null>",
    "market_cap_usd": "<decimal-string-or-null>",
    "fdv_usd": "<decimal-string-or-null>",
    "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/pair",
    "network": "mainnet",
    "source_scope": "all",
    "dex_scope": "all"
  }
}

The public row fields follow the current-market row contract documented in Chapter 08.

---

5. No Matching Row

When no exact row exists, the endpoint can return:

{
  "ok": true,
  "data": null,
  "meta": {
    "api_version": "v1",
    "endpoint": "market/pair",
    "network": "mainnet",
    "source_scope": "all",
    "dex_scope": "all"
  }
}

This is a valid 200 response, not a 404.

Possible reasons:

• the token/quote orientation is unavailable;
• the exact scope does not exist;
• no current derived row is available;
• an identifier does not match a public row.

data=null does not prove that the token has no activity or economic value. It means that no current row matches the exact requested pair, network, and scopes.

---

6. Token and Quote Orientation

The endpoint returns a pair-derived snapshot for the exact requested token and quote. The selected token is priced in units of the selected quote token.

Do not assume:

• the result is fiat-denominated;
• the result is automatically a USD price;
• a quote symbol containing USD, USDC, USDT, or similar text equals off-chain USD;
• latest_price is a universal token USD value;
• the reverse pair is identical;
• token A/quote B can be substituted for token B/quote A.

Keep token and quote identifiers attached to every stored or displayed price.

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

External market displays can use different routes, venues, filters, or valuation sources and are not guaranteed to match this exact pair snapshot.

---

7. Scope Matching

Default scope:

source_scope=all
dex_scope=all

Scope matching is exact. A narrower scope can return data=null even when an all row exists.

Treat returned scope labels as part of the market row identity.

---

8. Precision and Freshness

• Preserve latest_price, changes, and volumes as decimal strings when necessary.
• Use latest_event_time_utc for source-event recency.
• Use price_time_unix, price_time_utc, request-time age_seconds, and stale for explicit price freshness.
• Use stats_as_of_utc for snapshot calculation time.
• Use usd_valuation_as_of_* for the separate USD-target valuation time.
• Use current_supply_onchain_as_of_* for the separate supply observation time.
• Do not replace unavailable values with zero.
• The selected price is the newest structurally valid exact-pair evidence. Use explicit age/stale fields and support null when no structural candidate exists.
• The detail response uses exactly the same market row contract as market/current, including USD-target provenance, availability/reason fields, supply evidence, market cap, and FDV.
• change_24h_usd_pct never falls back to pair-denominated change_24h_pct.
• market_cap_usd uses current on-chain supply. fdv_usd uses maximum supply only and remains null when maximum supply is unavailable.

---

9. Error Handling

An exact no-match result remains HTTP 200 with data=null.

---

10. Client Recommendations

• Cache frequently requested pairs briefly.
• Do not expose the API key in a browser or mobile app.
• Display both token and quote symbols.
• Display scope when comparing rows.
• Label USD-like quotes as quote assets unless a separate true USD valuation contract is documented.
• Distinguish no match from request failure.
• Use the current listing endpoint to discover available rows when appropriate.

---

11. Scope and Data Exposure

The endpoint returns one matching pair snapshot or a successful response with data: null when no row matches. Its fields, nullability, confidence, and freshness semantics match the current-market contract.

---

12. Chapter Summary

Use /api/v1/market/pair for one exact current token/quote snapshot. Preserve orientation and scope, treat data=null as a valid no-match result, and interpret source-event time separately from snapshot as-of time.