Supra Core API — Public Client Documentation

Chapter 19 — Glossary

1. Purpose and Boundaries

This glossary defines client-facing terms used across the public documentation for the Supra Core API.

It is not:

a private administrator reference;
an infrastructure guide;
a description of internal processing or storage;
a complete legal, accounting, or financial data contract;
a substitute for endpoint-specific parameter and response documentation.

Definitions are concise interpretation aids. A concept defined here is not automatically a field returned by every endpoint.

2. General API Terms

Term	Public definition
Public client documentation	Public documentation for applications consuming the Supra Core API.
Supra Core API	The versioned HTTP interface exposing read-oriented health, market, candle, swap, and liquidity data.
Read-oriented API	An API used to retrieve data. It does not trade, sign, manage wallets, or perform on-chain actions.
Endpoint	A documented HTTP method and path that performs one public operation.
Endpoint family	A related group of endpoints, such as market, swap, or liquidity endpoints.
Request	The HTTP method, path, headers, and query parameters sent by a client.
Response	The HTTP status and JSON body returned for a request.
JSON	JavaScript Object Notation, the structured response format used by the API.
HTTP status code	A three-digit code describing the request outcome, such as `200`, `401`, or `429`.
Placeholder	A documentation-only value in angle brackets that must be replaced locally.
Public API contract	The documented external behavior clients may rely on, subject to the stated versioning guidance.

3. Authentication and Security Terms

Term	Public definition
`X-API-Key`	The HTTP header used to send the API key.
API key	A secret credential authorizing API reads. It is not a wallet key.
Secret	Sensitive information that must not be exposed in source code, URLs, screenshots, logs, or public messages.
HTTPS	Encrypted HTTP transport required for sending authenticated requests safely.
Backend	Trusted server-side software controlled by the client.
Proxy	A client-owned backend component that calls the API without exposing the key to public code.
Frontend	Browser-delivered user-interface code. It must not contain the API key.
Mobile app	Code distributed to user devices. Embedded long-lived secrets can be extracted and are unsafe.
Server-side job	A trusted scheduled or background process, such as an analytics or monitoring task.
Redaction	Removing or masking secrets before logging, displaying, or sharing request details.
Exposed key	A key that may have become visible to an unauthorized party and should be treated as compromised.
Key rotation	Replacing an existing key with a new key and stopping use of the old one.
Secure storage	A protected server-side mechanism with appropriately restricted secret access.
`401 Unauthorized`	The request did not provide an acceptable API credential.

Warning: Recommended architecture is frontend or mobile app → client-owned backend or proxy → Supra Core API. Never place <api-key> in public client code.

4. Endpoint Terms

Term	Public definition
`/api/v1/health`	Returns basic availability and selected data-state indicators.
`/api/v1/market/current`	Returns a bounded list of current market snapshots.
`/api/v1/market/pair`	Returns one exact token/quote market snapshot or `null`.
`/api/v1/candles`	Returns bounded OHLCV candle history for a token/quote pair.
`/api/v1/chart/token`	Returns a bounded chronological chart series with presentation-only carry-forward points.
`/api/v1/fa/swaps`	Returns normalized FA swap rows.
`/api/v1/legacy/swaps`	Returns normalized LEGACY swap rows.
`/api/v1/fa/liquidity-events`	Returns normalized FA pool and farm events.
`/api/v1/fa/burn-events`	Returns normalized final FA burn events.
`/api/v1/legacy/liquidity-events`	Returns normalized LEGACY pool and farm events.
FA	The fungible-asset-oriented source family. Preserve this label when combining data.
LEGACY	The legacy coin-type-oriented source family. Preserve this label when combining data.
Health check	A request used to inspect basic availability and selected freshness indicators.
Market endpoint	An endpoint returning a current derived market snapshot.
Candle endpoint	An endpoint returning time-bucketed OHLCV history.
Swap endpoint	An endpoint returning normalized exchange activity for one source family.
Liquidity endpoint	An endpoint returning normalized pool and farm activity for one source family.

Health success does not by itself prove every dataset is fully current.

5. Request and Pagination Terms

