NAV Navbar
protocol python csharp
  • Private API Introduction
  • Private API Calls
  • Data Types
  • Public API Introduction
  • Public API Calls
  • API Libraries & Source Code
  • Private API Introduction

    The Fairlay Private API allows you to POST requests (creating/changing markets and orders, transfering funds, etc.), costs 0.1mBTC per 100.000 requests, see below on how to create your developer API account.

    This is the low level documentation, if you need a working sample or are more comfortable reading code rather than specifications, head over to .NET API Library or Python API Library


    1. An account registered at fairlay
    2. A 2048 bits PEM RSA Key pair. There are multiple types of tools to generate it for you. Tools SSL Example
    3. Create an API account in profile page at Will be requested to provide your public key on form.


    All requests should be made to this endpoint:

    You must sign messages with your RSA key and provide your signature with all requests:


    The signature shoud be digested RSA-SHA512 signature encoded in Base64.

    This is a sample GETBALANCE Request using default ACCOUNT ID 1:


    The response is usually JSON-encoded:


    If there is an error, the server returns an error message starting with XError: for general errors or YError: if there was an error in a subtask of a bulk change order request.

    Requests must be send via TCP in the following format:


    Every request must end with <ENDOFDATA>

    Remember to use (YOUR API ID*1000)+Request ID on requests. Example: If you create your API accont on Fairlay, site will set an ID to it, usually first API ID is 1. So a request to Get Orderbook with this account will be 1001.

    Private API Calls

    Get Public Key (GETPUBLICKEY)


    Response: returns the server's public key in XML format.

    Get Server Time (2)


    Response: returns the server's time in ticks.


    Note: the server time can also be interfered from the nonce in every response.

    Get Me (21)


    Returns: User info object containing last connections, withdraw adresses, market makers, funds, API Accounts, screen name and ID.

    Get My Balance (22)


    Returns: JSON object containing account balance information:

    PrivReservedFunds: Total account funds in mBTC. PrivUsedFunds: Amount of balance placed on opened markets in mBTC. AvailableFunds: Amount of balance available to use in mBTC. SettleUsed: Amount retained due to settlement in mBTC. CreatorUsed: Amount retained by market creation in mBTC. RemainingRequests: Requests remaining before new charge.

    Set API Account to Readonly (49)


    This will permanently set your API Account #5 to Read Only. This cannot be undone.

    You can also set your API Account #0 to read only. But be careful with it:


    Get Orderbook (1)


    Response: An array containing one object with orderbooks for each runner in market.

    [{ "Bids": [ [3.954, 3.75] ], "Asks": [ [7.203, 2.06156] ], "S": 1 }, { "Bids": [ [5.627,2.63] ], "Asks": [], "S": 1}]

    This is a return from a market with 2 runners.

    Get Orderbooks (4)

    signature|nonce|userid|4|[marketID1, marketID2]
    signature|nonce|userid|4|[121046999588, 121046400020]

    Response: An array of objects containing orderbooks for each runner in market.

    [{ "Bids": [ [3.954, 3.75] ], "Asks": [ [7.203, 2.06156] ], "S": 1 }, { "Bids": [ [5.627,2.63] ], "Asks": [], "S": 1},{ "Bids": [ [3.954, 3.75] ], "Asks": [ [7.203, 2.06156] ], "S": 1 }, { "Bids": [ [5.627,2.63] ], "Asks": [], "S": 1}]

    This is a return from 2 markets with 2 runners.

    Get Market (6)


    Returns: market object

    Get Markets (7)

    "Comp":"Premier Leag",

    Returns all markets that apply to the given filter.

    Cat: is the Category, 0 queries all Categories.

    RunnerAND: All strings provided must be contained in the names of the runners of the market.

    TitleNOT: None of the strings may appear in the title of the market

    TypeOr: Only the Market Types given will be returned. If set to null, all market types will be returned. See A2) for Market Types

    PeriodOr: Similiar to TypeOr See A2) for Market Periods

    SettleOr: See A2) for Settlement Types

    ToSettle: If set to true, it will only return unsettled markets where the resolution time has passed.

    NoZombie: No empty markets (without any open order)

    Descr: The given string must appear in the market description.

    ChangedAfter: Only returns markets, where the meta data was changed after the given date. Usually the Closing and Settlement Dates of a market is the only data that changes. SoftChangedAfter: Returns all markets, where either the the meta data or the orderbook has changed since the given date.

    Returns: a list of market objects

    Get Markets Orderbook (67)

    "Comp":"Premier Leag",

    Returns: A long-string Dictionary with the marketID - orderbook key-value pair.

    Create Market (11)

    "Descr":"This market resolves to Yes, if the Senate confirms Merrick Garland’s Supreme Court nomination before President Obama leaves the office.",

    Comp: Competition CatID: Category (see A2)) ClosD: Closing Date SettlD: Resolution Date Ru: InvDelay must always be 0, VisDelay must always be set to 6000 _Type: See A2) _Period: See A2) SettlT: For settlement types see A2) Comm: 0.02 - must always be 0.02. PrivCreator: must match your userid and will remain privat CreatorName: must match your Username and is public

    Returns: Market ID (no json)

    Create Order (62)

    Note: (use requestID 61 for market making)




    Market ID: on which market the order will be placed Runner ID: on which runner the order will be placed: 0 for the 1st runner, 1 for the 2nd runner of the market and so on. BidorAsk: 0 places a bid order, against the runner. 1 places a bet on the runner to win. price: the decimal odds at which the order is placed amount: the amount in mBTC matchedsubuser: custom string type: see unmatched order types in A2) pendingperiod:s should be set to 6000ms

    Returns: unmatched order object

    Cancel Order (15)


    Returns: a list of all corresponding matched orders objects for the cancelled unmatched order.

    Cancel Market Orders (10)

    Cancel all opened orders on specific market


    Returns: how many unmatched orders were cancelled:

    2 Orders were cancelled`

    Cancel All Orders (16)


    Returns: how many unmatched orders were cancelled:

    5 Orders were cancelled

    Change Order (17)


    Is a combination of "cancel order" and "create order"

    Returns: unmatched order object

    Bulk Change Order Maker (109)

    Changes, cancels and creates many orders at once.

    signature|nonce|userid|1109|Array of Request ChangeOrder object



    Returns: an array of REQChangeOrder objects. The Res property of each object contains the status of each bet. Res is either a serialized UnmatchedOrder order object ( or contains an error message like (Res = ) "YError: Market closed" for example.

    Get New Orders (24)


    TimeinTicks: Time given in ticks, all orders after the given tick will be returned

    Returns: all unmatched orders and matched orders that were created, cancelled or changed after the given time.

    Get Unmatched Orders (25)


    TimeinTicks: Time given in ticks, all orders after the given tick will be returned

    Returns: all matched orders that were created, cancelled or changed after the given time.

    Get Matched Orders (27)


    TimeinTicks: Time given in ticks, all orders after the given tick will be returned

    Returns: all matched orders that were created, cancelled or changed after the given time.

    Transfer Founds/Withdraw (81)


    Example for transfer object:

    {"FromU":777888,"ToU":777889,"Descr":"test transfer","TType":1,"Amount":2.0}

    FromU: must match your userid ToU: must be an existing user TType: custom field, can have any int value

    Returns: transferobject if successful

    Get User Transaction (82)


    Get all user transactions since given time in ticks.

    Returns: An array of transactions. Every transaction has currency IDs in it.

    Set Market Maker (73)


    This sets up an fully automated LMSR market maker. Google the term to get familiar with the usage.

    example for lmsrmarketmakerobject:


    Default values:


    UserID: must match your userid MarketID: must be provided Runner: # of Runners / must match the # of runners of the market Enabled: must be set to true InitShareLimit (must be > 1): Shares that are offered in one order. Stake + Winnings from one order are 350mBTC B (must be > 10): ~ is about the same as the maxium possible loss of the market maker CancelAll (must be set to a future date): Date where the market maker stops. Set to year 2100 if the mm should run forever ShareStop (must be > 1): amount of exposure in shares before the market maker stops. Should be set higher than B in regular cases. InitProb: the initial probability estimation for all runners DiminishBack (must be non-negative): In general the LMSR market maker runs on 0% margin, i.e. it doesn't make any profit. If more margin should be added, you can worsen the odds for each bid orders for every runner. 0.01 worsens bid odds from 80% to 81% (or 1.25 to 1.2345) for example. DiminishLay: same for all ask orders.

    *Cool off adds temporary additional margin to markets with increased activity and should be applied to markets that can have exogenous shocks or where real probabilities can deviate from the initial probability distribution. *

    coolOffFactor (must be >=1): if set to 4.0 the odds will worsen 4.0 times more than expected from the usual lmsr market maker. coolOffSeconds (must be >=1): The time after which the coolOff period will be over. If set to 36000 the additional market margin will reduce step by step over an period of 10 hours.

    If no cool off is required, set coolOffSeconds to 1.

    Disable a MM by setting Enabled = false and other variables to a valid value.

    Get Marker Maker (70)

    Gets the current LMSR MM from the user for a given market.


    example for lmsrmarketmakerobject:

    shell{"UserID":777888,"MarketID":61659266392,"Runner":5,"Enabled":true,"InitShareLimit":350.0,"B":1300.0,"CancelAll":"2016-06-05T13:34:56", "ShareStop":1400.0,"InitProb":[0.3,0.1,0.2,0.2,0.2],"DiminishBack":[0.01,0.01,0.01,0.0,0.02],"DiminishLay":[0.0,0.0,0.0,0.01,0.01],"coolOffSeconds":36000.0,"coolOffFactor":4.0}

    Change Market Closing Time (84)

    Changes Closing and Settlement Date




    Returns: MarketTime changed.

    Get Settlements (85)

    Gets all bankroll adjustments after a given time.


    Returns: A JSON encoded Statement Object:

    long ID: is not unique globally; is the time in milliseconds from Jan 1th 2016 Descr: optional description, contains the market ID in case of a settlement. T: 0-99 stands for a transfer (same like ttype in transfer object) includes deposits & cashouts, 100 admin, 200 market settlement w/o commission, 201 market settlement with commission, 250 unsettlement, 300 commission bonus) Am: amount credited Bank: total bankroll after the adjustment.

    Settle Market (86)

    Settles a given market. Note that the total betting volume of the market will be deducted from the available balance for 2 to 3 days. Unless the user has special rights, a user can only settle markets he created.




    Mid: is the market ID Runner: determines the Runner which won (0 means that the 1st Runner won, 1 means that the 2nd Runner won and so on). If a market shall be voided the Runner must be set to -1 Win: Must be set to 1 Half: should be set to "false". Only needed for +- 0.25 and +-0.75 soccer spread and over/under markets. If a market is half won or half lost, set Half to "true"; Dec: If the market is not binary, but has a decimal outcome, this needs to be set to the result. [Not supported yet] ORed: Odds reduction [only for Horse racing - not needed in general]

    Returns: "Market settled" or some kind of "XError: ..."

    Data Types

    Market Category

    The main categories for diverse market options, use their IDs to filter market by category:

            1: 'Soccer',
            2: 'Tenis',
            3: 'Golf',
            4: 'Cricket',
            5: 'RugbyUnion',
            6: 'Boxing',
            7: 'Horse Racing',
            8: 'Motorsport',
            10: 'Special',
            11: 'Rugby League',
            12: 'Bascketball',
            13: 'American Football',
            14: 'Baseball',
            15: 'Politics',
            16: 'Financial',
            17: 'Greyhound',
            18: 'Volleyball',
            19: 'Handball',
            20: 'Darts',
            21: 'Bandy',
            22: 'Winter Sports',
            24: 'Bowls',
            25: 'Pool',
            26: 'Snooker',
            27: 'Table tennis',
            28: 'Chess',
            30: 'Hockey',
            31: 'Fun',
            32: 'eSports',
            33: 'Inplay',
            34: 'reserved4',
            35: 'Mixed Martial Arts',
            36: 'reserved6',
            37: 'reserved',
            38: 'Cycling',
            39: 'reserved9',
            40: 'Bitcoin',
            42: 'Badminton'

    Market Type

    Different types of market rules settlement:

        MARKET_TYPE = {
            0: 'MONEYLINE',
            1: 'OVER_UNDER',
            2: 'OUTRIGHT',
            3: 'GAMESPREAD',
            4: 'SETSPREAD',
            5: 'CORRECT_SCORE',
            6: 'FUTURE',
            7: 'BASICPREDICTION',
            8: 'RESERVED2',
            9: 'RESERVED3',
            10: 'RESERVED4',
            11: 'RESERVED5',
            12: 'RESERVED6'

    Market Periods

    Mostly used by sports markets, define if the market is related to a specific fraction of the match:

        MARKET_PERIOD = {
            0: 'UNDEFINED',
            1: 'FT',
            2: 'FIRST_SET',
            3: 'SECOND_SET',
            4: 'THIRD_SET',
            5: 'FOURTH_SET',
            6: 'FIFTH_SET',
            7: 'FIRST_HALF',
            8: 'SECOND_HALF',
            9: 'FIRST_QUARTER',
            10: 'SECOND_QUARTER',
            11: 'THIRD_QUARTER',
            12: 'FOURTH_QUARTER',
            13: 'FIRST_PERIOD',
            14: 'SECOND_PERIOD',
            15: 'THIRD_PERIOD',

    Market Settlements

    Different types of markets settlement:

            0: 'BINARY',
            1: 'CFD',
            2: 'CFDI',
            3: 'EXCHANGE'

    Matched order state

    States of an order could have during its lifetime:

            0: 'MATCHED',
            1: 'RUNNER_WON',
            2: 'RUNNER_HALFWON',
            3: 'RUNNER_LOST',
            4: 'RUNNER_HALFLOST',
            5: 'MAKERVOIDED',
            6: 'VOIDED',
            7: 'PENDING',
            8: 'DECIMAL_RESULT'

    Unmatched order state

    States of unmatched order could have during its lifetime:

            0: 'ACTIVE',
            1: 'CANCELLED',
            2: 'MATCHED',

    Order type

    Different types of order that is created: - MAKERTAKER : If not matched instantly, will remain in the orderbook. - MAKER : Will be placed at orderbook waiting for a match. - TAKER : If not fully matched instantly, the amount unmatched will be voided automatically.

        ORDER_TYPE = {
            0: 'MAKERTAKER',
            1: 'MAKER',
            2: 'TAKER'

    Public API Introduction

    This is a free service to scrape all markets on Fairlay. For all POST requests (creating/changing markets and orders) use the paid Private API.

    For more examples how this API should be used together with our paid API, please take a look at our sample clients in C# and Python.

    Please feel free to comment and make suggestions.

    Public API Calls

    Free Servers

    used by default for all Public API calls

    (is an alternate server with the same functionality, also used for all Private API calls)


    For examples on how to use each of the API calls presented here, see the C# Unit Tests.

    In all of the examples below you can call /free/(method) calls with /free0/ up to /free9/ to increase the given limits above, a simple way is to either rotate from 1 to 9 or just randomize the free call from 1 to 9.

    Server Time

    Returns the server time in ticks.

    Note: You can do the same in the Private API via getservertime


    Returns JSON encoded list of markets that apply to the given filter.

    MARKETFILTER object looks like this:

            "Comp":"Premier League",

    Cat: Category, see A2) for more information. 0 queries all Categories. TitleAND: List of strings which all must appear in the title of the market. RunnerAND: List of strings which all must be contained in at least one name of one runner of the market. TitleNOT: List of strings which none may appear in the title of the market. Comp: Competition name. null to get all competitions. **TypeOr8: Market Types, see A2) for more information. Only the Market Types given will be returned. If set to null, all market types will be returned. PeriodOr: Market Period, see A2) for more information. SettleOr: Settlement Type, see A2) for more information. NoZombie: If True, no empty markets will be returned (without any open order). Descr: The given string must appear in the market description. ••ChangedAfter••: Return markets where the meta data was changed after the given date. Usually the Closing and Settlement Dates of a market is the only data that changes. SoftChangedAfter: Return all markets, where either the the meta data or the orderbook has changed since the given date. FromClosT: Return markets where the closing time is greater than the given one. FromID and ToID: Use for paging requests. ToID has a default value of 300 if not set.


    Returns the first 100 non-empty soccer markets, where one of the runners is Portugal, the Title does not contain the words "Corners" or "Throwin" and the period of the match is full-time.{"Cat":1,"NoZombie":true,"RunnerAND":["Portugal"], "TitleNOT":["Corners","Throwin"], "PeriodOR":[1],"FromID":0,"ToID":100}

    Returns all active tennis matches of the type Over/Under or Outright where the odds or market data have changed after June 1st 12:01:30pm.{"Cat":2,"TypeOr":[1,2],"SoftChangedAfter":"2016-06-01T12:01:30","OnlyActive":true,"ToID":10000}

    Returns all active non-empty markets.{"OnlyActive":true,"NoZombie":true,"ToID":100000}


    Returns all competitions in the selected category.

    Example for all soccer competitions:

    API Libraries & Source Code