numerapi package

Submodules

numerapi.base_api module

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

Bases: object

Wrapper around the Numerai API

get_account() → Dict[KT, VT][source]

Get all information about your account!

Returns:user information including the following 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_transactions() → Dict[KT, VT][source]

Get all your account deposits and withdrawals.

Returns:lists of your tournament wallet NMR transactions

The returned dict has the following structure:

  • nmrDeposits (list) contains items with fields:
  • from (str)
  • posted (bool)
  • status (str)
  • to (str)
  • txHash (str)
  • value (decimal.Decimal)
  • insertedAt (datetime)
  • nmrWithdrawals”` (list) contains items with fields:
  • from”` (str)
  • posted”` (bool)
  • status”` (str)
  • to”` (str)
  • txHash”` (str)
  • value”` (decimal.Decimal)
  • insertedAt (datetime)
Return type:dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> api.get_account_transactions()
{'nmrDeposits': [
    {'from': '0x54479..9ec897a',
     'posted': True,
     'status': 'confirmed',
     'to': '0x0000000000000000000001',
     'txHash': '0x52..e2056ab',
     'value': Decimal('9.0'),
     'insertedAt: datetime.datetime((2018, 2, 11, 17, 54, 2)},
     .. ],
 'nmrWithdrawals': [
    {'from': '0x0000000000000000..002',
     'posted': True,
     'status': 'confirmed',
     'to': '0x00000000000..001',
     'txHash': '0x1278..266c',
     'value': Decimal('2.0'),
     'insertedAt: datetime.datetime((2018, 2, 11, 17, 54, 2)},},
     .. ]}
get_models() → Dict[KT, VT][source]

Get mapping of account model names to model ids for convenience

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'}
get_transactions(model_id: str = None) → Dict[KT, VT][source]

Get all your deposits and withdrawals.

Parameters:model_id (str) – Target model UUID (required for accounts with multiple models)
Returns:lists of your NMR and USD transactions

The returned dict has the following structure:

  • nmrDeposits (list) contains items with fields:
  • from (str)
  • posted (bool)
  • status (str)
  • to (str)
  • txHash (str)
  • value (decimal.Decimal)
  • insertedAt (datetime)
  • nmrWithdrawals”` (list) contains items with fields:
  • from”` (str)
  • posted”` (bool)
  • status”` (str)
  • to”` (str)
  • txHash”` (str)
  • value”` (decimal.Decimal)
  • insertedAt (datetime)
  • usdWithdrawals”` (list) contains items with fields:
  • confirmTime”` (datetime or None)
  • ethAmount”` (str)
  • from”` (str)
  • posted”` (bool)
  • sendTime”` (datetime)
  • status”` (str)
  • to (str)
  • txHash (str)
  • usdAmount (decimal.Decimal)
Return type:dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.get_transactions(model)
{'nmrDeposits': [
    {'from': '0x54479..9ec897a',
     'posted': True,
     'status': 'confirmed',
     'to': '0x0000000000000000000001',
     'txHash': '0x52..e2056ab',
     'value': Decimal('9.0'),
     'insertedAt: datetime.datetime((2018, 2, 11, 17, 54, 2)},
     .. ],
 'nmrWithdrawals': [
    {'from': '0x0000000000000000..002',
     'posted': True,
     'status': 'confirmed',
     'to': '0x00000000000..001',
     'txHash': '0x1278..266c',
     'value': Decimal('2.0'),
     'insertedAt: datetime.datetime((2018, 2, 11, 17, 54, 2)},},
     .. ],
 'usdWithdrawals': [
    {'confirmTime': datetime.datetime(2018, 2, 11, 17, 54, 2),
     'ethAmount': '0.295780674909307710',
     'from': '0x11.....',
     'posted': True,
     'sendTime': datetime.datetime(2018, 2, 11, 17, 53, 25),
     'status': 'confirmed',
     'to': '0x81.....',
     'txHash': '0x3c....',
     'usdAmount': Decimal('10.07')},
     ..]}
raw_query(query, variables=None, authorization=False)[source]

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

numerapi.cli module

numerapi.cli.prettify(stuff)[source]

numerapi.numerapi module

class numerapi.numerapi.NumerAPI(public_id=None, secret_key=None, verbosity='INFO', show_progress_bars=True)[source]

Bases: numerapi.base_api.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 allows downloading the training data, uploading predictions, accessing user, submission and competitions information and much more.

check_new_round(hours: int = 24, tournament: int = 8) → bool[source]

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

Parameters:
  • hours (int, optional) – timeframe to consider, defaults to 24
  • tournament (int) – ID of the tournament (optional, defaults to 8)
Returns:

True if a new round has started, False otherwise.

Return type:

bool

Example

>>> NumerAPI().check_new_round()
False
daily_submissions_performances(username: str) → List[Dict[KT, VT]][source]

Fetch daily performance of a user’s submissions.

Parameters:username (str) –
Returns:list of daily submission performance entries

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

  • date (datetime)
  • correlation (float)
  • roundNumber (int)
  • mmc (float)
  • correlationWithMetamodel (float)
Return type:list of dicts

Example

>>> api = NumerAPI()
>>> api.daily_user_performances("uuazed")
[{'roundNumber': 181,
  'correlation': -0.011765912,
  'date': datetime.datetime(2019, 10, 16, 0, 0),
  'mmc': 0.3,
  'correlationWithMetamodel': 0.87},
  ...
]
daily_user_performances(username: str) → List[Dict[KT, VT]][source]

Fetch daily performance of a user.

Parameters:username (str) –
Returns:list of daily user performance entries

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

  • tier (str)
  • stakeValue (float or none)
  • reputation (float) – DEPRECATED since 2020-04-05
  • rolling_score_rep (float)
  • rank (int)
  • leaderboardBonus (float or None)
  • date (datetime)
  • averageCorrelationPayout (float or None)
  • averageCorrelation (float)
  • sumDeltaCorrelation (float)
  • finalCorrelation (float)
  • payoutPending (float or None)
  • payoutSettled (float or None)
Return type:list of dicts

Example

>>> api = NumerAPI()
>>> api.daily_user_performances("uuazed")
[{'tier': 'A',
  'stakeValue': None,
  'reputation': 0.0017099,
  'rolling_score_rep': 0.0111,
  'rank': 32,
  'leaderboardBonus': None,
  'date': datetime.datetime(2019, 10, 16, 0, 0),
  'averageCorrelationPayout': None,
  'averageCorrelation': -0.000983637,
  'sumDeltaCorrelation': -0.000983637,
  'finalCorrelation': -0.000983637,
  'payoutPending': None,
  'payoutSettled': None},
  ...
]
download_current_dataset(dest_path='.', dest_filename=None, unzip=True, tournament=8)[source]

Download dataset for the current active round.

Parameters:
  • dest_path (str, optional) – destination folder, defaults to .
  • dest_filename (str, optional) – desired filename of dataset file, defaults to numerai_dataset_<round number>.zip
  • unzip (bool, optional) – indication of whether the training data should be unzipped, defaults to True
  • tournament (int, optional) – ID of the tournament, defaults to 8
Returns:

Path to the downloaded dataset

Return type:

str

Example

>>> NumerAPI().download_current_dataset()
./numerai_dataset_104.zip
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:

  • datasetId (str)
  • number (int)
  • openTime (datetime)
  • resolveTime (datetime)
  • participants (int): number of participants
  • prizePoolNmr (decimal.Decimal)
  • prizePoolUsd (decimal.Decimal)
  • resolvedGeneral (bool)
  • resolvedStaking (bool)
  • ruleset (string)
Return type:list of dicts

Example

>>> NumerAPI().get_competitions()
[
 {'datasetId': '59a70840ca11173c8b2906ac',
  'number': 71,
  'openTime': datetime.datetime(2017, 8, 31, 0, 0),
  'resolveTime': datetime.datetime(2017, 9, 27, 21, 0),
  'participants': 1287,
  'prizePoolNmr': Decimal('0.00'),
  'prizePoolUsd': Decimal('6000.00'),
  'resolvedGeneral': True,
  'resolvedStaking': True,
  'ruleset': 'p_auction'
 },
  ..
]
get_current_round(tournament=8)[source]

Get number of the current active round.

Parameters:tournament (int) – ID of the tournament (optional, defaults to 8)
Returns:number of the current active round
Return type:int

Example

>>> NumerAPI().get_current_round()
104
get_dataset_url(tournament=8)[source]

Fetch url of the current dataset.

Parameters:tournament (int, optional) – ID of the tournament, defaults to 8
Returns:url of the current dataset
Return type:str

Example

>>> NumerAPI().get_dataset_url()
https://numerai-datasets.s3.amazonaws.com/t1/104/n.........
get_leaderboard(limit: int = 50, offset: int = 0) → List[Dict[KT, VT]][source]

Get the current 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)
  • tier (str)
  • reputation (float) – DEPRECATED since 2020-04-05
  • rolling_score_rep (float)
  • rank (int)
  • prevRank (int)
  • stakedRank (int)
  • prevStakedRank (int)
  • nmrStaked (decimal.Decimal)
  • oldStakeValue (decimal.Decimal)
  • leaderboardBonus (decimal.Decimal)
  • averageCorrelationPayout (decimal.Decimal)
  • payoutPending (decimal.Decimal)
  • payoutSettled (decimal.Decimal)
  • bonusPerc (float)
  • badges (list of str)

Return type:

list of dicts

Example

>>> numerapi.NumerAPI().get_leaderboard(1)
[{'username': 'anton',
  'tier': 'C',
  'reputation': -0.00499721,
  'rolling_score_rep': -0.00499721,
  'rank': 143,
  'prevRank': 116,
  'stakedRank': 103,
  'prevStakedRank': 102,
  'nmrStaked': Decimal('12'),
  'oldStakeValue': Decimal('12'),
  `leaderboardBonus`: Decimal('0.1')
  `averageCorrelationPayout`: Decimal('0.1')
  `payoutPending`: Decimal('0.1')
  `payoutSettled`: Decimal('0.1')
  'bonusPerc': 0.5,
  'badges': ['submission-streak_1', 'burned_2']}]
get_payments(model_id: str = None) → Dict[KT, VT][source]

Get all your payments.

Parameters:model_id (str) – Target model UUID (required for accounts with multiple models)
Returns:payments & reputationPayments
A dict containing the following items:
  • payments (list) * nmrAmount (decimal.Decimal) * usdAmount (decimal.Decimal) * tournament (str) * round (dict)
    • number (int)
    • openTime (datetime)
    • resolveTime (datetime)
    • resolvedGeneral (bool)
    • resolvedStaking (bool)
  • reputationPayment (list) * nmrAmount (decimal.Decimal) * insertedAt (datetime)
Return type:dict of lists

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.get_payments(model)
{'payments': [
    {'nmrAmount': Decimal('0.00'),
     'round': {'number': 84,
     'openTime': datetime.datetime(2017, 12, 2, 18, 0),
     'resolveTime': datetime.datetime(2018, 1, 1, 18, 0),
     'resolvedGeneral': True,
     'resolvedStaking': True},
     'tournament': 'staking',
     'usdAmount': Decimal('17.44')},
     ...
    ],
 'reputationPayments': [
   {'nmrAmount': Decimal('0.1'),
    'insertedAt': datetime.datetime(2017, 12, 2, 18, 0)},
    ...
    ],
 'otherUsdIssuances': [
    {'usdAmount': Decimal('0.1'),
     'insertedAt': datetime.datetime(2017, 12, 2, 18, 0)},
     ...
 ]
}
get_stakes(model_id: str = None) → List[Dict[KT, VT]][source]

List all your stakes.

Parameters:model_id (str) – Target model UUID (required for accounts with multiple models)
Returns:stakes

Each stake is a dict with the following fields:

  • confidence (decimal.Decimal)
  • roundNumber (int)
  • tournamentId (int)
  • soc (decimal.Decimal)
  • insertedAt (datetime)
  • staker (str): NMR adress used for staking
  • status (str)
  • txHash (str)
  • value (decimal.Decimal)
Return type:list of dicts

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.get_stakes(model)
[{'confidence': Decimal('0.053'),
  'insertedAt': datetime.datetime(2017, 9, 26, 8, 18, 36, 709000),
  'roundNumber': 74,
  'soc': Decimal('56.60'),
  'staker': '0x0000000000000000000000000000000000003f9e',
  'status': 'confirmed',
  'tournamentId': 1,
  'txHash': '0x1cbb985629552a0f57b98a1e30acef02e02aaf0e91c95',
  'value': Decimal('3.00')},
  ..
 ]
get_submission_filenames(tournament=None, round_num=None, model_id=None) → List[Dict[KT, VT]][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}]
get_submission_ids(tournament=8)[source]

Get dict with username->submission_id mapping.

Parameters:tournament (int) – ID of the tournament (optional, defaults to 8)
Returns:username->submission_id mapping, string->string
Return type:dict

Example

>>> NumerAPI().get_submission_ids()
{'1337ai': '93c46857-fed9-4594-981e-82db2b358daf',
 '1x0r': '108c7601-822c-4910-835d-241da93e2e24',
 ...
 }
get_tournaments(only_active=True)[source]

Get all tournaments

Parameters:only_active (bool) – Flag to indicate of only active tournaments should be returned or all of them. Defaults to True.
Returns:list of tournaments

Each tournaments’ dict contains the following items:

  • id (str)
  • name (str)
  • tournament (int)
  • active (bool)
Return type:list of dicts

Example

>>> NumerAPI().get_tournaments()
[ { 'id': '2ecf30f4-4b4f-42e9-8e72-cc5bd61c2733',
    'name': 'alpha',
    'tournament': 1,
    'active': True},
  { 'id': '6ff44cca-263d-40bd-b029-a1ab8f42798f',
    'name': 'bravo',
    'tournament': 2,
    'active': True},
  { 'id': 'ebf0d62b-0f60-4550-bcec-c737b168c65d',
    'name': 'charlie',
    'tournament': 3
    'active': False},
  { 'id': '5fac6ece-2726-4b66-9790-95866b3a77fc',
    'name': 'delta',
    'tournament': 4,
    'active': True}]
get_user(model_id: str = None) → Dict[KT, VT][source]

Get all information about you! DEPRECATED

Parameters:model_id (str) – Target model UUID (required for accounts with multiple models)
Returns:user information including the following fields:
  • assignedEthAddress (str)
  • availableNmr (decimal.Decimal)
  • availableUsd (decimal.Decimal)
  • banned (bool)
  • email (str)
  • id (str)
  • insertedAt (datetime)
  • mfaEnabled (bool)
  • status (str)
  • username (str)
  • country (`str)
  • apiTokens (list) each with the following fields:
  • name (str)
  • public_id (str)
  • scopes (list of str)
  • v2Stake
  • status (str)
  • txHash (str)
