Vai al contenuto
Tutti i capitoli della documentazione
In questa pagina

Supra Core API — Public Client Documentation

Chapter 05 — Response Format

1. Response Format Purpose

This chapter explains how clients should interpret the response format of the Supra Core API service.

It focuses on:

  • the common success and error envelopes;
  • object and list response shapes;
  • pagination with limit and offset;
  • nullable and optional values;
  • numeric precision;
  • Unix and ISO timestamp handling;
  • token, address, boolean, and status fields;
  • empty or stale data;
  • defensive client parsing.

The JSON snippets in this chapter are illustrative. They show stable client-side patterns, but they are not exhaustive schemas for every endpoint. Later endpoint chapters define the fields and filters specific to each resource.

2. JSON Response Format

The Supra Core API service returns JSON.

Clients should send:

Accept: application/json

An authenticated request may look like:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/health'

Recommended client behavior:

  1. inspect the HTTP status;
  2. parse the response body as JSON;
  3. inspect the top-level ok boolean;
  4. read data and meta for success;
  5. read error.code and error.message for failure.

Do not treat a syntactically valid JSON body as proof that the request succeeded.

3. Success Response Overview

The current common success envelope is:

{
  "ok": true,
  "data": {},
  "meta": {
    "api_version": "v1",
    "endpoint": "<endpoint-name>"
  }
}

The data value depends on the endpoint:

  • an object;
  • a list of objects;
  • null when an optional single resource is not found.

The meta object provides request or response context. Its fields can vary by endpoint.

3.1 Success does not imply non-empty data

These are valid success outcomes:

{
  "ok": true,
  "data": [],
  "meta": {
    "count": 0
  }
}

{
  "ok": true,
  "data": null,
  "meta": {
    "endpoint": "market/pair"
  }
}

A client must distinguish:

  • request success;
  • resource presence;
  • data freshness;
  • business-level usefulness.

4. Error Response Overview

The common error envelope is:

{
  "ok": false,
  "error": {
    "code": "<error-code>",
    "message": "<message>"
  }
}

Error messages are intentionally generic. Clients should not expect private diagnostics, infrastructure details, or debug traces.

Typical HTTP outcomes include:

HTTP status General meaning
400 Invalid or missing request parameter
401 Missing or invalid authentication
404 Route not found
405 HTTP method not allowed
429 Request rate limit exceeded
500 Internal API error

Client applications should primarily branch on HTTP status and error.code. Human-readable error.message text should be displayed or logged safely, but should not be used as the only programmatic discriminator.

4.1 Illustrative error

{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "A required parameter is missing."
  }
}

4.2 Request identifiers

If a future response includes a public request identifier such as <request-id>, preserve it in client logs and support requests. Do not assume it is present unless the endpoint documentation explicitly guarantees it.

5. Object Responses

Single-resource endpoints return an object in data.

Illustrative shape:

{
  "ok": true,
  "data": {
    "token_metadata": "<token-address>",
    "quote_token_metadata": "<quote-token-address>",
    "latest_price": "<decimal-string>",
    "price_time_unix": "<integer-or-null>",
    "price_time_utc": "<utc-timestamp-or-null>",
    "age_seconds": "<integer-or-null>",
    "stale": "<boolean-or-null>"
  },
  "meta": {
    "api_version": "v1",
    "endpoint": "market/pair"
  }
}

When a single optional resource is not found, data may be null while ok remains true:

{
  "ok": true,
  "data": null,
  "meta": {
    "api_version": "v1",
    "endpoint": "market/pair"
  }
}

Clients should not confuse a successful null result with an error response.

6. List Responses

Collection endpoints return an array in data.

Illustrative shape:

{
  "ok": true,
  "data": [
    {
      "token_symbol": "<token-symbol>",
      "quote_token_symbol": "<quote-token-symbol>",
      "latest_price": "<decimal-string>"
    }
  ],
  "meta": {
    "api_version": "v1",
    "endpoint": "market/current",
    "limit": 50,
    "offset": 0,
    "count": 1
  }
}

An empty list is valid:

{
  "ok": true,
  "data": [],
  "meta": {
    "api_version": "v1",
    "endpoint": "fa/swaps",
    "limit": 50,
    "offset": 0,
    "count": 0
  }
}

Do not interpret an empty list as an authentication failure or transport error.

7. Metadata and As-Of Fields

The meta object can describe the response context, including:

  • API version;
  • endpoint name;
  • network;
  • applied filters;
  • pagination values;
  • returned item count.

Illustrative metadata:

{
  "api_version": "v1",
  "endpoint": "candles",
  "network": "<network>",
  "limit": 100,
  "offset": 0,
  "count": 100
}

Data objects may also contain as-of fields such as:

{
  "stats_as_of_utc": "<iso-utc-timestamp>",
  "latest_event_time_utc": "<iso-utc-timestamp>"
}

These values answer different questions:

  • stats_as_of_utc indicates when a derived market snapshot was calculated;
  • latest_event_time_utc indicates the latest event represented by that row;
  • server_time_utc indicates the API server's current UTC time;
  • a candle boundary indicates the time interval represented by that candle.

Do not use server time as a substitute for data freshness.

8. Pagination Response Handling

Public list endpoints use limit and offset.

They do not currently use page_token.

Illustrative request:

GET <api-base>/api/v1/fa/swaps?limit=<limit>&offset=<offset>

Illustrative response metadata:

{
  "limit": 50,
  "offset": 100,
  "count": 50
}

8.1 Basic pagination loop

limit = 50
offset = 0

repeat:
    response = request(limit, offset)
    process(response.data)

    if length(response.data) < limit:
        stop

    offset = offset + limit

8.2 Pagination cautions

Offset pagination is simple but does not create an immutable snapshot. If new rows arrive while a client paginates:

  • items can move between pages;
  • a client can observe an item twice;
  • a client can miss an item.

For periodic ingestion:

  • use endpoint filters where available;
  • store stable identifiers such as <tx-hash> plus event position where documented;
  • process results idempotently;
  • allow a small overlap between polling windows;
  • deduplicate in the client when required.

Do not invent a page_token flow. If a future endpoint introduces one, follow that endpoint's documentation.

9. Nullable Fields

Many public fields are nullable.

A JSON null can mean:

  • the source event did not provide the value;
  • the value could not be resolved safely;
  • the field does not apply to that event type;
  • derived data is not yet available;
  • the selected protocol or flow does not expose that concept.

Illustrative response:

{
  "token_symbol": null,
  "amount": null,
  "farm_address": null
}

Recommended handling:

  • preserve null as unknown or not applicable;
  • do not replace it with zero;
  • do not invent a symbol;
  • do not copy an unrelated address into a missing field;
  • render a clear placeholder in user interfaces.

null, 0, "0", and "" are not interchangeable.

10. Missing and Optional Fields

The public contract is versioned, but clients should still parse defensively.

Unless an endpoint chapter explicitly marks a field as required:

  • tolerate its absence;
  • tolerate a null value;
  • ignore unknown additional fields;
  • avoid strict object-shape rejection.

Example:

price = data.latest_price if present
otherwise price = null

Do not silently continue when a field required by your own business logic is missing. Instead:

  1. record a safe diagnostic;
  2. skip or quarantine the affected item;
  3. retry only when appropriate;
  4. avoid guessing a replacement value.

Forward-compatible clients should ignore fields they do not understand.

11. Numeric Values and Precision

Numeric values can appear as JSON numbers or strings, depending on the field.

Examples:

{
  "swaps_count": 12,
  "block_height": 123456,
  "latest_price": "0.000123456789",
  "volume_quote_24h": "98765.43210000",
  "amount_raw": "1000000000000"
}

Typical guidance:

  • counts and bounded integer values can be JSON numbers;
  • large raw amounts may be strings;
  • decimal prices, amounts, percentages, and volumes may be strings;
  • clients must preserve precision.

11.1 Avoid binary floating-point loss

Do not immediately convert every decimal string to a binary floating-point type.

Prefer:

  • arbitrary-precision decimal libraries;
  • fixed-point integer arithmetic;
  • decimal types supplied by your language or database;
  • string preservation when only display or transport is required.

