Supra Core API — Public Client Documentation

Chapter 17 — Integration Guide

1. Purpose

This chapter provides practical integration best practices for building safe and reliable Supra Core API clients.

It covers:

• recommended client architecture;
• backend proxy responsibilities;
• browser and mobile safety;
• caching;
• polling;
• pagination;
• retry and backoff;
• data freshness;
• numeric precision;
• timestamp handling;
• combining endpoint families;
• UI states;
• logging and redaction;
• integration testing.

It does not replace the endpoint-specific chapters. Use those chapters for exact parameters, fields, filters, and semantics.

---

2. Integration Principles

2.1 Keep API keys server-side

The X-API-Key value belongs in a trusted backend, proxy, bot server, or analytics job.

Do not expose it to:

• browser JavaScript;
• mobile application bundles;
• public source code;
• URLs;
• screenshots;
• logs;
• client-visible configuration.

2.2 Use HTTPS

Send requests only to the HTTPS <api-base> supplied for your access.

2.3 Parse JSON defensively

Clients should:

• inspect HTTP status;
• parse JSON when present;
• check top-level ok;
• support object, list, empty-list, and null data;
• tolerate nullable and added fields;
• reject only when a field required by the client use case is unusable.

2.4 Preserve numeric precision

Prices, amounts, percentages, and volumes can be decimal strings.

Do not force every numeric-looking value into a low-precision float.

2.5 Cache repeated reads

Reuse responses when several users or components need the same data.

2.6 Handle rate limits

On 429:

• reduce request volume;
• apply backoff and jitter;
• coordinate workers;
• avoid immediate retry loops.

2.7 Handle stale and empty data

An empty array can be valid. A successful health response does not prove complete data freshness.

2.8 Avoid unsupported features

Do not assume support for:

• WebSocket;
• streaming;
• write endpoints;
• trading or order placement;
• wallet signing;
• staking or farming actions;
• private account management;
• page_token.

2.9 Do not overinterpret derived data

Market, candle, swap, and liquidity data has endpoint-specific meaning.

Do not:

• treat a candle as a live quote;
• treat a pair-derived price as a universal or true USD price;
• treat an on-chain USD-like quote symbol as proof that the quote equals off-chain USD;
• expect change_24h_pct or change_7d_pct to match every external market display;
• treat liquidity activity as a swap;
• treat BUY or SELL as complete wallet intent;
• treat a health response as proof that every dataset is current.

Clients requiring true USD valuation need a separately documented USD source or valuation layer. Do not derive portfolio USD totals merely from a USD-like symbol.

---

3. Recommended Architecture

Use:

<client-app> or frontend or mobile
    -> <backend-url>
    -> Supra Core at <api-base>

Detailed flow:

user action
    -> public client calls client-owned backend
    -> backend validates request
    -> backend reads <api-key> from protected storage
    -> backend calls Supra Core with X-API-Key
    -> backend validates and optionally caches response
    -> backend returns UI-safe data to client

The frontend never receives the upstream API key.

3.1 Why this pattern matters

A client-owned backend can:

• protect credentials;
• validate user input;
• centralize caching;
• coordinate polling;
• apply application-level rate limits;
• normalize UI output;
• redact logs;
• hide unnecessary upstream details.

Important: Obfuscating a key in frontend code does not protect it.

---

4. Backend Proxy Responsibilities

4.1 Store the key securely

Keep <api-key> in protected server-side secret storage.

4.2 Validate incoming requests

Allow only:

• required application routes;
• documented parameter names;
• safe parameter lengths;
• supported values;
• bounded pagination and ranges.

4.3 Call the Supra Core API Service

The backend should add:

Accept: application/json
X-API-Key: <api-key>

4.4 Validate upstream responses

Check:

• HTTP status;
• valid JSON;
• top-level ok;
• endpoint-specific data;
• required client fields.

4.5 Cache safe responses

Cache by all request dimensions that affect the response, such as:

• endpoint;
• network;
• token and quote;
• scope;
• granularity;
• filters;
• pagination position.

4.6 Redact logs

Never log the API key or full secret-bearing headers.

4.7 Normalize UI-safe output

The backend can:

