Your organisation's settled trades, paginated
/settlementsEvery trade submitted through POST /trade/submit with your API key
presented, newest first. This is the one route a read-only trk_ reporting
key may call; your tik_ key works here too and returns the same rows.
Settled fills only. A trade appears once it reaches completed; on
Ethereum and Robinhood Chain that is when the resolver fills the order, which
can be minutes after you submitted it. Until then the amounts on record are
quote-time expectations, not what happened, so they are withheld rather than
reported as fact. Poll GET /quote/{quote_id}/status for in-flight legs.
Attribution requires the header. A submit sent without X-API-Key is not
attributed to anyone and will never appear here; there is no way to recover
it afterwards. Trades predating this endpoint are likewise absent.
Ordering and pagination key on settlement time. Pass the previous response's
next_cursor back as cursor to page; has_more tells you whether another
page exists. data may be shorter than limit while has_more is true.
Re-scan a trailing window if you reconcile exactly. A small number of Solana
trades are settled by a recovery job that records the on-chain block time, which
is earlier than when the record appeared, typically by minutes. Such a row lands
behind a cursor you have already paged past. If your totals must be exact,
re-scan roughly the last 2 hours on each pass rather than relying on the cursor
alone; trade_id is stable, so re-scanned rows deduplicate cleanly.
Note that 2 hours is a normal-operations figure, not a guaranteed bound: if that recovery job is itself delayed, a row can be backdated by as long as the delay. Treat a periodic wider re-scan as the backstop for balances that must tie out exactly.
Each entry carries a LI.FI-style sending / receiving leg pair, each with its
own transaction hash, chain and explorer link. On a single-chain swap both legs
share one transaction hash, chain and timestamp; only the token and amount
differ.
A sell quoted with payout_chain is the exception: the stock leg (sending) is
the sale on the entry's chain, and the USDC leg (receiving) is the payout, its
own transaction on the chain the USDC landed on. That is payout_chain, or the
sale's own chain when the USDC was returned there instead, in which case the
entry is one chain with two transactions. Both legs carry the settlement time.
The top-level token_out_address and amount mirror the receiving leg; the
top-level chain and tx_hash are the trade's own, the same tx_hash
GET /trades reports, so on a cross-chain sell tx_hash is the sale
(sending.tx_hash) while receiving.tx_hash is the payout.
Every amount is truncated, never rounded up. Amounts, prices and fees are reported at or below their true value, never above it, so a figure here is always safe to reconcile, re-spend, or pay out against without a buffer. Treat the last decimal place as a floor rather than a rounded value.
Filtering. All filter parameters are optional and combine with AND; omitting
one means "any". chain, protocol and ticker accept a comma-separated list
which is an OR within that parameter; ?chain=sol,eth&ticker=AAPL means AAPL
on Solana or Ethereum. Repeating a parameter is not additive:
?chain=sol&chain=eth is read as sol alone, so use the comma form. A filter
that matches nothing returns an empty data with 200, never an error.
Casing follows the response. Every filter value is matched in the casing this
endpoint reports it in: chain, protocol and side are lowercase and are
matched exactly (?side=BUY is rejected), while ticker is reported uppercase
and is the one filter accepted in any case. EVM token_out_address values are
case-insensitive; Solana addresses are base58 and case-sensitive.
A cursor is bound to the filters that produced it. Paging is a keyset over one
result set, so changing any filter mid-chain invalidates the cursor and returns
400 cursor: filters_changed; start that new query from the first page. Changing
limit is fine and does not invalidate the cursor.
Request
Responses
- 200
- 400
- 401
- 403
- 429
OK
Invalid query. cursor: malformed means the cursor did not decode; restart from the first page rather than retrying it. cursor: filters_changed means the cursor came from a different set of filters; restart that query from the first page. settled_from: must be <= settled_to means the time range is inverted.
Missing, malformed or unknown X-API-Key. These are deliberately indistinguishable; the API never reveals whether a key exists.
A key you genuinely hold, but which may not be used here. key_revoked: the key was retired. integrator_suspended: your organisation is suspended, so every one of your keys is affected.
Sliding window exceeded: per-IP or per-(IP, wallet), plus a per-organisation bucket (shared across all of your keys) whenever a valid X-API-Key is presented. Retry-After header carries delta-seconds.