Return type:dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.get_user(model)
{'apiTokens': [
        {'name': 'tokenname',
         'public_id': 'BLABLA',
         'scopes': ['upload_submission', 'stake', ..]
         }, ..],
 'assignedEthAddress': '0x0000000000000000000000000001',
 'availableNmr': Decimal('99.01'),
 'availableUsd': Decimal('9.47'),
 'banned': False,
 'email': 'username@example.com',
 'country': 'US',
 'id': '1234-ABC..',
 'insertedAt': datetime.datetime(2018, 1, 1, 2, 16, 48),
 'mfaEnabled': False,
 'status': 'VERIFIED',
 'username': 'cool username',
 'v2Stake': None
 }
get_user_activities(username, tournament=8)[source]

Get user activities (works for all users!).

Parameters:
  • username (str) – name of the user
  • tournament (int) – ID of the tournament (optional, defaults to 8)
Returns:

list of user activities (dict)

Each activity in the list as the following structure:

  • resolved (bool)
  • roundNumber (int)
  • tournament (int)
  • submission (dict)
  • concordance (bool)
  • consistency (float)
  • date (datetime)
  • liveLogloss (float)
  • liveAuroc (float)
  • liveCorrelation (float)
  • validationLogloss (float)
  • validationAuroc (float)
  • validationCorrelation (float)
  • stake (dict)
  • confidence (decimal.Decimal)
  • date (datetime)
  • nmrEarned (decimal.Decimal)
  • staked (bool)
  • usdEarned (decimal.Decimal)
  • burned (bool)

