numerapi package¶

Submodules¶

Module contents¶

Numerai Python API

class numerapi.CryptoAPI(*args, **kwargs)[source]¶

Bases: Api

“API for Numerai Crypto

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

Get the current Numerai Crypto leaderboard with a reduced set of fields.

Returns:

each dict contains only the requested fields:

nmrStaked
rank
username
corrRep
mmcRep
return_1_day
return_52_weeks
return_13_weeks

Return type:

list of dicts

class numerapi.NumerAPI(*args, **kwargs)[source]¶

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][source]¶

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)[source]¶

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][source]¶

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][source]¶

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[source]¶

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[source]¶

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[source]¶

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'}

class numerapi.SignalsAPI(*args, **kwargs)[source]¶

Bases: Api

“API for Numerai Signals

daily_model_performances(username: str) → List[Dict][source]¶

Fetch daily Numerai Signals performance of a model.

Parameters:

username (str)

Returns:

list of daily user performance entries

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

date (datetime)

corrRank (int)

corrRep (float or None)

mmcRank (int)

mmcRep (float or None)

icRank (int)

icRep (float or None)

tcRank (int)

tcRep (float or None)

corr20dRank (int)

corr20dRep (float or None)

corr60Rank (int)

corr60Rep (float or None)

mmc20dRank (int)

mmc20dRep (float or None)

Return type:

list of dicts

Example

>>> api = SignalsAPI()
>>> api.daily_model_performances("floury_kerril_moodle")
[{'corrRank': 45,
  'corrRep': -0.00010935616731632354,
  'corr20dRank': None,
  'corr20dRep': None,
  'mmc20dRank': None,
  'mmc20dRep': None,
  'date': datetime.datetime(2020, 9, 18, 0, 0, tzinfo=tzutc()),
  'mmcRank': 6,
  'mmcRep': 0.0,
  'icRank': 6,
  'icRep': 0.0,
  ...},
  ...
  ]

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

Get the current Numerai Signals leaderboard :param limit: number of items to return (optional, defaults to 50) :type limit: int :param offset: number of items to skip (optional, defaults to 0) :type offset: int

Returns:

list of leaderboard entries Each dict contains the following items:

username (str)

sharpe (float)

rank (int)

prevRank (int)

today (float)

mmc (float)

mmcRank (int)

icRep (float)

icRank (int)

tcRep (float)

tcRank (int)

nmrStaked (float)

Return type:

list of dicts

Example

>>> numerapi.SignalsAPI().get_leaderboard(1)
[{'prevRank': 1,
  'rank': 1,
  'sharpe': 2.3,
  'today': 0.01321,
  'username': 'floury_kerril_moodle',
  'mmc': -0.0101202715,
  'mmcRank': 30,
  'nmrStaked': 13.0,
  'icRep': -0.0101202715,
  'icRank': 30,
  ..
 }]

public_user_profile(username: str) → Dict[source]¶

Fetch the public Numerai Signals profile of a user.

Parameters:

username (str)

Returns:

user profile including the following fields:

username (str)

startDate (datetime)

id (string)

bio (str)

nmrStaked (decimal.Decimal)

Return type:

dict

Example

>>> api = SignalsAPI()
>>> api.public_user_profile("floury_kerril_moodle")
{'bio': None,
 'id': '635db2a4-bdc6-4e5d-b515-f5120392c8c9',
 'startDate': datetime.datetime(2019, 3, 26, 0, 43),
 'username': 'floury_kerril_moodle',
 'nmrStaked': Decimal('14.630994874320760131')}

stake_get(username) → Decimal[source]¶

get current stake for a given users

Parameters:: username (str)
Returns:: current stake
Return type:: decimal.Decimal

Example

>>> SignalsAPI().stake_get("uuazed")
Decimal('14.63')

ticker_universe() → List[str][source]¶

fetch universe of accepted tickers

Returns:: list of currently accepted tickers
Return type:: list of strings

Example

>>> SignalsAPI().ticker_universe()
["MSFT", "AMZN", "APPL", ...]

Upload predictions from file. Will read TRIGGER_ID from the environment if this model is enabled with a Numerai Compute cluster setup by Numerai CLI.

Parameters:

file_path (str) – CSV file with predictions that will get uploaded
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
timeout (float|tuple(float,float)) – waiting time (connection timeout, read timeout)

Returns:

submission_id

Return type:

str

Example

>>> api = SignalsAPI(secret_key="..", public_id="..")
>>> model_id = api.get_models()['uuazed']
>>> api.upload_predictions("prediction.cvs", model_id=model_id)
'93c46857-fed9-4594-981e-82db2b358daf'

>>> # upload directly from a pandas DataFrame:
>>> api.upload_predictions(df = predictions_df, model_id=model_id)