Supra Core API — Public Client Documentation

Chapter 13 — FA Liquidity Events Endpoint

1. Purpose

GET /api/v1/fa/liquidity-events returns normalized FA pool and farm activity.

The endpoint is read-only. It does not add or remove liquidity, stake assets, harvest rewards, trade, sign transactions, or stream live events.

---

2. Event Families and Types

Liquidity events are not swap events. Do not map ADD_POOL to BUY or REMOVE_POOL to SELL. HARVEST_FARM does not by itself provide complete reward accounting.

---

3. Request Parameters

The token filter is exact and can match any applicable token role in the normalized event. It does not search symbols and does not combine FA with LEGACY rows.

---

4. Curl Examples

Recent FA liquidity events:

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

Events involving one token metadata value:

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

Farm harvests:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/fa/liquidity-events?event_family=FARM&event_type=HARVEST_FARM&farm=<farm-address>'

Pool activity:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/fa/liquidity-events?event_family=POOL&pool=<pool-address>'

---

5. Illustrative Response

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

The example is shortened. Field applicability depends on the event family and type.

---

6. Public Field Groups

The current public response includes:

• row, network, transaction, block, and event-index context;
• source, protocol, function_name, event_family, event_type, and position_type;
• wallet, pool, and farm addresses;
• LP token 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;
• created_at.

Many fields are nullable because pool and farm rows represent different actions.

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.

---

7. Pool Events

For ADD_POOL and REMOVE_POOL, clients should prioritize:

• pool identity;
• LP identity;
• token slot identities;
• token-slot amounts when non-null;
• wallet and transaction context.

The public response includes lp_amount, a nullable decimal string for the normalized LP/stake quantity. It is independent of token-slot amounts and rewards. Preserve precision, zero, negative values and null; do not derive underlying quantities or rename the supplied LP/stake identity.

---

8. Farm Events

For ADD_FARM and REMOVE_FARM, use the action, LP identity, farm identity, token-slot amounts, and transaction context that are actually returned. When lp_amount is available, associate it with lp_token_symbol/lp_token_metadata, not with the underlying tokens. Its availability depends on source data, including for legacy events.

For HARVEST_FARM, reward_amount is nullable and represents only the normalized event value when present.

A harvest row does not prove complete reward accounting, account balance, or lifetime earnings.

---

9. Pagination, Ordering, and Empty Data

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

Use limit and offset; page_token is not supported.

data=[] can be valid when:

• no FA event matches;
• filters are too narrow;
• the offset is beyond available rows;
• activity is represented only in LEGACY;
• coverage is not currently available.

---

10. Precision and Display

• Preserve returned decimal amount strings without converting them through binary floating point.
• Preserve null when an event-specific amount is unavailable.
• Show pool or farm context and event type.
• Preserve full identifiers even when visually truncating them.
• Display the fa source-family label when combining feeds.
• Keep liquidity events separate from swaps.

---

11. Errors

---

12. Scope and Data Exposure

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

---

13. Chapter Summary

Use /api/v1/fa/liquidity-events for normalized FA pool and farm activity. Preserve event type, pool or farm context, returned token amounts, LP identity, transaction context, and the fa source-family label. Treat nullable fields as event-specific and do not infer unstated LP or reward accounting.