Return type:

list

Example

>>> NumerAPI().get_user_activities("slyfox", 5)
[{'tournament': 5,
  'submission': {
   'validationLogloss': 0.6928141372700635,
   'validationAuroc': 0.52,
   'validationCorrelation': 0.52,
   'liveLogloss': None,
   'liveAuroc': None,
   'liveCorrelation': None,
   'date': datetime.datetime(2018, 7, 14, 17, 5, 27, 206042),
   'consistency': 83.33333333333334,
   'concordance': True},
  'stake': {'value': Decimal('0.10'),
   'usdEarned': None,
   'staked': True,
   'nmrEarned': None,
   'date': datetime.datetime(2018, 7, 14, 17, 7, 7, 877845),
   'confidence': Decimal('0.100000000000000000')},
   'burned': False
  'roundNumber': 116,
  'resolved': False},
 {'tournament': 5,
  'submission': {'validationLogloss': 0.6928141372700635,

]

get_v1_leaderboard(round_num=0, tournament=8)[source]

Retrieves the leaderboard for the given round.

Parameters:
  • round_num (int, optional) – The round you are interested in, defaults to current round.
  • tournament (int, optional) – ID of the tournament, defaults to 8
Returns:

list of participants

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

  • concordance (dict)
  • pending (bool)
  • value (bool)
  • consistency (float)
  • liveLogloss (float or None)
  • liveAuroc (float or None)
  • liveCorrelation (float or None)
  • validationLogloss (float)
  • validationAuroc (float or None)
  • validationCorrelation (float or None)
  • paymentGeneral (dict or None)
  • nmrAmount (decimal.Decimal)
  • usdAmount (decimal.Decimal)
  • paymentStaking (dict or None)
  • nmrAmount (decimal.Decimal)
  • usdAmount (decimal.Decimal)
  • submissionId (str)
  • username (str)
  • stakeResolution (dict)
  • destroyed (bool)
  • paid (decimal.Decimal)
  • successful (‘bool’)
  • return (dict)
  • nmrAmount (decimal.Decimal)
  • status (str)

Return type:

list of dicts

Example

>>> NumerAPI().get_v1_leaderboard(99)
[{'concordance': {'pending': False, 'value': True},
  'consistency': 83.33333333333334,
  'liveLogloss': 0.6941153941722517,
  'liveAuroc': 0.5368847103148798,
  'liveCorrelation': 0.536898,
  'paymentGeneral': None,
  'paymentStaking': None,
  'submissionId': '4459d3df-0a4b-4996-ad44-41abb7c45336',
  'stakeResolution': {'destroyed': False,
                      'paid': Decimal('19.86'),
                      'successful': True},
  'return': {'nmrAmount': Decimal('0.3'),
             'status': ''}
  'username': 'ci_wp',
  'validationLogloss': 0.692269984475575},
  'validationAuroc': 0.6368847103148798,
  'validationCorrelation': 0.54342
 ...
]
public_user_profile(username: str) → Dict[KT, VT][source]

Fetch the public profile of a user.

Parameters:username (str) –
Returns:user profile including the following fields:
  • username (str)
  • startDate (datetime)
  • netEarnings (float)
  • id (string)
  • historicalNetUsdEarnings (float)
  • historicalNetNmrEarnings (float)
  • badges (list of str)
  • bio (str)
  • totalStake (float)
Return type:dict

Example

>>> api = NumerAPI()
>>> api.public_user_profile("niam")
{'username': 'niam',
 'startDate': datetime.datetime(2018, 6, 14, 22, 58, 2, 186221),
 'netEarnings': None,
 'id': '024c9bb9-77af-4b3f-91c7-63062fce2b80',
 'historicalNetUsdEarnings': '3669.41',
 'historicalNetNmrEarnings': '1094.247665827645663410',
 'badges': ['burned_3', 'compute_0', 'submission-streak_1'],
 'bio': 'blabla',
 'totalStake': 12.2}
round_details(round_num: int) → List[Dict[KT, VT]][source]

Fetch all correlation scores of a round.

Parameters:round_num (int) –
Returns:list containing scores for each user

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

  • date (datetime)
  • correlation (float)
  • username (str)
Return type:list of dicts

Example

>>> api = NumerAPI()
>>> api.round_details(180)
[{'username': 'abcd',
  'date': datetime.datetime(2019, 11, 15, 0, 0),
  'correlation': 0.02116131087},
  ...
]
stake_change(nmr, action: str = 'decrease', model_id: str = None) → Dict[KT, VT][source]

Change stake by value NMR.

Parameters:
  • nmr (float or str) – amount of NMR you want to reduce
  • 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_decrease(10, model)
{'dueDate': None,
 'requestedAmount': decimal.Decimal('10'),
 'type': 'decrease',
 'status': ''}
stake_decrease(nmr, model_id: str = None) → Dict[KT, VT][source]

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)
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) → Dict[KT, VT][source]