• remove fields the frontend does not need;
• convert timestamps for display;
• retain canonical raw values for calculation;
• attach a safe stale-data indicator;
• retain and display the quote asset for every pair-derived price;
• preserve source family.

4.8 Enforce application limits

Protect your backend from:

• unbounded client pagination;
• rapid repeated searches;
• excessive date ranges;
• high fan-out requests;
• cache bypass.

4.9 Avoid exposing upstream errors directly

Return a safe application message while preserving redacted diagnostic context in server-side logs.

---

5. Server-Side Bot and Analytics Architecture

Trusted bots and analytics jobs can call the API directly from a protected server environment.

Recommended flow:

scheduled or event-driven job
    -> load <api-key> securely
    -> call required <endpoint>
    -> validate status and JSON
    -> cache or process response
    -> store only application-required results
    -> emit redacted metrics and logs

5.1 Schedule responsibly

Avoid running every job at the same second.

Use:

• staggered schedules;
• random jitter;
• a shared scheduler;
• bounded concurrency;
• one fetch shared by multiple consumers.

5.2 Cache results

If several reports use the same response, fetch it once and reuse it.

5.3 Monitor status codes

Track:

• success rate;
• 401;
• 429;
• 500;
• request duration;
• empty response frequency;
• latest represented timestamp or block where relevant.

5.4 Redact logs

Do not print:

• X-API-Key;
• full request headers;
• secret environment values;
• unreviewed response dumps.

---

6. Frontend and Browser Guidance

6.1 Do not embed the key

Do not place X-API-Key in:

• JavaScript bundles;
• frontend environment variables;
• HTML;
• browser local storage;
• service workers;
• browser requests to Supra Core.

6.2 Call your own backend

Frontend request:

GET <backend-url>/<client-safe-route>

Your backend calls:

GET <api-base>/api/v1/<endpoint>
X-API-Key: <api-key>

6.3 Debounce user actions

For search, filtering, chart updates, or pagination:

• wait briefly after input;
• cancel obsolete requests;
• ignore responses for an older selection;
• avoid one upstream request per keystroke.

6.4 Display data states clearly

Support:

• loading;
• loaded;
• no data;
• stale or last known;
• rate limited;
• authentication setup issue;
• temporary service error.

---

7. Mobile App Guidance

7.1 Do not embed long-lived keys

Assume secrets in a mobile application can be extracted from:

• application bundles;
• runtime memory;
• debug logs;
• network instrumentation;
• modified devices.

7.2 Use a backend session

Recommended flow:

mobile app
    -> authenticated session with <backend-url>
    -> backend calls <api-base>

7.3 Replace exposed keys

If a key is included in a released application or public diagnostic:

1. treat it as exposed;
2. stop relying on it;
3. follow the provider's credential replacement process;
4. update the protected backend;
5. verify the old credential is no longer used.

7.4 Redact mobile logs

Do not log:

• API keys;
• full headers;
• secret-bearing URLs;
• unredacted upstream responses.

---

8. Caching Strategy

Caching reduces latency, request volume, and rate-limit risk.

8.1 No universal TTL

Choose <cache-ttl> according to:

• endpoint type;
• expected update frequency;
• user expectations;
• acceptable staleness;
• cost of refetching;
• whether the data is historical or recent.

Do not treat a suggested cache pattern as a freshness guarantee.

8.2 Cache key design

Include every response-affecting parameter.

Illustrative cache key:

endpoint=<endpoint>
network=<network>
token=<token-address>
quote=<quote-token-address>
granularity=<granularity>
limit=<limit>
offset=<offset>
filters=<normalized-safe-filters>

8.3 Do not cache secrets in public clients

Never cache <api-key> in:

• browser storage;
• mobile preference storage;
• frontend state;
• public CDN objects.

8.4 Invalidation

Possible strategies:

• time-based expiration;
• replace recent pages on refresh;
• retain immutable-looking historical pages longer;
• invalidate when user filters change;
• serve stale data briefly during a temporary failure with a visible stale label.

---

9. Polling Strategy

9.1 Avoid tight loops

Do not call an endpoint continuously without delay.

9.2 Use sensible intervals

Choose polling frequency according to:

