numerapi.numerapi module

API for Numerai Classic

class numerapi.numerapi.NumerAPI(*args, **kwargs)

Bases: Api

Wrapper around the Numerai 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 implemented in Python and tournamentallows downloading the training data, uploading predictions, accessing user, submission and competitions information and much more.

daily_model_performances(username: str) → List[Dict]

Fetch daily performance of a user.

Parameters:

username (str)

Returns:

list of daily model performance entries

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

• date (datetime)

• corrRep (float or None)

• corrRank (int)

• mmcRep (float or None)

• mmcRank (int)

• fncRep (float or None)

• fncRank (int)

• fncV3Rep (float or None)

• fncV3Rank (int)

• tcRep (float or None)

• tcRank (int)

Return type:

list of dicts

Example

>>> api = NumerAPI()
>>> api.daily_model_performances("uuazed")
[{'corrRank': 485,
 'corrRep': 0.027951873730771848,
 'date': datetime.datetime(2021, 9, 14, 0, 0, tzinfo=tzutc()),
 'fncRank': 1708,
 'fncRep': 0.014548700790462122,
 'tcRank': 1708,
 'tcRep': 0.014548700790462122,
 'fncV3Rank': 1708,
 'fncV3Rep': 0.014548700790462122,
 'mmcRank': 508,
 'mmcRep': 0.005321406467445256},
 ...
]

get_competitions(tournament=8)

Retrieves information about all competitions

Parameters:

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

Returns:

list of rounds

Each round’s dict contains the following items:

• number (int)

• openTime (datetime)

• resolveTime (datetime)

• resolvedGeneral (bool)

• resolvedStaking (bool)

Return type:

list of dicts

Example

>>> NumerAPI().get_competitions()
[
 {'number': 71,
  'openTime': datetime.datetime(2017, 8, 31, 0, 0),
  'resolveTime': datetime.datetime(2017, 9, 27, 21, 0),
  'resolvedGeneral': True,
  'resolvedStaking': True,
 },
  ..
]

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

Get the current model 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)

• rank (int)

• nmrStaked (decimal.Decimal)

• corr20Rep (float)

• corj60Rep (float)

• fncRep (float)

• fncV3Rep (float)

• tcRep (float)

• mmcRep (float)

• bmcRep (float)

• team (bool)

• return_1_day (float)

• return_52_day (float)

• return_13_day (float)

Return type:

list of dicts

Example

>>> numerapi.NumerAPI().get_leaderboard(1)
[{'username': 'anton',
  'rank': 143,
  'nmrStaked': Decimal('12'),
  ...
  }]

get_submission_filenames(tournament=None, round_num=None, model_id=None) → List[Dict]

Get filenames of the submission of the user.

Parameters:

• tournament (int) – optionally filter by ID of the tournament

• round_num (int) – optionally filter round number

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

Returns:

list of user filenames (dict)

Each filenames in the list as the following structure:

• filename (str)

• round_num (int)

• tournament (int)

Return type:

list

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.get_submission_filenames(3, 111, model)
[{'filename': 'model57-dMpHpYMPIUAF.csv',
  'round_num': 111,
  'tournament': 3}]

public_user_profile(username: str) → Dict

Fetch the public profile of a user.

Parameters:

username (str)

Returns:

user profile including the following fields:

• username (str)

• startDate (datetime)

• id (string)

• bio (str)

• nmrStaked (float)

Return type:

dict

Example

>>> api = NumerAPI()
>>> api.public_user_profile("integration_test")
{'bio': 'The official example model. Submits example predictions.',
 'id': '59de8728-38e5-45bd-a3d5-9d4ad649dd3f',
 'startDate': datetime.datetime(
    2018, 6, 6, 17, 33, 21, tzinfo=tzutc()),
 'nmrStaked': '57.582371875005243780',
 'username': 'integration_test'}

stake_get(modelname: str) → float

Get your current stake amount.

Parameters:

modelname (str)

Returns:

current stake (including projected NMR earnings from open

rounds)

Return type:

float

Example

>>> api = NumerAPI()
>>> api.stake_get("uuazed")
1.1

stake_set(nmr, model_id: str) → Dict

Set stake to value by decreasing or increasing your current stake

Parameters:

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

• model_id (str) – model_id for where you want to stake

Returns:

stake information with the following content:

• insertedAt (datetime)

• status (str)

• txHash (str)

• value (decimal.Decimal)

• source (str)

• to (str)

• from (str)

• posted (bool)

Return type:

dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> api.stake_set(10)
{'from': None,
 'insertedAt': None,
 'status': None,
 'txHash': '0x76519...2341ca0',
 'from': '',
 'to': '',
 'posted': True,
 'value': '10'}