Completely remove your stake.

Parameters: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_drain(model)
{'dueDate': None,
 'requestedAmount': decimal.Decimal('11000000'),
 'type': 'decrease',
 'status': ''}
stake_get(username: str) → float[source]

Get your current stake amount.

Parameters:username (str) –
Returns:current stake
Return type:float

Example

>>> api = NumerAPI()
>>> api.stake_get("uuazed")
1.1
stake_increase(nmr, model_id: str = None) → Dict[KT, VT][source]

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)
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': ''}
stake_set(nmr) → Dict[KT, VT][source]

Set stake to value by decreasing or increasing your current stake

Parameters:nmr (float or str) – amount of NMR 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'}
submission_status(model_id: str = None) → Dict[KT, VT][source]

submission status of the last submission associated with the account

Parameters:model_id (str) –
Returns:submission status with the following content:
  • concordance (dict):
  • pending (bool)
  • value (bool): whether the submission is concordant
  • consistency (float): consistency of the submission
  • validationCorrelation (float)
  • filename (string)
  • corrWithExamplePreds (float)
  • validationFeatureExposure (float)
  • validationSharpe (float)
Return type:dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model_id = api.get_models()['uuazed']
>>> api.submission_status(model_id)
{'concordance': None,
 'consistency': None,
 'corrWithExamplePreds': 0.3811635610849811,
 'filename': 'model57-HPzOyr56TPaD.csv',
 'validationCorrelation': 0.02967954913128146,
 'validationFeatureExposure': 0.09736206063204657,
 'validationSharpe': 1.5567641700803665}