• endpoint purpose;
• user visibility;
• expected activity;
• cache behavior;
• rate-limit budget.

9.3 Stagger jobs

Avoid synchronized bursts from:

• scheduled jobs;
• application replicas;
• browser sessions;
• bot workers.

Add jitter around scheduled start times.

9.4 Back off after errors

Apply bounded backoff for 429, 500, and temporary transport failures.

9.5 Avoid repeated full-history reads

For candles, swaps, and liquidity:

• cache historical pages;
• request only needed ranges;
• use block or time filters where supported;
• avoid fetching every page on every refresh.

9.6 Prefer incremental reads

Use documented filters plus limit and offset to reduce work.

Because offset pagination can shift when new rows appear, deduplicate client-side where appropriate.

9.7 Not a streaming feed

Polling faster does not turn the API into a streaming interface.

---

10. Pagination Strategy

Current list endpoints use:

• limit;
• offset.

They do not currently use page_token.

10.1 Language-agnostic pseudo-code

limit = <limit>
offset = 0
maximum_pages = <safe-maximum-pages>
page_number = 0

while page_number < maximum_pages:
    response = request(
        endpoint = <endpoint>,
        limit = limit,
        offset = offset
    )

    if response failed:
        apply error strategy
        stop or retry safely

    rows = response.data

    if rows is empty:
        stop

    process rows idempotently

    if length(rows) < limit:
        stop

    next_offset = offset + limit

    if next_offset <= offset:
        stop with pagination safety error

    offset = next_offset
    page_number = page_number + 1

10.2 Protect against infinite loops

Use:

• maximum page count;
• maximum row count;
• request deadline;
• repeated-page detection;
• offset progress validation.

10.3 Avoid massive parallel loads

Parallel page requests can:

• exceed rate limits;
• return inconsistent moving pages;
• create unnecessary load;
• complicate deduplication.

Use bounded concurrency or sequential pagination.

---

11. Error and Retry Strategy

11.1 Pseudo-code

attempt = 0
base_delay = <retry-delay>
maximum_delay = <maximum-retry-delay>
maximum_attempts = <maximum-attempts>

while attempt < maximum_attempts:
    response = request()

    if response.status == 200:
        return response

    if response.status == 400
       or response.status == 401
       or response.status == 404
       or response.status == 405:
        stop and require configuration or request correction

    if response.status == 429
       or response.status == 500:
        delay = min(maximum_delay, base_delay * 2^attempt)
        delay = delay + random_jitter()
        wait(delay)
        attempt = attempt + 1
        continue

    stop

return safe failure state

11.2 Retry-After

Retry-After may not be present unless explicitly documented.

Clients need their own bounded retry policy.

11.3 Shared retry budget

Coordinate retry attempts across workers sharing:

• the same key;
• the same cache;
• the same requested resource.

---

12. Data Freshness Strategy

12.1 Health is basic availability

/api/v1/health can confirm basic service availability.

It does not guarantee that:

• market/current is current;
• market/pair has a fresh row;
• candles includes the latest activity;
• fa/swaps and legacy/swaps have equal coverage;
• fa/liquidity-events and legacy/liquidity-events have equal coverage.

12.2 Use endpoint-specific freshness context

Where present, inspect:

• as-of timestamps;
• latest event timestamps;
• candle bucket boundaries;
• block heights;
• transaction context.

12.3 Empty results can be valid

Distinguish:

request failed

from:

request succeeded; no data matched

12.4 UI language

Prefer:

No data available yet.

or:

Last updated: <timestamp>

Avoid alarming outage messages for normal empty states.

12.5 Stale-while-error

If your application shows cached data during a temporary failure:

• label it as last known;
• display its timestamp;
• do not call it live;
• expire it according to your use case.

---

13. Numeric Precision Strategy

13.1 Preserve strings

When the API returns:

{
  "latest_price": "<decimal-string>",
  "tracked_amount": "<decimal-string>",
  "volume_quote": "<decimal-string>"
}

preserve those strings until a decimal-safe calculation is required.

13.2 Avoid unsafe float-only storage

Binary floating-point types can lose precision for:

• small prices;
• large token amounts;
• percentage changes;
• cumulative volume.

