NumerAPI 2.24.0 - Payout score refactor, Crypto/Signals API fixes

CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 Notable changes to this project.
 
+## [2.24.0] - 2026-08-03
+- add exact `roundScoreConfigs` identities, scoring windows, and payout settings
+  to `list_rounds` for Classic, Signals, and Crypto
+- stop querying deprecated GraphQL round multiplier fields; keep the six
+  established Corr/MMC return keys as exact-name compatibility projections
+  until their scheduled removal in numerapi 3.0.0
+- document migration from legacy round multiplier roles and isolate the
+  deprecated `round_model_performances_v2` behavior
+- expose the tournament-aware `stake_get` API consistently for Classic,
+  Signals, and Crypto
+- allow `download_dataset` to use pandas Parquet filters and download only the
+  matching portion of a dataset
+
 ## [2.23.3] - 2026-06-30
 - fix `models_of_account` referencing incorrect type `Str!` instead of `String!`
 

README.md

@@ -39,6 +39,12 @@ and `NUMERAI_SECRET_KEY`).
     napi = numerapi.NumerAPI(verbosity="info")
     # download current dataset => also check `https://numer.ai/data`
     napi.download_dataset("v4/train.parquet", "train.parquet")
+    # use pandas filter syntax to download only selected parquet rows
+    napi.download_dataset(
+        "v4/train.parquet",
+        "train_eras_1_and_2.parquet",
+        filters=[("era", "in", ["0001", "0002"])],
+    )
     # get current leaderboard
     leaderboard = napi.get_leaderboard()
     # check if a new round has started

docs/index.rst

@@ -7,6 +7,7 @@ Contents
     :maxdepth: 2
 
     changelog
+    round-score-configs
     license
 
 Indices and tables

docs/round-score-configs.md

@@ -0,0 +1,92 @@
+# Round score and payout configuration
+
+Starting in numerapi 2.24.0, `NumerAPI.list_rounds()`,
+`SignalsAPI.list_rounds()`, and `CryptoAPI.list_rounds()` return the public
+`roundScoreConfigs` list. Each item is an exact score definition and per-round
+snapshot from the Tournament API. New code should select entries by `name`,
+`version`, or `scoreConfigId`; it should not infer score identity from a legacy
+payout role.
+
+Each item includes:
+
+- identity: `id`, `scoreConfigId`, `name`, `version`, and `displayName`;
+- applicability: `roundNumberStart`, `roundNumberEnd`, `universe`,
+  and `isCanonScore`;
+- scoring: `totalScoreDays`, `returnsLagDays`, `dataDelayDays`,
+  `scoringStart`, and `scoringEnd`;
+- payout settings: `isPayout`, `minMultiplier`, `maxMultiplier`,
+  `defaultMultiplier`, `clipThreshold`, `stakeThreshold`, and `payoutFactor`.
+
+`scoringStart` and `scoringEnd` are returned as `datetime.datetime` objects,
+consistent with other date fields in numerapi. GraphQL float and integer fields
+retain their normal Python JSON types.
+
+## Migrating from legacy multiplier keys
+
+Before 2.24.0, `list_rounds()` requested server compatibility fields. For a
+Signals round, a response could look like this even though the payout scores
+were Alpha and MPC:
+
+```python
+{
+    "defaultCorrMultiplier": 0.3,
+    "defaultMmcMultiplier": 0.8,
+}
+```
+
+In 2.24.0 the exact identities are available without knowing score names in
+advance:
+
+```python
+{
+    "roundScoreConfigs": [
+        {
+            "scoreConfigId": "...",
+            "name": "alpha",
+            "version": "2",
+            "displayName": "alpha",
+            "isPayout": True,
+            "defaultMultiplier": 0.3,
+            # Other identity, scoring, timing, and payout fields omitted.
+        },
+        {
+            "scoreConfigId": "...",
+            "name": "meta_portfolio_contribution",
+            "version": "2",
+            "displayName": "mpc",
+            "isPayout": True,
+            "defaultMultiplier": 0.8,
+        },
+    ],
+    "defaultCorrMultiplier": None,
+    "defaultMmcMultiplier": None,
+}
+```
+
+The six established Corr/MMC keys (`min`, `max`, and `default` for each) stay
+in the returned round dictionary throughout numerapi 2.x. They are now
+identity-safe projections: Corr keys select only a payout config whose `name`
+is exactly `correlation`, MMC keys select only a payout config whose `name` is
+exactly `meta_model_contribution`, and the keys are `None` when there is no
+exact match. Alpha and FNC are never projected as Corr; MPC is never projected
+as MMC. If multiple exact payout configs exist, the projection uses the config
+with the newest `roundNumberStart`, then compares the numeric `version` values
+as integers and uses `id` for a numeric-version tie. If multiple configs at the
+newest start contain a non-numeric future version, the compatibility keys are
+`None` rather than guessing an order. The complete list remains available
+unchanged in either case.
+
+These six compatibility keys are scheduled for removal in numerapi 3.0.0.
+`list_rounds()` never exposed the three legacy TC multiplier fields, so this
+migration does not introduce them. Code should migrate now by filtering
+`roundScoreConfigs`, normally starting with `isPayout`.
+
+## Deprecated performance endpoint
+
+`round_model_performances_v2()` remains an isolated deprecated compatibility
+method. Its `corrMultiplier` and `mmcMultiplier` fields come from the deprecated
+`v2RoundModelPerformances` GraphQL endpoint and must not be used to infer score
+identity. Use `submission_scores()` for identity-preserving score results and
+join them to `list_rounds()` by round when payout configuration is needed.
+Neither performance method nor `list_rounds()` has a dedicated CLI command, so
+there is no CLI return shape to migrate.