Supra Core API — Public Client Documentation

Chapter 12 — LEGACY Swaps Endpoint

1. Purpose

GET /api/v1/legacy/swaps returns normalized swap activity from the LEGACY source family.

It is separate from the FA endpoint. A token or transaction visible in one family is not proof that a matching row exists in the other.

2. Request Parameters

Parameter	Required?	Default or bound	Description
`network`	No	`mainnet`	Public network
`token`	No	None	Matches tracked, source, destination, or counter metadata
`symbol`	No	None	Case-insensitive exact symbol match
`wallet`	No	None	Exact `<wallet-address>`
`tx_hash`	No	None	Exact `<tx-hash>`
`dex`	No	None	Exact public DEX label
`source`	No	None	Exact public source label
`summary_type`	No	None	Exact public summary type
`side`	No	None	Exactly `BUY` or `SELL`
`from_block`	No	None	Inclusive minimum block
`to_block`	No	None	Inclusive maximum block
`limit`	No	Default `50`, maximum `500`	Maximum rows
`offset`	No	Default `0`, maximum `10000`	Rows skipped

No query parameter causes this endpoint to include FA rows.

3. Curl Examples

Recent LEGACY swaps:

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

Wallet activity:

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

4. Illustrative Response

{
  "ok": true,
  "data": [
    {
      "flow": "legacy",
      "tx_hash": "<tx-hash>",
      "block_height": 0,
      "event_index": 0,
      "wallet_address": "<wallet-address-or-null>",
      "src_token_metadata": "<legacy-token-metadata>",
      "dst_token_metadata": "<quote-token-address>",
      "tracked_token_metadata": "<legacy-token-metadata>",
      "counter_token_metadata": "<quote-token-address>",
      "side": "BUY",
      "tracked_amount": "<decimal-string>",
      "counter_amount": "<decimal-string>",
      "source": "<source-label>",
      "summary_type": "<summary-type>"
    }
  ],
  "meta": {
    "api_version": "v1",
    "endpoint": "legacy/swaps",
    "network": "mainnet",
    "limit": 50,
    "offset": 0,
    "count": 1
  }
}

Legacy token metadata can use a different public identifier shape from FA metadata. Preserve returned values exactly.

5. FA and LEGACY Separation

Use:

/api/v1/fa/swaps for FA rows;
/api/v1/legacy/swaps for LEGACY rows.

If a client intentionally combines both:

retain flow;
do not normalize away identifier differences;
do not deduplicate only by transaction hash;
label the source family in UI and exports.

6. Token Roles and Side

The same token roles apply:

source token;
destination token;
tracked token;
counter token.

BUY and SELL are tracked-token projections, not complete statements of user intent.

Both-token and multi-event cases can produce more than one row for one transaction.

7. Ordering and Pagination

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

Use limit and offset. Do not use page_token.

Stop a pagination loop on an empty or shorter-than-limit page.

8. Empty and No-Data Results

data=[] can mean:

no matching LEGACY rows;
the token is represented only in FA;
filters are too narrow;
the offset is beyond available rows;
no currently available coverage matches the request.

It does not automatically mean the API is unavailable.

9. Precision and Defensive Parsing

Preserve src_amount, dst_amount, tracked_amount, and counter_amount as exact decimal strings.
Raw integer amount columns are not part of this public swap response.
Preserve full metadata identifiers.
Treat symbols as display values.
Accept nullable and added fields.
Keep source-family context with cached or stored rows.

10. Errors

Status	Typical cause
`400`	Invalid side, integer, or range
`401`	Authentication failure
`429`	Rate limit exceeded
`500`	Temporary service error

11. Scope and Data Exposure

The endpoint exposes only the documented normalized LEGACY swap fields and filters. Parsing and evidence details are not part of the response contract.

12. Chapter Summary

Use /api/v1/legacy/swaps for normalized LEGACY swap history. Preserve returned metadata, token roles, event context, precision, and the legacy family label, especially when combining it with FA data.