Term	Public definition
`<api-base>`	Placeholder for the supplied HTTPS API base URL.
`<api-key>`	Placeholder for the client's secret API credential.
`<token-address>`	Placeholder for token metadata accepted by a specific endpoint.
`<quote-token-address>`	Placeholder for quote-token metadata accepted by a specific endpoint.
`<wallet-address>`	Placeholder for a wallet or account address.
`<tx-hash>`	Placeholder for a transaction hash.
`<pool-address>`	Placeholder for a pool identifier.
`<farm-address>`	Placeholder for a farm or staking identifier.
`<granularity>`	Placeholder for an allowed candle interval.
`<limit>`	Placeholder for the maximum rows requested.
`<offset>`	Placeholder for the number of ordered rows skipped.
`<request-id>`	Placeholder for a public request identifier when one is supplied.
Query parameter	A named value appended after `?` in a request URL.
Filter	A parameter that narrows results by a documented field.
`limit`	Maximum rows requested for one list response, subject to endpoint bounds.
`offset`	Rows skipped from the endpoint's current deterministic ordering.
`page_token`	A cursor-style pagination value. It is not currently supported.

Use limit and offset. An empty or shorter-than-limit page can indicate the current end of matching results.

6. Response Format Terms

Term	Public definition
JSON object	A set of named key/value fields enclosed by `{}`.
JSON array	An ordered list enclosed by `[]`.
Success response	A response with `ok=true`, a `data` value, and endpoint metadata where documented.
Error response	A response with `ok=false` and a public error code and message.
Illustrative example	A shortened sample demonstrating usage or shape; it may omit fields.
Exact schema	The endpoint-specific fields and types explicitly documented as the current public contract.
Nullable field	A field that can legitimately contain JSON `null`.
`null`	An explicit JSON value indicating no value is available or applicable.
Missing field	A field absent from an object, distinct from a field present as `null`.
Optional field	A field not guaranteed for every row, event type, source family, or version.
Numeric string	A JSON string containing a numeric representation that may preserve high precision.
JSON number	A numeric value encoded without quotes. Its safe range depends on the client runtime.
Precision	The significant and fractional digits preserved in a value. Avoid early rounding.
Timestamp	A value representing a point in time according to the documented field.
Unix timestamp	Seconds since the Unix epoch unless another unit is explicitly documented.
ISO-like timestamp	A human-readable UTC date-time string in the field's documented format.
As-of	The time at which a derived snapshot was calculated or considered current.
Data freshness	How recent represented data is relative to current time and client expectations.

Defensive clients tolerate nullable, missing, optional, and added fields while validating fields required by their use case.

7. Error and Rate-Limit Terms

Term	Public definition
`200 OK`	The request succeeded. Data can still be empty, nullable, stale, or incomplete.
`400 Bad Request`	A required parameter is missing or a supplied value is invalid.
`401 Unauthorized`	Authentication failed. Correct key configuration rather than retrying rapidly.
`404 Not Found`	The requested route is unavailable.
`405 Method Not Allowed`	The route exists but the requested method is unsupported.
`429 Rate Limited`	The client exceeded an applicable request allowance.
`500 Internal Error`	The service could not complete the request because of an internal problem.
Rate limit	A request-volume constraint protecting service availability.
`Retry-After`	An optional header indicating when to retry; it may be absent.
Backoff	Increasing the delay between retry attempts.
Jitter	Small random variation added to retry delays.
Retry	Repeating a request after an appropriate delay.
Cache	A stored response reused for a bounded period.
Stale data	Valid data older than the client's freshness threshold.
Empty response	A successful response containing an empty list or `null` where documented.
Support/debug report	Sanitized request context containing no API key or other secret.

8. Market and Candle Terms

