feat(perps): paginate fills with the native cursor and sort

[kartojal]

Resolves DEV-427

Changes

• list_fills (action and PerpsSession) now forwards the API's native cursor param instead of the SDK-managed opaque cursor (timestamp window + seen keys), which has been removed for fills. Cursors are treated as opaque pass-through values; next_cursor comes from the last fill of each page per the documented cursor protocol.
• New sort keyword ("desc" default / "asc", typed as PerpsSortDirection and exported from polymarket.models) forwarded as the native sort param; invalid values raise UserInputError.
• The fills-specific default 24-hour window is gone, so the API's own defaults apply. Other account history endpoints are unchanged.
• Tests: native fills coverage for first page, cursor continuation, sort forwarding, invalid sort rejection, and exact query serialization; the shared descending-history malformed-cursor tests now run against funding payments.

Note: previously issued SDK-encoded fills cursors are no longer decoded; cursors are short-lived pagination state, so this is not treated as a breaking migration.

Usage

pages = session.list_fills(sort="asc")

first = await pages.first_page()
async for page in pages.from_cursor(first.next_cursor):
    ...  # page.items: tuple[PerpsFill, ...]

---

Note

Medium Risk
Behavior change for fills pagination (no SDK-encoded cursors, no implicit 24h window) can affect integrators mid-pagination; scope is limited to the fills listing path with solid test coverage.

Overview
Perps list_fills (account action and PerpsSession) no longer uses the SDK’s _descending_history opaque cursor (timestamp window + seen keys). It now calls /v1/account/fills with the API’s cursor and sort query params, sets next_cursor from the last fill’s trade_id when more is true, and passes through caller cursors unchanged.

New optional sort ("desc" / "asc", typed as exported PerpsSortDirection) is validated client-side; bad values raise UserInputError. The fills-only default 24-hour window when start is omitted is removed so server defaults apply. Other account history paginators are unchanged.

Tests add native fills pagination coverage and move malformed-cursor checks from fills to funding payments.

^{Reviewed by Cursor Bugbot for commit e9fc858. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 188b932. Configure here.}

[naruto11eth]

approved