Supra Core API — Public Client Documentation

Chapter 01 — Introduction

1. What This Manual Is

The public client documentation for the Supra Core API helps external developers consume its read-oriented HTTP service.

It explains:

• available endpoint families;
• API key usage;
• common JSON response shapes;
• pagination and filtering conventions;
• rate-limit handling;
• data freshness expectations;
• safe integration practices.

Later chapters provide endpoint-specific parameters, fields, examples, and error handling.

Note: Examples in this introductory chapter are illustrative. Endpoint-specific chapters and the OpenAPI specification define exact request and response behavior.

---

2. What This Manual Is Not

This manual is not:

• private developer or administrator documentation;
• infrastructure or deployment documentation;
• a trading or order-placement API guide;
• a wallet signing or custody integration guide;
• a write API guide;
• a private account-management guide;
• a WebSocket or streaming API guide;
• a guaranteed legal, accounting, investment, or financial data source;
• a replacement for endpoint-specific contracts or the OpenAPI specification.

The API does not currently provide:

• trading execution;
• order placement;
• wallet signing;
• transaction submission;
• private account management;
• WebSocket subscriptions;
• streaming feeds.

---

3. API Overview

Supra Core provides read access to normalized blockchain and market information.

Current public-facing data domains include:

• basic API and data-state health;
• current token/quote market snapshots;
• exact pair market snapshots;
• OHLCV-style candles;
• chart-ready continuous presentation series;
• current fungible-asset swap history;
• legacy token swap history;
• current fungible-asset liquidity and farm events;
• current fungible-asset burn events;
• legacy liquidity and farm events.

All current public endpoints use HTTP GET.

The API is designed for:

• dashboards;
• portfolio and market views;
• alerting systems;
• bots;
• analytics pipelines;
• historical activity lookups;
• development and research tools.

It is read-oriented. Clients cannot use it to modify blockchain state or place trades.

---

4. Endpoint Families

Endpoint-specific chapters will document query parameters and response fields in detail.

---

5. Authentication Overview

Access to the Supra Core API service is commercial. Every request, including health, requires a valid API key associated with an enabled plan. Public documentation and the OpenAPI specification do not grant access to the service.

Send the key with X-API-Key or Authorization: Bearer. Example:

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

5.1 Protect the key

• Keep the key on a trusted server.
• Do not embed it in public browser JavaScript.
• Do not place it in mobile application source code.
• Do not include it in URLs.
• Do not commit it to source control.
• Do not paste it into public logs, screenshots, or support messages.

For a public website, call Supra Core from your own backend or server-side proxy. The browser should call your backend, not expose the API key directly.

5.2 Exposure

If a key is exposed:

1. stop using the exposed value;
2. request revocation and replacement through the approved access channel;
3. update the consuming service;
4. verify the old key no longer works.

Warning: Hiding a key in minified client-side code does not protect it.

---

6. Base URL and Placeholders

Examples use:

<api-base>

Replace it with the base URL supplied for your API environment.

Other placeholders include:

Do not send angle brackets as part of a real request.

This chapter intentionally does not publish an environment-specific hostname.

---

7. Basic Request Examples

7.1 Health

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

7.2 Current market data

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

7.3 Illustrative success response

This shortened JSON example is illustrative:

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

An empty array can be a valid result.

---

8. Response Format Overview

The API returns JSON.

8.1 Success

Successful responses use:

{
  "ok": true,
  "data": {},
  "meta": {}
}

Depending on the endpoint, data can be:

• an object;
• an array;
• null when an exact optional lookup has no match.

8.2 Error

Errors use:

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

8.3 Types and nullability

Clients should:

• handle nullable fields;
• treat empty arrays as valid;
• preserve decimal precision;
• avoid converting every numeric string to floating point;
• accept documented integer values as integers;
• parse timestamps according to each field's documented format.

Timestamp fields can use Unix values, UTC strings, or database-style timestamp strings depending on the endpoint and field. Endpoint chapters will document the exact public fields.

---

9. Pagination and Filtering

Current list endpoints use:

• limit;
• offset.

They do not currently use page_token.

Example:

curl -sS \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/fa/swaps?wallet=<wallet-address>&limit=<limit>&offset=<offset>'

Integration guidance:

• use the smallest practical limit;
• advance offset only when another page is required;
• use endpoint filters to reduce unnecessary data;
• avoid deep, aggressive polling;
• handle a page containing data=[];
• do not assume a total-count field is available;
• do not assume that a result set remains unchanged while paginating.

Later endpoint chapters will document available filters and maximum values.

---

10. Data Freshness

The API returns indexed and derived data. It does not fetch or calculate every result directly from the blockchain at request time.

Data freshness depends on:

• blockchain indexing progress;
• event normalization;
• timestamp availability;
• candle processing;
• current market-data updates.

10.1 Health limitations

HTTP 200 from /api/v1/health confirms basic API availability and returns selected status information. It does not guarantee:

• every swap is indexed;
• every liquidity event is available;
• every candle is current;
• every market snapshot was refreshed recently.

10.2 Client behavior

Dashboards should:

• display latest event or as-of timestamps when provided;
• tolerate temporary stale or empty data;
• distinguish “no matching data” from transport failure;
• avoid presenting an old value as real-time without its timestamp;
• retry conservatively.

Note: A successful response and current data freshness are separate conditions.

---

11. Error Handling Overview

Error messages are intentionally generic in some cases. Clients should use the HTTP status and public error code rather than depend on hidden implementation causes.

---

12. Rate-Limit Behavior

Clients may receive HTTP 429 when their assigned access limits are exceeded.

Recommended behavior:

1. stop immediate retries;
2. apply exponential backoff with jitter;
3. reduce request frequency;
4. cache repeated reads;
5. combine filters and pagination efficiently;
6. contact the approved support channel if plan capacity is consistently insufficient.

The current API does not guarantee a Retry-After header. Do not assume remaining-quota or reset headers are present unless a later public contract explicitly documents them.

Avoid synchronized polling across many workers. Spread scheduled requests over time.

---

13. Client Integration Recommendations

13.1 Security

• Keep API keys server-side.
• Use encrypted secret storage.
• Rotate exposed credentials.
• Never log authentication headers.
• Sanitize support evidence.

13.2 Reliability

• Set connection and response timeouts.
• Retry only transient failures.
• Use bounded exponential backoff.
• Treat 400 and 401 as requests requiring correction, not immediate repetition.
• Back off on 429.
• Retry persistent 500 responses cautiously and escalate with sanitized evidence.

13.3 Data handling

• Cache common reads.
• Preserve decimal strings when exact precision matters.
• Validate nullable fields.
• Store token and quote identifiers explicitly.
• Display freshness timestamps.
• Keep FA and LEGACY endpoint families distinct.
• Handle empty arrays and null pair results.

13.4 Compatibility

• Ignore unknown response fields when safe.
• Do not hardcode undocumented assumptions.
• Do not infer trading or wallet functionality from read-only data.
• Treat examples as illustrative unless marked exact.
• Review the changelog and endpoint chapter before deploying contract-sensitive changes.

---

14. Public Examples Disclaimer

Examples in this introduction:

• use placeholder values;
• may omit fields for readability;
• demonstrate request and envelope style;
• do not replace endpoint-specific documentation;
• do not guarantee every optional field is populated;
• do not define future features.

Exact endpoint chapters will document:

• required and optional parameters;
• defaults and limits;
• accepted values;
• response fields and types;
• ordering;
• empty-result behavior;
• endpoint-specific errors.

---

15. Scope and Data Exposure

This manual covers the documented HTTP routes, parameters, fields, and client-visible behavior. Administrative and operational procedures are outside its scope.

---

16. Chapter Summary

Supra Core provides a read-oriented JSON API for:

• health;
• current market snapshots;
• exact token/quote snapshots;
• candles;
• FA and LEGACY swaps;
• FA and LEGACY liquidity/farm events.

Clients authenticate with X-API-Key, should keep credentials on trusted servers, and must never expose them in public web applications or logs.

Current list pagination uses limit and offset; there is no page_token. HTTP 429 requires backoff and sensible polling. HTTP 200 can contain empty or null data. Health success is a basic availability signal, not a guarantee that all market, swap, candle, or liquidity data is current.

Later chapters will define access, authentication, response envelopes, errors, each endpoint family, pagination, integration guidance, and support procedures in greater detail.