11.2 Raw and human-readable amounts

An endpoint can expose both:

{
  "amount_raw": "1000000",
  "amount": "1.000000",
  "token_decimals": 6
}

Treat the documented human-readable value as authoritative for display. When calculating from a raw amount, use the documented decimals and decimal-safe arithmetic.

11.3 Percentages

A percentage field such as change_24h_pct is a percentage value, not necessarily a fractional ratio.

Do not assume:

1 means 100%

Read the endpoint-specific definition before using a percentage in calculations.

12. Timestamp Handling

Public responses can include:

  • Unix timestamps;
  • ISO-formatted UTC timestamps;
  • named as-of timestamps;
  • candle boundary timestamps.

Illustrative shape:

{
  "event_time_unix": 1234567890,
  "event_time_utc": "<iso-utc-timestamp>",
  "stats_as_of_utc": "<iso-utc-timestamp>"
}

12.1 Unix values

A Unix timestamp represents seconds since the Unix epoch unless an endpoint explicitly states otherwise.

Clients should:

  • parse it as an integer;
  • avoid applying local timezone offsets before conversion;
  • preserve the original value when exact ordering matters.

12.2 ISO values

An ISO UTC timestamp typically ends in Z, for example:

<iso-utc-timestamp>

Treat it as UTC. Convert to a local timezone only for presentation.

12.3 Candle boundaries

For candles:

  • bucket_start_unix and bucket_start_utc identify the bucket start;
  • bucket_end_unix and bucket_end_utc identify the bucket end;
  • first and last event timestamps identify observed activity inside the bucket.

Do not use the latest event time as the candle boundary.

12.4 Freshness comparison

When checking data freshness, compare timestamps with equivalent meaning:

  • snapshot as-of time to snapshot expectations;
  • latest event time to expected event activity;
  • server time only to assess clock-relative delay.

13. Token and Address Fields

Token metadata and account-like addresses are identifiers, not display labels.

Examples:

{
  "token_metadata": "<token-address>",
  "quote_token_metadata": "<quote-token-address>",
  "wallet_address": "<wallet-address>",
  "tx_hash": "<tx-hash>"
}

Client rules:

  • preserve the full returned value;
  • compare identifiers case-insensitively only when the endpoint contract permits it;
  • do not trim leading zeroes;
  • do not reinterpret a token identifier as a wallet address;
  • do not infer a token symbol from a shortened address;
  • truncate identifiers only in visual presentation, never in storage or comparison.

Symbols are convenient labels but are not guaranteed to be globally unique.

Use metadata identifiers, not symbols alone, for stable filtering and equality checks.

14. Boolean and Status Fields

The top-level ok field is a JSON boolean:

{
  "ok": true
}

Do not parse it using truthy string behavior. The strings "true" and "false" are not substitutes for JSON booleans.

Status fields are strings with endpoint-specific meaning:

{
  "status": "<status>"
}

Recommended handling:

  • support the documented values;
  • preserve unknown future values;
  • avoid crashing when a new value appears;
  • do not infer overall HTTP success from a nested status field.

An HTTP 200 response with ok: true and a health status value are separate signals.

15. Empty, Delayed, or Stale Data

An API can be reachable while some datasets are empty, delayed, or older than expected.

Examples:

  • a newly tracked pair has no candles yet;
  • a filtered list has no matching swaps;
  • a market pair returns data: null;
  • the health endpoint is available while a derived dataset is behind;
  • a low-activity token has an old latest event timestamp.

Clients should evaluate data freshness explicitly.

Recommended checks:

  • inspect stats_as_of_utc for derived market rows;
  • inspect latest event timestamps;
  • inspect candle bucket times;
  • compare the newest item with your application's freshness threshold;
  • show “no data” separately from “request failed”;
  • avoid presenting an old value as live without a timestamp.

The health endpoint confirms service-level availability. A healthy response is not complete proof that every market, candle, swap, or liquidity dataset is current.

16. Illustrative Endpoint Family Snippets

The following snippets are intentionally compact. They demonstrate response parsing patterns, not complete endpoint schemas.

