numerapi.base_api module

Parts of the API that is shared between Signals and Classic

class numerapi.base_api.Api(public_id=None, secret_key=None, verbosity='INFO', show_progress_bars=True)

Bases: object

Wrapper around the Numerai API

check_new_round(hours: int = 12, tournament: int | None = None) → bool

Check if a new round has started within the last hours.

Parameters:

• hours (int, optional) – timeframe to consider, defaults to 12

• tournament (int) – ID of the tournament (optional) – DEPRECATED this is now automatically filled

Returns:

True if a new round has started, False otherwise.

Return type:

bool

Example

>>> NumerAPI().check_new_round()
False

check_round_open() → bool

Check if a round is currently open.

Returns:

True if a round is currently open for submissions, False otherwise.

Return type:

bool

Example

>>> NumerAPI().check_round_open()
False

diagnostics(model_id: str, diagnostics_id: str | None = None) → Dict

Fetch results of diagnostics run

Parameters:

• model_id (str) – Target model UUID (required for accounts with multiple models)

• diagnostics_id (str, optional) – id returned by “upload_diagnostics”

Returns:

diagnostic results with the following content:

• validationCorrMean (float)

• validationCorrSharpe (float)

• examplePredsCorrMean (float)

• validationMmcStd (float)

• validationMmcSharpe (float)

• validationCorrPlusMmcSharpeDiff (float)

• validationMmcStdRating (float)

• validationMmcMeanRating (float)

• validationCorrPlusMmcSharpeDiffRating (float)

• perEraDiagnostics (list) each with the following fields:

  • era (int)

  • examplePredsCorr (float)

  • validationCorr (float)

  • validationCorrV4 (float)

  • validationFeatureCorrMax (float)

  • validationFeatureNeutralCorr (float)

  • validationFeatureNeutralCorrV3

  • validationMmc (float)

  • validationFncV4 (float)

  • validationIcV2 (float)

  • validationRic (float)

• validationCorrPlusMmcStd (float)

• validationMmcMean (float)

• validationCorrStdRating (float)

• validationCorrPlusMmcSharpe (float)

• validationMaxDrawdownRating (float)

• validationFeatureNeutralCorrMean (float)

• validationCorrPlusMmcMean (float)

• validationFeatureCorrMax (float)

• status (string),

• validationCorrMeanRating (float)

• validationFeatureNeutralCorrMeanRating (float)

• validationCorrSharpeRating (float)

• validationCorrPlusMmcMeanRating (float)

• message (string)

• validationMmcSharpeRating (float)

• updatedAt (datetime)

• validationFeatureCorrMaxRating (float)

• validationCorrPlusMmcSharpeRating (float)

• trainedOnVal (bool)

• validationCorrStd (float)

• erasAcceptedCount (int)

• validationMaxDrawdown (float)

• validationCorrPlusMmcStdRating (float)

• validationAdjustedSharpe (float)

• validationApy (float)

• validationAutocorr (float)

• validationCorrCorrWExamplePreds (float)

• validationCorrMaxDrawdown (float)

• validationCorrV4CorrWExamplePreds (float)

• validationCorrV4MaxDrawdown (float)

• validationCorrV4Mean (float)

• validationCorrV4Sharpe (float)

• validationCorrV4Std (float)

• validationFeatureNeutralCorrV3Mean (float)

• validationFeatureNeutralCorrV3MeanRating (float)

• validationFncV4CorrWExamplePreds (float)

• validationFncV4MaxDrawdown (float)

• validationFncV4Mean (float)

• validationFncV4Sharpe (float)

• validationFncV4Std (float)

• validationIcV2CorrWExamplePreds (float)

• validationIcV2MaxDrawdown (float)

• validationIcV2Mean (float)

• validationIcV2Sharpe (float)

• validationIcV2Std (float)

• validationRicCorrWExamplePreds (float)

• validationRicMaxDrawdown (float)

• validationRicMean (float)

• validationRicSharpe (float)

• validationRicStd (float)

Return type:

dict

Example

>>> napi = NumerAPI(secret_key="..", public_id="..")
>>> model_id = napi.get_models()['uuazed']
>>> api.upload_diagnostics("prediction.cvs", model_id=model_id)
'93c46857-fed9-4594-981e-82db2b358daf'
>>> napi.diagnostic(model_id)
{"validationCorrMean": 0.53231,
...
}

