Skip to main content
We are updating the time-window behavior for GET /contracts/{contractAddress}/transfers. The change affects the validation of timestampFrom and timestampTo.

​
Action Required by July 1, 2026

Update the integration logic before July 1, 2026. Make sure you’re using it as described below.

​
Compatibility Note

This change is not fully backward-compatible for clients that depended on previous implicit timestamp adjustments. We are making this update to provide explicit, predictable API behavior so integrations can rely on clear rules instead of silent server-side adjustments. If your integration assumed the API would auto-correct invalid or oversized windows, you may now receive:
  • 400 for invalid ordering or explicit windows larger than 90 days.
  • 200 with empty items (and range) for out-of-range timestamps.
Update client logic to read range first and construct valid windows explicitly.

​
Updated Time-Window Behavior

The API now applies these rules:
  1. If a contract has no transfer activity, the response returns empty items and:
    • range.startTimestamp = null
    • range.endTimestamp = null
  2. timestampFrom must be less than or equal to timestampTo (otherwise 400).
  3. Provided timestamps must be within the contract activity range.
    • If they are outside the range, the response is 200 with empty items and range included.
  4. If both timestamps are provided, the requested span must be <= 90 days.
    • If the span is greater than 90 days, the response is 400.
  5. Defaults when only one timestamp is provided:
    • Only timestampFrom (must be within the activity range) -> timestampTo defaults to min(lastTransfer, timestampFrom + 90 days).
    • Only timestampTo (must be within the activity range) -> timestampFrom defaults to max(firstTransfer, timestampTo - 90 days).
    • Neither provided -> the latest 90 days of activity.
  6. Every response includes range with the contract’s first and latest transfer timestamps.
    • Use range to page through full history.

​
What Changed from Previous Behavior

These legacy behaviors are no longer applied:
  • timestampFrom is no longer auto-adjusted forward when it is earlier than the first activity.
  • Future-facing timestampTo is no longer auto-capped to the current time.
  • The API no longer silently fixes out-of-range user timestamps; out-of-range inputs return 200 with empty items and range.
  • The API no longer auto-adjusts oversized requested windows to 90 days; when both timestamps are provided and the requested span is greater than 90 days, the request returns 400.
Apply these steps now so your integration remains compatible after the updated logic is live:
  1. Make an initial request without timestampFrom or timestampTo.
  2. Read range from the response.
    • If both values are null, there is no activity for this contract/type.
    • If values exist, treat them as the valid bounds.
  3. Iterate only within:
    • range.startTimestamp <= requested timestamps <= range.endTimestamp
  4. Keep every requested window <= 90 days.
  5. For larger periods, split into multiple requests.
  6. To fetch full history, start with empty timestamps, read range, then request <= 90 day windows inside that range.