Supra Core API — Public Client Documentation

Chapter 14 — LEGACY Liquidity Events Endpoint

1. Purpose

GET /api/v1/legacy/liquidity-events returns normalized pool and farm activity from the LEGACY source family.

It is separate from the FA endpoint. The absence of LEGACY rows can be a valid result and does not imply that related FA activity is absent.

---

2. Supported Public Event Model

The endpoint uses the same normalized categories:

• POOL with ADD_POOL or REMOVE_POOL;
• FARM with ADD_FARM, REMOVE_FARM, or HARVEST_FARM.

Availability depends on observed and normalized LEGACY activity. Do not infer coverage beyond returned rows.

---

3. Request Parameters

The token filter is exact and uses only token-role columns available to the LEGACY event table. It does not include FA rows.

---

4. Curl Examples

Recent LEGACY liquidity events:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/legacy/liquidity-events?limit=<limit>&offset=<offset>'

Exact transaction:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/legacy/liquidity-events?tx_hash=<tx-hash>'

Events involving one token metadata value:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/legacy/liquidity-events?token=<token-address>&limit=<limit>'

---

5. Illustrative Response

{
  "ok": true,
  "data": [
    {
      "flow": "legacy",
      "tx_hash": "<tx-hash>",
      "block_height": 0,
      "event_index": 0,
      "event_family": "POOL",
      "event_type": "ADD_POOL",
      "wallet_address": "<wallet-address-or-null>",
      "pool_address": "<pool-address-or-null>",
      "farm_address": null,
      "lp_token_symbol": "<lp-symbol-or-null>",
      "lp_amount": "<decimal-string-or-null>",
      "token0_symbol": "<token-symbol-or-null>",
      "token0_amount": "<decimal-string-or-null>",
      "token1_symbol": "<token-symbol-or-null>",
      "token1_amount": "<decimal-string-or-null>",
      "source": "<source-label>",
      "protocol": "<protocol-label>"
    }
  ],
  "meta": {
    "api_version": "v1",
    "endpoint": "legacy/liquidity-events",
    "network": "mainnet",
    "limit": 50,
    "offset": 0,
    "count": 1
  }
}

The example is illustrative. Empty arrays and nullable event-specific fields are valid.

---

6. FA and LEGACY Separation

Use:

• /api/v1/fa/liquidity-events for FA activity;
• /api/v1/legacy/liquidity-events for LEGACY activity.

When combining:

• retain flow;
• preserve returned metadata identifiers;
• label the family in UI and exports;
• do not deduplicate only by transaction hash;
• keep pool and farm event context.

---

7. Event Interpretation

• ADD_POOL and REMOVE_POOL describe pool activity, not token BUY or SELL.
• ADD_FARM and REMOVE_FARM describe staking-position activity.
• HARVEST_FARM is a normalized harvest or reward event representation, not complete reward accounting.
• One transaction can produce more than one row.

---

8. Fields, Precision, and Nullability

The current public response includes:

• row, network, transaction, block, and event-index context;
• wallet, pool, and farm identifiers;
• LP metadata and symbol as identity fields;
• token slots token0 through token3, each with metadata, symbol, and a nullable human-readable amount;
• nullable reward metadata, symbol, and reward_amount for applicable returned events;
• source, protocol, function, family, type, position, and created_at context.

The public response includes lp_amount as a nullable decimal string for the normalized LP/stake quantity; indexed raw amounts remain excluded. Associate it with lp_token_symbol/lp_token_metadata, independently of underlying token-slot quantities and rewards. Preserve decimal strings, zero, negative values and null; do not derive missing amounts or rename the supplied LP/stake identity.

created_at is row-creation context. Do not treat it automatically as the on-chain execution time. Interpret timestamps only according to the fields explicitly documented by the endpoint.

---

9. Ordering, Pagination, and Empty Data

Rows are newest-block-first with deterministic tie-breaking.

Use limit and offset; page_token is not supported.

An empty response can mean:

• no matching LEGACY event;
• filters are too narrow;
• offset is beyond available rows;
• the relevant activity is available only in FA;
• current LEGACY coverage has no rows.

---

10. Errors

---

11. Scope and Data Exposure

The endpoint exposes the documented LEGACY liquidity events with their nullable asset slots. Clients must not infer missing amounts or evidence that the response does not provide.

---

12. Chapter Summary

Use /api/v1/legacy/liquidity-events for normalized LEGACY pool and farm history. Preserve source family, event type, identifiers, returned decimal values, and transaction context. Treat nullable fields and empty coverage as valid, and do not infer unstated LP amounts, reward accounting, or source-family coverage.