13.3 Use decimal-safe tools

Use:

• arbitrary-precision decimal libraries;
• fixed-point arithmetic;
• decimal database/application types;
• string preservation for transport and display.

13.4 Round only for display

Keep:

• original value for calculations;
• formatted value for UI.

13.5 Preserve units

Do not mix:

• token and quote amounts;
• token volume and quote volume;
• raw and human-readable values;
• prices with different quote tokens.

Do not relabel an on-chain quote as USD unless a documented true USD valuation source supports that conversion.

---

14. Timestamp Strategy

14.1 Parse explicitly

Fields can use:

• Unix seconds;
• UTC timestamp strings;
• candle bucket boundaries;
• creation timestamps.

14.2 Do not assume local timezone

Parse canonical timestamps first, then convert for display.

14.3 Chart conversion

Some chart libraries expect Unix milliseconds instead of seconds.

Confirm the required unit before conversion.

14.4 Candle ordering

Candle responses can be newest first while chart libraries often expect oldest first.

Reverse or sort the bounded result safely before rendering.

14.5 Different timestamp meanings

Do not assume:

• created time;
• received time;
• on-chain event time;
• snapshot as-of time;
• display time;

mean the same thing.

Use each field only according to its endpoint documentation.

---

15. Combining Endpoint Families

15.1 Market and candles are different

market/current and market/pair provide current derived snapshots.

candles provides historical bucketed data.

Do not assume their update timing is identical.

Both families retain token/quote semantics. They do not guarantee the same USD market display shown by an external dashboard.

15.2 Swaps and liquidity are different

Swap rows describe token exchange activity.

Liquidity rows describe pool or farm activity.

Do not:

• label ADD_POOL as BUY;
• label REMOVE_POOL as SELL;
• include liquidity amounts in swap volume without a documented model.

15.3 Preserve FA and LEGACY

When combining:

• fa/swaps with legacy/swaps;
• fa/liquidity-events with legacy/liquidity-events;

retain the source family.

15.4 Do not deduplicate blindly

One transaction can produce:

• multiple event positions;
• multiple token-centric rows;
• FA and LEGACY rows;
• pool and farm activity.

Do not use transaction hash alone as a universal deduplication key.

15.5 BUY and SELL boundary

BUY or SELL is token-centric.

It should not be interpreted as complete user intent without source and destination context.

---

16. UI and UX Recommendations

16.1 Loading state

Show a clear progress indicator for the active request only.

16.2 Empty state

Use endpoint-specific language:

No market data available for this pair.
No candle data yet.
No swap activity found.
No liquidity activity found.

16.3 Stale-data label

Display the relevant last-updated, as-of, bucket, or event timestamp.

16.4 Rate-limited state

Suggested message:

Too many requests. Retrying later.

16.5 Authentication state

Suggested message:

The API connection requires setup.

Do not display the credential.

16.6 Temporary service error

Suggested message:

Data is temporarily unavailable.

16.7 Precision-aware formatting

Use:

• appropriate significant digits;
• token-specific formatting;
• clear quote units;
• tooltips or expanded values where useful.

16.8 Address display

Store and compare full identifiers.

Truncate addresses only in the visual layer:

<address-prefix>…<address-suffix>

16.9 Source family labels

Show FA or LEGACY when feeds are combined.

---

17. Logging and Observability

17.1 Safe client logs

Useful fields:

• endpoint path;
• HTTP status;
• request duration;
• <request-id> or client-generated request identifier;
• safe application version;
• retry attempt;
• result count;
• redacted error code;
• freshness marker where public.

Illustrative log:

request_id=<request-id>
endpoint=<endpoint>
status=<status-code>
duration_ms=<duration>
attempt=<attempt>
result_count=<count-or-null>

17.2 Unsafe log content

Do not log:

• X-API-Key;
• full headers;
• real secrets;
• secret-bearing URLs;
• unredacted screenshots;
• raw support dumps;
• private user data not needed for diagnosis.

17.3 Redaction

Replace sensitive values with:

<redacted>

Apply redaction before sending data to logs, metrics, chat, issue trackers, or support.

---

18. Client Security Checklist

