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.

If you encounter a problem or have suggestions, feel free to open an issue.

pip install --upgrade numerapi

See example.py. You can run it as ./example.py

Some actions (like uploading predictions or staking) requires 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.

Parameters and return values are given with Python types. Dictionary keys are given in quotes; other names to the left of colons are for reference convenience only. In particular, lists of dicts have names for the dicts; these names will not show up in the actual data, only the actual dict data itself.

• dest_path (str, optional, default: .): destination folder for the dataset
• dest_filename (str, optional, default: numerai_dataset_<round number>.zip)
• unzip (bool, optional, default: True): indication of whether the training data should be unzipped

• path (string): location of the downloaded dataset

Fetch url of the current dataset.

• url (str): url of the current dataset

retrieves the leaderboard for the given round

• round_num (int, optional, defaults to current round): The round you are interested in.

• participants (list): information about all competitors
  • participants (dict)
    • "concordance" (dict)
      • "pending" (bool)
      • "value" (bool)
    • "originality" (dict)
      • "pending" (bool)
      • "value" (bool)
    • "consistency" (float)
    • "liveLogloss" (float or None)
    • "validationLogloss" (float)
    • "paymentGeneral" (dict or None)
      • "nmrAmount" (float)
      • "usdAmount" (float)
    • "paymentStaking" (dict or None)
      • "nmrAmount" (float)
      • "usdAmount" (float)
    • "submissionId" (str)
    • "totalPayments" (dict)
      • "nmrAmount" (float)
      • "usdAmount" (float)
    • "username" (str)

retrieves the leaderboard of the staking competition for the given round

• round_num (int, optional, defaults to current round): The round you are interested in.

• stakes (list): information about all competitors
  • participants (dict)
    • "username" (str)
    • "consistency" (float)
    • "liveLogloss" (float or None)
    • "validationLogloss" (float)
    • "stake" (dict)
      • "confidence" (float)
      • "insertedAt" (datetime)
      • "soc" (float)
      • "txHash" (str)
      • "value" (float)

• all_competitions (list): information about all competitions
  • competition (dict)
    • "datasetId" (str)
    • "number" (int)
    • "openTime" (datetime)
    • "resolveTime" (datetime)
    • "resolvedGeneral" (bool)
    • "resolvedStaking" (bool)

• number (int): number of the current round

get dict with username->submission_id mapping

• submission_ids (dict)
  • "username" (str)
  • "submissionId" (str): ID of submission

submission status of the given submission_id or the last submission done within the same session.

• submission_id (str, optional, default: None)

• status (dict)
  • "concordance" (dict):
    • "pending" (bool)
    • "value" (bool): whether the submission is concordant
  • "originality" (dict)
    • "pending" (bool)
    • "value" (bool): whether the submission is original
  • "consistency" (float): consistency of the submission
  • "validation_logloss" (float): amount of logloss for the submission

• file_path (str): path to CSV of predictions (e.g. "path/to/file/prediction.csv")

• submission_id: ID of submission

• user (dict)
  • "apiTokens" (list)
    • token (dict)
      • "name" (str)
      • "public_id" (str)
      • "scopes" (list)
        • scope (str)
  • "assignedEthAddress" (str)
  • "availableNmr" (float)
  • "availableUsd" (float)
  • "banned" (bool)
  • "email" (str)
  • "id" (str)
  • "insertedAt" (datetime)
  • "mfaEnabled" (bool)
  • "status" (str)
  • "username" (str)

• payments (list)
  • payment (dict)
    • "nmrAmount" (float)
    • "usdAmount" (float)
    • "tournament" (str)
    • "round" (dict)
      • "number" (int)
      • "openTime" (datetime)
      • "resolveTime" (datetime)
      • "resolvedGeneral" (bool)
      • "resolvedStaking" (bool)

• transactions (dict)
  • "nmrDeposits" (list)
    • nmrDeposit (dict)
      • "from" (str)
      • "id" (str)
      • "posted" (bool)
      • "status" (str)
      • "to" (str)
      • "txHash" (str)
      • "value" (float)
  • "nmrWithdrawals" (list)
    • nmrWithdrawal (dict)
      • "from" (str)
      • "id" (str)
      • "posted" (bool)
      • "status" (str)
      • "to" (str)
      • "txHash" (str)
      • "value" (float)
  • "usdWithdrawals" (list)
    • usdWithdrawal (dict)
      • "confirmTime" (datetime or None)
      • "ethAmount" (str)
      • "from" (str)
      • "posted" (bool)
      • "sendTime" (datetime)
      • "status" (str)
      • "to" (str)
      • "txHash" (str)
      • "usdAmount" (float)

participate in the staking competition

• confidence (float)
• value (float): the amount of NMR you want to stake

• stake (dict)
  • "id" (str)
  • "status" (str)
  • "txHash" (str)
  • "value" (float)

• stakes (list)
  • stake (dict)
    • "confidence" (float)
    • "roundNumber" (int)
    • "soc" (float)
    • "insertedAt" (str (datetime))
    • "staker" (str): NMR adress used for staking
    • "status" (str)
    • "txHash" (str)
    • "value" (float)

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.

• query (str)
• variables (dict, optional)
• authorization (bool, optional, default: False): indicates if a token is required

• data (dict)

Checks if a new round has started recently.

• hour (int, optional): timeframe to consider

• is_new_round (bool)

Check if the last submission passes concordance, originality and consistency tests

• submission_id (str, optional, default: None)

• success (bool)