Numerai Python API
Automatically download and upload data for the Numerai machine learning competition.
This library is a Python client to the Numerai API. The interface is programmed in Python and allows downloading the training data, uploading predictions, and accessing user, submission and competitions information. It works for both, the main competition and the newer Numerai Signals competition.
If you encounter a problem or have suggestions, feel free to open an issue.
Installation
pip install --upgrade numerapi
Usage
Numerapi can be used as a regular, importable Python module or from the command line.
Some actions (like uploading predictions or staking) require a token to verify
that it is really you interacting with Numerai's API. These tokens consists of
a public_id and secret_key. Both can be obtained by login in to Numer.ai and
going to Account -> Custom API Keys. Tokens can be passed to the Python module
as parameters or you can be set via environment variables (NUMERAI_PUBLIC_ID
and NUMERAI_SECRET_KEY).
Python module
Usage example - main competition
import numerapi
# some API calls do not require logging in
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
if napi.check_new_round():
print("new round has started within the last 12hours!")
else:
print("no new round within the last 12 hours")
# provide api tokens
example_public_id = "somepublicid"
example_secret_key = "somesecretkey"
napi = numerapi.NumerAPI(example_public_id, example_secret_key)
# upload predictions
model_id = napi.get_models()['uuazed']
napi.upload_predictions("preds.csv", model_id=model_id)
# increase your stake by 1.2 NMR
napi.stake_increase(1.2)
# convert results to a pandas dataframe
import pandas as pd
df = pd.DataFrame(napi.daily_user_performances("uuazed"))
Usage example - Numerai Signals
import numerapi
napi = numerapi.SignalsAPI()
# get current leaderboard
leaderboard = napi.get_leaderboard()
# setup API with api tokens
example_public_id = "somepublicid"
example_secret_key = "somesecretkey"
napi = numerapi.SignalsAPI(example_public_id, example_secret_key)
# upload predictions
model_id = napi.get_models()['uuazed']
napi.upload_predictions("preds.csv", model_id=model_id)
# get daily performance as pandas dataframe
import pandas as pd
df = pd.DataFrame(napi.daily_user_performances("uuazed"))
# using the diagnostics tool
napi.upload_diagnostics("preds.csv", model_id=model_id)
# ... or using a pandas DataFrame directly
napi.upload_diagnostics(df=df, model_id=model_id)
# fetch results
napi.diagnostic(model_id)
Command line interface
To get started with the cli interface, let's take a look at the help page:
$ numerapi --help
Usage: numerapi [OPTIONS] COMMAND [ARGS]...
Wrapper around the Numerai API
Options:
--help Show this message and exit.
Commands:
account Get all information about your account!
check-new-round Check if a new round has started within the...
competitions Retrieves information about all competitions
current-round Get number of the current active round.
daily-model-performances Fetch daily performance of a model.
download-dataset Download specified file for the given round
leaderboard Get the leaderboard.
list-datasets List of available data files
models Get map of account models!
profile Fetch the public profile of a user.
stake-decrease Decrease your stake by `value` NMR.
stake-drain Completely remove your stake.
stake-get Get stake value of a user.
stake-increase Increase your stake by `value` NMR.
submission-filenames Get filenames of your submissions
submit Upload predictions from file.
transactions List all your deposits and withdrawals.
version Installed numerapi version.
All CLI commands accept a --tournament option. It defaults to 8
(the classic tournament), but you can point the CLI at Signals (11) or
Crypto (12) on a per-command basis, e.g. numerapi list-datasets --tournament 11.
Each command has it's own help page, for example:
$ numerapi submit --help
Usage: numerapi submit [OPTIONS] PATH
Upload predictions from file.
Options:
--tournament INTEGER The ID of the tournament, defaults to 8
--model_id TEXT An account model UUID (required for accounts with
multiple models
--help Show this message and exit.
API Reference
Checkout the detailed API docs to learn about all available methods, parameters and returned values.
3 maintainers
Metadata
3 maintainers
Release files for numerapi 3.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| numerapi-3.1.1.tar.gz | 36.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| numerapi-3.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 67.2 kB
Release files / numerapi-3.1.1.tar.gz
| Download URL | numerapi-3.1.1.tar.gz |
|---|---|
| Size | 36.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ae3496e41f88d03211934837fddf00a7ab2cfb51896e76bbd78603ca166895e1
|
|
BLAKE2b-256 checksum How to use checksums |
e336321183a4523df1b9f118dd5a2b8bfba4745a3191842e63c2bc513668551c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Release files / numerapi-3.1.1-py3-none-any.whl
| Download URL | numerapi-3.1.1-py3-none-any.whl |
|---|---|
| Size | 30.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c37a72ac0783fb1d6eac5bc959a5b3e2adf4d0c04fc2ca0b18da6bfb10583162
|
|
BLAKE2b-256 checksum How to use checksums |
681cd3c1118e3d12b6a2f6ee3b3b1d8e7123840510598a994b94f8edfba4ae03
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