• <api-key> stays server-side.
• Requests use HTTPS.
• Keys are never placed in query strings.
• Keys are absent from frontend bundles.
• Keys are absent from mobile bundles.
• Keys are absent from repositories.
• Keys are absent from screenshots.
• Keys are absent from logs and error reports.
• Exposed keys are replaced through the provider process.
• Logs apply redaction.
• The proxy exposes only required client-facing routes.
• Incoming proxy parameters are validated and bounded.
• Application-level abuse controls are enabled where appropriate.

---

19. Client Testing Checklist

19.1 Basic availability

• Call /api/v1/health through the intended integration path.
• Verify valid JSON and ok: true.
• Verify the key is not visible in frontend tools.

19.2 Market

• Test market/current with a small limit.
• Test market/pair with <token-address> and <quote-token-address>.
• Test data: null handling.

19.3 Candles

• Test one candles query with <granularity>.
• Test empty history.
• Test timestamp conversion and row ordering.

19.4 Swaps

• Test fa/swaps if FA coverage is required.
• Test legacy/swaps if LEGACY coverage is required.
• Verify family labels remain distinct.
• Verify multiple rows per transaction do not break the UI.

19.5 Liquidity

• Test fa/liquidity-events if FA pool/farm coverage is required.
• Test legacy/liquidity-events if LEGACY coverage is required.
• Verify liquidity rows are not labeled as swaps.

19.6 Pagination

• Test limit and offset.
• Test an empty final page.
• Test the maximum page guard.
• Confirm no page_token behavior is assumed.

19.7 Errors

• Test 401 handling without exposing a real key.
• Test invalid parameter handling.
• Test 429 and backoff behavior carefully in an approved environment.
• Test bounded 500 retry logic using a controlled client simulation.

19.8 UI data states

• Test loading.
• Test empty data.
• Test stale data.
• Test rate limited.
• Test authentication setup error.
• Test temporary service error.

---

20. Common Integration Mistakes

20.1 Exposing the key in a browser

Use a backend proxy.

20.2 Treating the API as a real-time stream

Use responsible polling and freshness indicators.

20.3 Assuming page_token exists

Use limit and offset.

20.4 Treating empty data as an outage

An empty array or data: null can be valid.

20.5 Treating health as freshness proof

Inspect endpoint-specific timestamps and blocks.

20.6 Parsing every number as a float

Preserve decimal strings and use decimal-safe arithmetic.

20.7 Losing FA or LEGACY labels

Preserve source family when combining feeds.

20.8 Mixing swaps and liquidity events

Keep exchange activity separate from pool and farm activity.

20.9 Retrying 401 in a loop

Fix credentials before retrying.

20.10 Ignoring 429

Reduce polling and apply backoff with jitter.

20.11 Logging secrets

Redact credentials and full headers before logging.

20.12 Fetching full history repeatedly

Cache stable pages and request bounded updates.

20.13 Using transaction hash as a universal deduplication key

Preserve family, event, and token-role context.

20.14 Treating pair price as true USD

Preserve the quote identity, show freshness, and use a separately documented valuation source when a true USD value is required.

---

21. Scope and Data Exposure

Integrations can rely on the documented routes, parameters, response fields, envelopes, HTTP behavior, and endpoint semantics. Provider administration and operations are outside the API contract.

---

22. Chapter Summary

Safe Supra Core integrations should:

• keep X-API-Key on a trusted backend, proxy, bot server, or analytics job;
• use HTTPS;
• parse JSON defensively;
• cache common reads;
• poll responsibly;
• paginate with limit and offset;
• not assume page_token;
• apply bounded retry, backoff, and jitter;
• distinguish 401 from 429;
• handle empty and stale data separately from request failures;
• preserve numeric precision;
• parse each timestamp according to its documented meaning;
• keep market, candles, swaps, and liquidity semantics distinct;
• preserve FA and LEGACY labels;
• avoid blind cross-family deduplication;
• display clear loading, empty, stale, and error states;
• log only redacted request context;
• test security, pagination, retry, precision, and freshness behavior before release.

The Supra Core API service is a read-oriented data interface. It is not a streaming, trading, wallet-signing, staking-action, farming-action, or private account-management interface.