download_dataset(filename: str | None = None, dest_path: str | None = None, round_num: int | None = None) → None

Download specified file for the given round.

Parameters:

• filename (str, optional) – file to be downloaded

• dest_path (str, optional) – complete path where the file should be stored, defaults to the same name as the source file

• round_num (int, optional) – tournament round you are interested in. defaults to the current round

Returns:

path of the downloaded file

Return type:

str

Example

>>> filenames = NumerAPI().list_datasets()
>>> NumerAPI().download_dataset(filenames[0]}")

download_submission(submission_id: str | None = None, model_id: str | None = None, dest_path: str | None = None) → str

Download previous submissions from numerai

Parameters:

• submission_id (str, optional) – the submission to be downloaded

• model_id (str, optional) – if provided, the latest submission of that model gets downloaded

• dest_path (str, optional) – where to save the downloaded file

Returns:

path to downloaded file

Return type:

str

Example

>>> # fetch latest submission
>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model_id = api.get_models()["uuazed"]
>>> api.download_submission(model_id=model_id)
>>> # fetch older submssion
>>> ids = api.submission_ids(model_id)
>>> import random; submission_id = random.choice(ids)["id"]
>>> api.download_submission(submission_id=submission_id)

get_account() → Dict

Get all information about your account!

Returns:

user information including the fields:

• assignedEthAddress (str)

• availableNmr (decimal.Decimal)

• availableUsd (decimal.Decimal)

• email (str)

• id (str)

• insertedAt (datetime)

• mfaEnabled (bool)

• status (str)

• username (str)

• apiTokens (list) each with the following fields:

• name (str)

• public_id (str)

• scopes (list of str)

• models * username * id * submissions * v2Stake

  • status (str)

  • txHash (str)

Return type:

dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> api.get_account()
{'apiTokens': [
        {'name': 'tokenname',
         'public_id': 'BLABLA',
         'scopes': ['upload_submission', 'stake', ..]
         }, ..],
 'assignedEthAddress': '0x0000000000000000000000000001',
 'availableNmr': Decimal('99.01'),
 'email': 'username@example.com',
 'id': '1234-ABC..',
 'insertedAt': datetime.datetime(2018, 1, 1, 2, 16, 48),
 'mfaEnabled': False,
 'status': 'VERIFIED',
 'username': 'cool username',
 }

get_account_leaderboard(limit: int = 50, offset: int = 0) → List[Dict]

Get the current account leaderboard

Parameters:

• limit (int) – number of items to return (optional, defaults to 50)

• offset (int) – number of items to skip (optional, defaults to 0)

Returns:

list of leaderboard entries

Each dict contains the following items:

• username (str)

• displayName (str)

• rank (int)

• nmrStaked (decimal.Decimal)

• v2Corr20 (float)

• cort20 (float)

• corrV4 (float)

• fncV4 (float)

• icV2 (float)

• mmc (float)

• ric (float)

• return1y (float)

• return3m (float)

• returnAllTime (float)

• return1yNmr (decimal.Decimal)

• return3mNmr (decimal.Decimal)

• returnAllTimeNmr (decimal.Decimal)

Return type:

list of dicts

Example

>>> numerapi.NumerAPI().get_account_leaderboard()
[{'username': 'leonidas',
  'rank': 1,
  'nmrStaked': Decimal('3034.00'),
  ...
  }]

get_account_transactions() → List

Get all your account deposits and withdrawals.

DEPRECATED - please use wallet_transactions instead”

get_current_round(tournament: int | None = None) → int

Get number of the current active round.

Parameters:

tournament (int) – ID of the tournament (optional)

Returns:

number of the current active round

Return type:

int

Example

>>> NumerAPI().get_current_round()
104

get_models(tournament: int | None = None) → Dict

Get mapping of account model names to model ids for convenience

Parameters:

tournament (int) – ID of the tournament (optional)

Returns:

modelname->model_id mapping, string->string

Return type:

dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()
{'uuazed': '9b157d9b-ce61-4ab5-9413-413f13a0c0a6'}

intra_round_scores(model_id: str)

Fetch intra-round scores for your model.

While only the final scores are relevant for payouts, it might be interesting to look how your scores evolve throughout a round.

Parameters:

model_id (str) –

Returns:

list of intra-round model performance entries

