Supra Core API — Public Client Documentation

Chapter 11 — FA Swaps Endpoint

1. Purpose

GET /api/v1/fa/swaps returns normalized FA swap activity.

It supports:

recent token activity;
exact wallet and transaction lookup;
token-centric BUY and SELL feeds;
source and DEX filtering;
inclusive block-range queries.

It is read-only and does not trade, route orders, sign transactions, or stream live events.

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 across supported roles
`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

If both block bounds are supplied, from_block must not exceed to_block.

3. Curl Examples

Recent FA swaps:

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

Token and side:

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

Transaction:

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

4. Illustrative Response

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

The example is shortened. Fields can be nullable or added compatibly.

5. Token Roles

Role	Meaning
Source token	Asset supplied on the represented source side
Destination token	Asset received on the represented destination side
Tracked token	Token selected for the token-centric row
Counter token	The other represented token

The broad token filter can match more than one role.

6. `BUY` and `SELL`

BUY: the tracked token is represented on the destination side.
SELL: the tracked token is represented on the source side.

These labels are token-centric projections. They do not automatically describe the user's complete strategy or intent.

When both source and destination tokens are tracked, one transaction can produce:

a SELL row for the source token;
a BUY row for the destination token.

7. Multi-Hop and Multiple Rows

One transaction can contain:

multiple events;
multiple token-centric projections;
a summarized multi-hop route;
more than one returned row.

Do not deduplicate only by transaction hash. Preserve:

flow;
transaction hash;
event index;
tracked token;
side;
public row identifier when provided.

8. Ordering, Pagination, and Freshness

Rows are returned newest blocks first, with deterministic tie-breaking.

Use limit and offset; page_token is not supported.

An empty array is valid. Event availability can be delayed or incomplete, so display freshness context when available.

9. Precision and Nullability

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.
Keep token metadata as the identity; symbols are display labels.
Handle nullable wallet, user, symbol, decimal, and context fields.
Do not invent a standalone price when no documented price field is present.

10. Errors

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

11. Scope and Data Exposure

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

12. Chapter Summary

Use /api/v1/fa/swaps for normalized FA swap history. Preserve source and destination roles, tracked-token side, precision, event context, and the fa family label.