16.1 health

{
  "ok": true,
  "data": {
    "status": "<status>",
    "network": "<network>",
    "server_time_utc": "<iso-utc-timestamp>"
  },
  "meta": {
    "api_version": "v1",
    "endpoint": "health"
  }
}

16.2 market/current

{
  "ok": true,
  "data": [
    {
      "token_metadata": "<token-address>",
      "token_symbol": "<token-symbol>",
      "quote_token_metadata": "<quote-token-address>",
      "latest_price": "<decimal-string>",
      "latest_price_usd": "<decimal-string-or-null>",
      "change_24h_usd_pct": "<decimal-string-or-null>",
      "stats_as_of_utc": "<iso-utc-timestamp>"
    }
  ],
  "meta": {
    "endpoint": "market/current",
    "limit": 50,
    "offset": 0,
    "count": 1
  }
}

16.3 market/pair

{
  "ok": true,
  "data": {
    "token_metadata": "<token-address>",
    "quote_token_metadata": "<quote-token-address>",
    "latest_price": "<decimal-string>",
    "change_24h_pct": "<decimal-string-or-null>",
    "change_24h_usd_pct": "<decimal-string-or-null>",
    "market_cap_usd": "<decimal-string-or-null>",
    "fdv_usd": "<decimal-string-or-null>",
    "price_time_unix": "<integer-or-null>",
    "price_time_utc": "<utc-timestamp-or-null>",
    "age_seconds": "<integer-or-null>",
    "stale": "<boolean-or-null>"
  },
  "meta": {
    "endpoint": "market/pair"
  }
}

When no matching pair exists, data can be null.

16.4 candles

{
  "ok": true,
  "data": [
    {
      "granularity": "<granularity>",
      "bucket_start_unix": 1234567890,
      "bucket_start_utc": "<iso-utc-timestamp>",
      "open_price": "<decimal-string>",
      "high_price": "<decimal-string>",
      "low_price": "<decimal-string>",
      "close_price": "<decimal-string>",
      "is_final": true
    }
  ],
  "meta": {
    "endpoint": "candles",
    "limit": 100,
    "offset": 0,
    "count": 1
  }
}

16.5 chart/token

{
  "ok": true,
  "data": [
    {
      "bucket_start_unix": 1234567800,
      "close_price": "<decimal-string>",
      "synthetic": true,
      "has_events": false
    }
  ],
  "meta": {
    "endpoint": "chart/token",
    "range": "24h",
    "granularity": "5min",
    "gaps_filled": true,
    "max_points": 2500
  }
}

16.6 fa/swaps

{
  "ok": true,
  "data": [
    {
      "tx_hash": "<tx-hash>",
      "wallet_address": "<wallet-address>",
      "side": "<side>",
      "tracked_token_metadata": "<token-address>",
      "tracked_amount": "<decimal-string-or-null>"
    }
  ],
  "meta": {
    "endpoint": "fa/swaps",
    "limit": 50,
    "offset": 0,
    "count": 1
  }
}

16.7 legacy/swaps

{
  "ok": true,
  "data": [
    {
      "tx_hash": "<tx-hash>",
      "wallet_address": "<wallet-address>",
      "side": "<side>",
      "tracked_token_metadata": "<token-address>",
      "counter_token_metadata": "<quote-token-address>"
    }
  ],
  "meta": {
    "endpoint": "legacy/swaps",
    "limit": 50,
    "offset": 0,
    "count": 1
  }
}

16.8 fa/liquidity-events

{
  "ok": true,
  "data": [
    {
      "tx_hash": "<tx-hash>",
      "event_family": "<event-family>",
      "event_type": "<event-type>",
      "wallet_address": "<wallet-address>",
      "token0_amount": "<decimal-string-or-null>",
      "reward_amount": "<decimal-string-or-null>"
    }
  ],
  "meta": {
    "endpoint": "fa/liquidity-events",
    "limit": 50,
    "offset": 0,
    "count": 1
  }
}

16.9 legacy/liquidity-events