For each entry in the list, there is a dict with the following content:

• roundNumber (int)

• intraRoundSubmissionScores (dict)

  • date (datetime)

  • day (int)

  • displayName (str): name of the metric

  • payoutPending (float)

  • payoutSettled (float)

  • percentile (float)

  • value (float): value of the metric

Return type:

list of dicts

list_datasets(round_num: int | None = None) → List[str]

List of available data files

Parameters:

round_num (int, optional) – tournament round you are interested in. defaults to the current round

Returns:

filenames

Return type:

list of str

Example

>>> NumerAPI().list_datasets()
[
  "numerai_training_data.csv",
  "numerai_training_data.parquet",
  "numerai_validation_data.csv",
  "numerai_validation_data.parquet"
]

model_upload(file_path: str, tournament: int | None = None, model_id: str | None = None, data_version: str | None = None, docker_image: str | None = None) → str

Upload pickled model to numerai.

Parameters:

• file_path (str) – pickle file, needs to endwith .pkl

• tournament (int) – ID of the tournament (optional)

• model_id (str) – Target model UUID

• data_version (str, optional) – which data version to use. ID or name. Check available options with ‘model_upload_data_versions’

• docker_image (str, optional) – which docker image to use. ID or name. Check available options with ‘model_upload_docker_images’

Returns:

model_upload_id

Return type:

str

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model_id = api.get_models()['uuazed']
>>> api.model_upload("example.pkl", model_id=model_id)
'93c46857-fed9-4594-981e-82db2b358daf'

model_upload_data_versions() → Dict

Get available data version for model uploads

Returns:

name to ID mapping

Return type:

dict[str, str]

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> api.model_upload_data_versions()
{'v4.1': 'a76bafa1-b25a-4f22-9add-65b528a0f3d0'}

model_upload_docker_images() → Dict

Get available docker images for model uploads

Returns:

name to ID mapping

Return type:

dict[str, str]

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> api.model_upload_docker_images()
{'Python 3.10': 'c72ae05e-2831-4c50-b20f-c2fe01c206ef',
 'Python 3.9': '5a32b827-cd9a-40a9-a99d-e58401120a0b',
   ...
}

modelid_to_modelname(model_id: str) → str

Get model name from a model_id.

Parameters:

model_id (str) –

Returns:

modelname

Return type:

str

models_of_account(account) → Dict[str, str]

Get all models (name and id) of an account

Parameters:

account (str) – account name

Returns:

modelname->model_id mapping, string->string

Return type:

dict

Example

>>> api = NumerAPI()
>>> NumerAPI().models_of_account("uuazed")
{'uuazed': '9b157d9b-ce61-4ab5-9413-413f13a0c0a6', ...}

pipeline_status(date: str | None = None) → Dict

Get status of Numerai’s scoring pipeline

Parameters:

date (str, optional) – date in YYYY-MM-DD format. Defaults to today.

Returns:

pipeline status information including the following fields:

• dataReadyAt (str)

• isScoringDay (bool)

• resolvedAt (datetime)

• scoredAt (datetime)

• startedAt (datetime)

• tournament (str)

Return type:

dict

Example

>>> napi = NumerAPI()
>>> napi.pipeline_status()

raw_query(query: str, variables: Dict | None = None, authorization: bool = False, retries: int = 3, delay: int = 5, backoff: int = 2)

Send a raw request to the Numerai’s GraphQL API.

This function allows to build your own queries and fetch results from Numerai’s GraphQL API. Checkout https://medium.com/numerai/getting-started-with-numerais-new-tournament-api-77396e895e72 for an introduction and https://api-tournament.numer.ai/ for the documentation.

Parameters:

• query (str) – your query

• variables (dict, optional) – dict of variables

• authorization (bool, optional) – does the request require authorization, defaults to False

• retries (int) – for 5XX errors, how often should numerapi retry

• delay (int) – in case of retries, how many seconds to wait between tries

• backoff (int) – in case of retries, multiplier to increase the delay between retries

Returns:

Result of the request

Return type:

dict

Raises:

ValueError – if something went wrong with the requests. For example, this could be a wrongly formatted query or a problem at Numerai’s end. Have a look at the error messages, in most cases the problem is obvious.

Example

>>> query = '''query($tournament: Int!)
               {rounds(tournament: $tournament number: 0)
                {number}}'''