Term	Public definition
`market/current`	Shorthand for the current-market listing endpoint.
`market/pair`	Shorthand for one exact token/quote snapshot endpoint.
Token	The primary asset whose price or activity is represented.
Quote token	The asset in which the token's price or volume is expressed.
Pair	The ordered token and quote-token combination.
Price	A value whose unit and source must be identified; in current market endpoints it is normally pair-derived.
Market price	A context-dependent price selected for market display or analysis; it is not automatically universal or USD-denominated.
Pair price	The price of the selected token expressed in units of the selected quote token.
USD-like quote	An on-chain quote asset whose symbol or intended use resembles USD; it must not automatically be treated as off-chain USD.
True USD price	A USD-denominated value backed by a separately documented trusted USD source or explicit valuation layer.
Market display price	A value shown by a dashboard that may use its own routes, sources, filters, or formulas.
`latest_price`	The newest positive, structurally valid exact-pair price for the token, quote, and scopes; it can be `null` when no structural candidate exists and is not a universal USD value.
Selected market price	The newest structurally valid exact token/quote candle. Staleness and volume thresholds classify quality but do not replace this price.
Dust-sized candle	Informal description of a candle with low represented volume; it can carry a quality warning but this does not imply pool-liquidity measurement or statistical outlier rejection.
`change_7d_pct`	A pair/source/window-dependent seven-day percentage statistic; it is distinct from one stored `7d` candle row.
`7d` candle granularity	A UTC civil-week candle beginning Monday at `00:00:00Z`.
Liquidity	Assets available to a market or pool; only guaranteed when explicitly exposed and defined.
Volume	Represented token or quote activity over a stated period.
Market cap	Nullable USD-target valuation calculated from `latest_price_usd` and `current_supply_onchain`; availability, basis, and reason remain explicit.
FDV	Nullable USD-target valuation calculated from `latest_price_usd` and `maximum_supply`; it does not fall back to current or total supply.
Token metadata	The public identity of the primary token.
Quote token metadata	The public identity of the quote token.
Candles	Time-bucketed price and activity summaries.
OHLCV	Open, high, low, close, and volume for one bucket.
Open	First represented price in a bucket.
High	Highest represented price in a bucket.
Low	Lowest represented price in a bucket.
Close	Last represented price in a bucket.
Bucket	A fixed time interval used to group represented activity.
Granularity	The duration of each candle bucket.
Missing bucket	A time interval without a persisted event candle. The canonical endpoint leaves it absent; the chart endpoint can return a presentation-only carry-forward point after a real seed.

Market and candle fields are endpoint-specific. Candles are derived historical data, not a guaranteed real-time stream or true USD valuation series. External market displays can use different pricing sources and formulas.

9. Swap Terms

Term	Public definition
Swap	An on-chain exchange represented as one or more normalized token-centric rows.
FA swap	A normalized swap row from the FA source family.
LEGACY swap	A normalized swap row from the LEGACY source family.
Transaction hash	Public identifier of the associated on-chain transaction.
Wallet	Account address associated with the represented row when available.
Source token	Asset supplied on the represented source side.
Destination token	Asset received on the represented destination side.
Source amount	Represented amount of the source token.
Destination amount	Represented amount of the destination token.
`BUY`	Token-centric projection where the tracked token is on the destination side.
`SELL`	Token-centric projection where the tracked token is on the source side.
Tracked token	Token selected for monitored token-centric output.
Multi-hop	A route containing intermediate steps or assets.
Both-token case	A swap where both sides are tracked and can produce both `SELL` and `BUY` projections.
Source family	The FA or LEGACY label associated with the row.
Deduplication	Preventing accidental repeat processing using documented row context.

BUY and SELL do not automatically describe the user's complete economic strategy or intent. One transaction can produce multiple rows, so transaction hash alone is not always a sufficient deduplication key.

10. Liquidity Terms

Term	Public definition
Liquidity event	A normalized pool or farm activity row. It is distinct from a swap row and does not imply `BUY` or `SELL`.
FA liquidity event	A pool or farm event from the FA source family.
LEGACY liquidity event	A pool or farm event from the LEGACY source family.
Pool	A protocol-defined asset pool represented by public identifiers when available.
Farm	A staking or reward context associated with a pool or staking asset.
Event type	The normalized action label describing a liquidity row.
`ADD_POOL`	Assets were added to a tracked pool context.
`REMOVE_POOL`	Assets were removed from a tracked pool context.
`ADD_FARM`	LP or staking assets were added to a tracked farm context.
`REMOVE_FARM`	LP or staking assets were removed from a tracked farm context.
`HARVEST_FARM`	A normalized harvest or reward event representation, not complete reward accounting.
LP identity	Public metadata or symbol identifying the liquidity-provider or staking asset; it does not imply that an LP amount is available.
LP amount	An event-specific LP or staking amount that may be absent and is not guaranteed by the current liquidity response contract.
Reward amount	An optional event-scoped reward value; it is not a complete reward ledger, account balance, or lifetime total.
`created_at` in liquidity rows	Row-creation context when returned; it must not automatically be treated as on-chain execution time.
Pool activity	Add or remove activity associated with a pool.
Farm activity	Stake, unstake, or harvest activity represented by normalized farm events.