tournament_name2number(name: str) → int[source]

Translate tournament name to tournament number.

Parameters:name (str) – tournament name to translate
Returns:number of the tournament or None if unknown.
Return type:number (int)

Examples

>>> NumerAPI().tournament_name2number('delta')
4
>>> NumerAPI().tournament_name2number('foo')
None
tournament_number2name(number: int) → str[source]

Translate tournament number to tournament name.

Parameters:number (int) – tournament number to translate
Returns:name of the tournament or None if unknown.
Return type:name (str)

Examples

>>> NumerAPI().tournament_number2name(4)
'delta'
>>> NumerAPI().tournament_number2name(99)
None
upload_predictions(file_path: str, tournament: int = 8, model_id: str = None) → str[source]

Upload predictions from file.

Parameters:
  • file_path (str) – CSV file with predictions that will get uploaded
  • tournament (int) – ID of the tournament (optional, defaults to 8)
  • model_id (str) – Target model UUID (required for accounts with multiple models)
Returns:

submission_id

Return type:

str

Example

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

numerapi.signalsapi module

class numerapi.signalsapi.SignalsAPI(public_id=None, secret_key=None, verbosity='INFO', show_progress_bars=True)[source]

Bases: numerapi.base_api.Api

daily_submissions_performances(username: str) → List[Dict[KT, VT]][source]