>>> args = {'tournament': 1}
>>> NumerAPI().raw_query(query, args)
{'data': {'rounds': [{'number': 104}]}}

round_model_performances(username: str) → List[Dict]

Fetch round model performance of a user.

Parameters:

username (str) –

Returns:

list of round model performance entries

For each entry in the list, there is a dict with the following content:

• corr (float)

• corr20V2 (float or None)

• corr20V2Percentile (float or None)

• corr20d (float or None)

• corr20dPercentile (float or None)

• corrMultiplier (float)

• corrPercentile (float)

• corrWMetamodel (float)

• tc (float)

• tcPercentile (float)

• tcMultiplier (float)

• ic (float)

• icPercentile (float)

• fnc (float)

• fncPercentile (float)

• fncV3 (float)

• fncV3Percentile (float)

• mmc (float)

• mmc20d (float or None)

• mmc20dPercentile (float or None)

• mmcMultiplier (float)

• mmcPercentile (float)

• payout (Decimal)

• roundNumber (int)

• roundOpenTime (datetime)

• roundPayoutFactor (Decimal)

• roundResolveTime (datetime)

• roundResolved (bool)

• roundTarget (str or None)

• selectedStakeValue (Decimal)

Return type:

list of dicts

Example

>>> api = NumerAPI()
>>> api.round_model_performances("uuazed")
[{'corr': -0.01296840448965,
 'corr20V2': None,
 'corr20V2Percentile': None,
 'corr20d': None,
 'corr20dPercentile': None,
 'corrMultiplier': 1.0,
 'corrPercentile': 0.0411107104219257,
 'corrWMetamodel': 0.51542251407092,
 'tc': 0.1415973344,
 'tcPercentile': 0.115398485394879,
 'ic': 0.1415973344,
 'icPercentile': 0.115398485394879,
 'fnc': 0.000437631996046271,
 'fncPercentile': 0.115398485394879,
 'fncV3': 0.000437631996046271,
 'fncV3Percentile': 0.115398485394879,
 'mmc': -0.0152125841680981,
 'mmc20d': None,
 'mmc20dPercentile': None,
 ...
]

round_model_performances_v2(model_id: str)

Fetch round model performance of a user.

Parameters:

model_id (str) –

Returns:

list of round model performance entries

For each entry in the list, there is a dict with the following content:

• atRisk (float)

• corrMultiplier (float or None)

• tcMultiplier (float or None)

• roundNumber (int)

• roundOpenTime (datetime)

• roundResolveTime (datetime)

• roundResolved (bool)

• roundTarget (str)

• submissionScores (dict)

  • date (datetime)

  • day (int)

  • displayName (str): name of the metric

  • payoutPending (float)

  • payoutSettled (float)

  • percentile (float)

  • value (float): value of the metric

Return type:

list of dicts

set_bio(model_id: str, bio: str) → bool

Set bio field for a model id.

Parameters:

• model_id (str) – Target model UUID

• bio (str) –

Returns:

if the bio was changed successfully

Return type:

bool

Example

>>> napi = numerapi.NumerAPI()
>>> model_id = napi.get_models()["uuazed"]
>>> napi.set_bio(model_id, "This model stinks.")
True

set_global_data_dir(directory: str)

Set directory used for downloading files

Parameters:

directory (str) – directory to be used

set_link(model_id: str, link_text: str, link: str) → bool

Set link field for a model id.

Parameters:

• model_id (str) – Target model UUID

• link_test (str) –

• link (str) –

Returns:

if the bio was changed successfully

Return type:

bool

Example

>>> napi = numerapi.NumerAPI()
>>> model_id = napi.get_models()["uuazed"]
>>> napi.set_link(model_id, "buy my predictions", "numerbay.ai")
True

set_submission_webhook(model_id: str, webhook: str | None = None) → bool

Set a model’s submission webhook used in Numerai Compute. Read More: https://docs.numer.ai/tournament/compute

Parameters:

• model_id (str) – Target model UUID

• webhook (str) – The compute webhook to trigger this model

Returns:

confirmation that your webhook has been set

Return type:

bool

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> api.set_submission_webhook(model_id="..", webhook="..")
True

stake_change(nmr, action: str = 'decrease', model_id: str | None = None) → Dict

Change stake by value NMR.

Parameters:

• nmr (float or str) – amount of NMR you want to increase/decrease

• action (str) – increase or decrease

• model_id (str) – Target model UUID (required for accounts with multiple models)

Returns:

stake information with the following content:

• dueDate (datetime)

• status (str)

• requestedAmount (decimal.Decimal)

• type (str)

Return type:

dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.stake_change(10, "decrease", model)
{'dueDate': None,
 'requestedAmount': decimal.Decimal('10'),
 'type': 'decrease',
 'status': ''}

stake_decrease(nmr, model_id: str | None = None) → Dict

Decrease your stake by value NMR.

Parameters:

• nmr (float or str) – amount of NMR you want to reduce

• model_id (str) – Target model UUID (required for accounts with multiple models)

• tournament (int) – ID of the tournament (optional, defaults to 8)

Returns:

stake information with the following content:

• dueDate (datetime)

• status (str)

• requestedAmount (decimal.Decimal)

• type (str)

Return type:

dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.stake_decrease(10, model)
{'dueDate': None,
 'requestedAmount': decimal.Decimal('10'),
 'type': 'decrease',
 'status': ''}

stake_drain(model_id: str | None = None) → Dict

Completely remove your stake.

Parameters:

• model_id (str) – Target model UUID (required for accounts with multiple models)

• tournament (int) – ID of the tournament (optional, defaults to 8)

Returns:

stake information with the following content:

• dueDate (datetime)

• status (str)

• requestedAmount (decimal.Decimal)

• type (str)

Return type:

dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.stake_drain(model)
{'dueDate': None,
 'requestedAmount': decimal.Decimal('11000000'),
 'type': 'decrease',
 'status': ''}

stake_increase(nmr, model_id: str | None = None) → Dict

Increase your stake by value NMR.

Parameters:

• nmr (float or str) – amount of additional NMR you want to stake

• model_id (str) – Target model UUID (required for accounts with multiple models)

• tournament (int) – ID of the tournament (optional, defaults to 8) – DEPRECATED there is only one tournament nowadays

Returns:

stake information with the following content:

• dueDate (datetime)

• status (str)

• requestedAmount (decimal.Decimal)

• type (str)

Return type:

dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.stake_increase(10, model)
{'dueDate': None,
 'requestedAmount': decimal.Decimal('10'),
 'type': 'increase',
 'status': ''}

submission_ids(model_id: str)

Get all submission ids from a model

Parameters:

model_id (str) –

Returns:

list of submissions

For each entry in the list, there is a dict with the following content:

• insertedAt (datetime)

• filename (str)

• id (str)

Return type:

list of dicts

Example:

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model_id = napi.get_models()["uuazed"]
>>> api.submission_ids(model_id)

upload_diagnostics(file_path: str = 'predictions.csv', tournament: int | None = None, model_id: str | None = None, df: DataFrame | None = None) → str

Upload predictions to diagnostics from file.

Parameters:

• file_path (str) – CSV file with predictions that will get uploaded

• tournament (int) – ID of the tournament (optional, defaults to None) – DEPRECATED there is only one tournament nowadays

• model_id (str) – Target model UUID (required for accounts with multiple models)

• df (pandas.DataFrame) – pandas DataFrame to upload, if function is given df and file_path, df will be uploaded.

Returns:

diagnostics_id

Return type:

str

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model_id = api.get_models()['uuazed']
>>> api.upload_diagnostics("prediction.cvs", model_id=model_id)
'93c46857-fed9-4594-981e-82db2b358daf'
>>> # upload from pandas DataFrame directly:
>>> api.upload_diagnostics(df=predictions_df, model_id=model_id)

wallet_transactions() → List

Get all transactions in your wallet.

Returns:

List of dicts with the following structure:

• from (str)

• posted (bool)

• status (str)

• to (str)

• txHash (str)

• amount (decimal.Decimal)

• time (datetime)

• tournament (int)

Return type:

list

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> api.wallet_transactions()
[{'amount': Decimal('1.000000000000000000'),
  'from': '0x000000000000000000000000000000000000313bc',
  'status': 'confirmed',
  'time': datetime.datetime(2023, 4, 19, 13, 28, 45),
  'to': '0x000000000000000000000000000000000006621',
  'tournament': None,
  'txHash': '0xeasdfkjaskljf314451234',
  'type': 'withdrawal'},
  ...
  ]