Do not interpret ADD_POOL as BUY or REMOVE_POOL as SELL.

11. Integration Terms

Term	Public definition
Backend proxy pattern	Public client calls a trusted client-owned backend, which calls the API with `X-API-Key`.
Caching strategy	Rules for safely reusing responses by endpoint, parameters, and freshness need.
Polling strategy	Controlled repeated reads using sensible intervals, caching, and backoff.
Incremental pagination	Loading later `limit`/`offset` pages as needed instead of repeatedly fetching all history.
Defensive JSON parsing	Handling `null`, missing fields, added fields, arrays, objects, and numeric strings safely.
Stale-data label	UI indicator that data is valid but older than the client's threshold.
Empty state	UI state for a successful response with no matching data.
Loading state	UI state while a request is in progress.
Auth setup error	Client configuration problem commonly represented by `401`.
Temporary service error	Potentially transient network or `500` failure.
Precision-aware formatting	Displaying numeric values without premature precision loss.
Address truncation	Shortening an address only for display while preserving its full value.
Source family label	Visible FA or LEGACY label preventing unlike rows from being silently merged.
Public frontend safety	Keeping secrets server-side and exposing only client-safe data to public code.

12. Commonly Confused Terms

Terms	Distinction
API key vs wallet key	API key authorizes reads; wallet private key controls wallet actions. They are never interchangeable.
`401` vs `429`	`401` is authentication failure; `429` is request-rate enforcement.
Empty array vs outage	`data=[]` can be valid; an outage is a request or service failure.
Health OK vs data freshness	Health can succeed while some derived data is stale or incomplete.
Market endpoint vs candle endpoint	Market returns current snapshots; candles return time-bucketed history.
Swap event vs liquidity event	Swap represents exchange activity; liquidity represents pool or farm activity.
FA vs LEGACY	Distinct source families with separate endpoints and identifiers.
`BUY`/`SELL` vs user intent	Side is token-centric and does not fully describe strategy or intent.
`limit`/`offset` vs `page_token`	Current pagination uses numeric `limit` and `offset`; `page_token` is unsupported.
`null` vs missing field	`null` is explicit; a missing field is absent.
Numeric string vs number	Numeric strings can preserve values beyond a runtime's safe numeric range.
Placeholder vs real value	Angle-bracket values are documentation markers, not usable credentials or identifiers.
Public API docs vs private admin docs	Public docs define client-visible behavior; private admin details are intentionally excluded.

13. Dangerous Assumptions

Do not assume:

the API can trade, place orders, sign transactions, or manage wallets;
exposing an API key in frontend or mobile code is safe;
page_token exists;
a successful health response proves every dataset is fresh;
one transaction always equals one returned row;
empty data means the API is unavailable;
illustrative examples are complete schemas;
every numeric value can be rounded or converted to a low-precision float early;
FA and LEGACY data can be merged without source-family labels;
missing candle buckets should be filled with invented zero values;
any endpoint performs staking, farming, or other write actions.

14. Scope and Data Exposure

This glossary explains client-visible terms but does not replace endpoint-specific request and response contracts. Provider administration and operations are outside its scope.

15. Chapter Summary

This glossary provides a shared public vocabulary for API requests, authentication, JSON responses, errors, rate limits, pagination, market snapshots, candles, swaps, liquidity events, and safe integrations.

Use each endpoint chapter for exact parameters and fields. Treat this glossary as an interpretation aid, not as a replacement for the endpoint-specific public API contract.