{
  "ok": true,
  "data": [],
  "meta": {
    "endpoint": "legacy/liquidity-events",
    "limit": 50,
    "offset": 0,
    "count": 0
  }
}

16.10 fa/burn-events

{
  "ok": true,
  "data": [
    {
      "tx_hash": "<tx-hash>",
      "token_metadata": "<token-address>",
      "amount_raw": "<integer-string>",
      "amount": "<decimal-string>",
      "block_time_available": true
    }
  ],
  "meta": {
    "endpoint": "fa/burn-events",
    "limit": 50,
    "offset": 0,
    "count": 1
  }
}

An empty array means the request succeeded but no matching public rows were returned.

17. Client Parsing Recommendations

Use the following parsing sequence:

response = send request

if response body is not valid JSON:
    treat as transport or gateway failure

if HTTP status is not successful:
    read error.code and error.message when available
    apply retry policy based on status

if body.ok is not true:
    treat as API failure

data = body.data
meta = body.meta if present, otherwise empty object

validate fields required by the client use case
preserve null values
preserve decimal precision
ignore unknown additional fields

17.1 Retry guidance

Retry decisions should use HTTP status:

  • do not repeatedly retry an invalid 400 request without changing it;
  • refresh or replace credentials after a persistent 401;
  • respect backoff for 429;
  • retry temporary server or network failures with bounded exponential backoff;
  • add jitter when multiple workers can retry together.

17.2 Typed model guidance

When using generated or strongly typed models:

  • mark nullable public fields as nullable;
  • model decimal values with string or decimal-safe types;
  • allow unknown status values;
  • make data endpoint-specific;
  • support data: null for optional object results;
  • support empty arrays for list results.

17.3 Logging guidance

Safe client logs can include:

  • endpoint name;
  • HTTP status;
  • public error.code;
  • request duration;
  • <request-id> if publicly returned;
  • pagination position;
  • non-secret filter values when appropriate.

Never log <api-key>.

18. Common Mistakes

18.1 Checking only HTTP 200

Always confirm valid JSON and ok: true.

18.2 Treating null as zero

Unknown amount, price, or decimals must remain unknown.

18.3 Parsing decimal strings as binary floats

This can silently lose precision.

18.4 Assuming every success contains data

data: [] and data: null are valid success outcomes.

18.5 Assuming health proves data freshness

Inspect the relevant as-of and event timestamps.

18.6 Ignoring pagination

A list response can be bounded even when more matching rows exist.

18.7 Inventing page_token

Current public list pagination uses limit and offset.

18.8 Comparing symbols as identities

Symbols can collide or change. Prefer token metadata identifiers.

18.9 Reformatting addresses before storage

Preserve the exact returned address and transaction identifier values.

18.10 Rejecting unknown fields

Forward-compatible clients should ignore additional response fields.

19. Scope and Data Exposure

The documented JSON envelopes, fields, nullability, and semantics form the client-visible contract. The Supra Core API service is read-only: a response grants no authority to modify data or administer the service.

20. Client Parsing Checklist

Before releasing an integration, verify that it:

  • requests and validates JSON;
  • checks HTTP status and top-level ok;
  • parses the success and error envelopes separately;
  • supports object, list, empty-list, and null data;
  • handles nullable and missing fields safely;
  • preserves numeric precision;
  • interprets Unix and ISO timestamps as UTC;
  • distinguishes server availability from data freshness;
  • uses limit and offset correctly;
  • does not assume a page_token;
  • stores full token metadata and address values;
  • ignores unknown additional fields;
  • applies bounded retry and backoff behavior;
  • never logs <api-key>;
  • uses only documented public fields and routes.

21. Summary

Supra Core public responses use JSON with a common success or error envelope.

Reliable clients should:

  • inspect HTTP status before consuming data;
  • use ok, data, meta, and error according to the response outcome;
  • treat empty and nullable values as valid states;
  • preserve decimal precision;
  • handle Unix and ISO timestamps carefully;
  • paginate with limit and offset;
  • evaluate data freshness from relevant timestamps;
  • parse defensively as the public API contract evolves compatibly.

The endpoint chapters that follow define the detailed request parameters and public fields for each resource family.