Fetch daily Numerai Signals performance of a user’s submissions.

Parameters:username (str) –
Returns:list of daily submission performance entries

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

  • date (datetime)
  • returns (float)
  • submission_time (datetime)
Return type:list of dicts

Example

>>> api = SignalsAPI()
>>> api.daily_submissions_performances("floury_kerril_moodle")
[{'date': datetime.datetime(2020, 5, 16, 0, 0),
  'returns': 1.256,
  'submissionTime': datetime.datetime(2020, 5, 12, 1, 23)},
 ...
daily_user_performances(username: str) → List[Dict[KT, VT]][source]

Fetch daily Numerai Signals performance of a user.

Parameters:username (str) –
Returns:list of daily user performance entries

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

  • rank (int)
  • date (datetime)
  • sharpe (float)
Return type:list of dicts

Example

>>> api = SignalsAPI()
>>> api.daily_user_performances("floury_kerril_moodle")
[{'date': datetime.datetime(2020, 5, 16, 0, 0,
  'rank': 1,
  'sharpe': 2.35},
 ...]
get_leaderboard(limit: int = 50, offset: int = 0) → List[Dict[KT, VT]][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)
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'}]
public_user_profile(username: str) → Dict[KT, VT][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)
  • rank (int)
  • bio (str)
  • sharpe (float)
Return type:dict

Example

>>> api = SignalsAPI()
>>> api.public_user_profile("floury_kerril_moodle")
{'bio': None,
 'id': '635db2a4-bdc6-4e5d-b515-f5120392c8c9',
 'rank': 1,
 'sharpe': 2.35,
 'startDate': datetime.datetime(2019, 3, 26, 0, 43),
 'username': 'floury_kerril_moodle'}
submission_status(model_id: str = None) → Dict[KT, VT][source]

submission status of the last submission associated with the account

Parameters:model_id (str) –
Returns:submission status with the following content:
  • firstEffectiveDate (datetime.datetime):
  • userId (string)
  • filename (string)
  • id (string)
  • submissionIp (string)
  • submittedCount (int)
  • filteredCount (int)
Return type:dict

Example

>>> api = SignalsAPI(secret_key="..", public_id="..")
>>> model_id = api.get_models()['uuazed']
>>> api.submission_status(model_id)
{'firstEffectiveDate': datetime.datetime(2020, 5, 12, 1, 23),
 'userId': "slyfox",
 'filename': 'model57-HPzOyr56TPaD.csv',
 'id': '1234'
 'submissionIp': "102.142.12.12",
 'submittedCount': 112,
 'filteredCount': 12}
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(file_path: str, model_id: str = None) → str[source]

Upload predictions from file.

Parameters:
  • file_path (str) – CSV file with predictions that will get uploaded
  • model_id (str) – Target model UUID (required for accounts with multiple models)
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'

numerapi.utils module

numerapi.utils.download_file(url, dest_path, show_progress_bars=True)[source]
numerapi.utils.ensure_directory_exists(path)[source]
numerapi.utils.parse_datetime_string(s)[source]
numerapi.utils.parse_float_string(s)[source]
numerapi.utils.post_with_err_handling(url, body, headers, timeout=None)[source]
numerapi.utils.replace(dictionary, key, function)[source]

Module contents