List Clawbackable Transfers
This endpoint returns a paginated list of transfers that are eligible to be clawed back. It queries the Sparkscan API for transfers sent by the authenticated user and then filters them based on eligibility criteria (status, age, spent status).
Eligibility Criteria
A transfer is included in the list if:
- It was sent by the authenticated user
- It was sent to a pool the user has interacted with (automatically derived from swap history)
- It exists and has a valid status in Sparkscan (not claimed/settled)
- It has not already been used in a swap operation (database check on
amm_swapstable) - It has not already been used in a liquidity operation (database check on
amm_liquiditytable) - It is not currently reserved or spent in the AMM gateway cache (Redis check on
sparkscan:atomic:{...}keys) - It is not currently reserved by the TEE (Redis check on
transfer:{id}keys - catches already clawed back transfers) - It is at least 30 seconds old (to prevent race conditions with in-flight transfers)
- It is less than 241 hours old (10 days + 1 hour buffer)
Pagination
Results are paginated with configurable limits:
- Maximum 500 transfers per request
- Default limit is 20
- Use
offsetto skip transfers for pagination
Query Parameters
limit- Maximum number of transfers to return (1-500)offset- Number of transfers to skip for pagination
Authentication
- Bearer token in
Authorizationheader - used to identify the sender
Returns
200 OKwithListClawbackableTransfersResponsecontaining eligible transfers with timestamps (empty array if no eligible transfers found or user has not interacted with any pools)400 Bad Requestif query parameter validation fails401 Unauthorizedif authentication fails or token is invalid500 Internal Server Errorif database or Sparkscan service fails
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Maximum number of transfers to return per page. Defaults to 20, maximum 500.
Number of transfers to skip before starting to collect the result set. Used for pagination - set to 0 for first page, 20 for second page (with limit=20), etc.
(Internal/debug) Override the user public key to query clawbackable transfers for. When provided, queries transfers for this pubkey instead of the authenticated user.
Response
List of eligible transfers with timestamps (or empty if none found)
Response for listing eligible clawback transfers
Contains a paginated list of transfers filtered for eligibility (not spent/reserved).
List of transfers that are eligible for clawback (paginated)