betfaiR

betfair is the primary function in the betfaiR package. It takes three arguments, your Betfair username, your password and your API key, if entered correctly then the function will return an environment with the various Betfair API methods.

usage

bf <- betfair(usr = username,
              pwd = password,
              key = api_key,
              jurisdiction = "default")

arguments

param	details
`usr`	Betfair username
`pwd`	Betfair password
`key`	Betfair API key (see Betfair documentation on how to get an API key)
`jurisdiction`	Sign into different jurisdictions, the default logs into .com, enter ‘italy’ for the Italian exchange, ‘spain’ for the Spanish and ‘romania’ for the Romanian

Usernames, passwords and API Keys SHOULD NOT be shared, there is the danger in R that you inadvertently save these either by saving your workspace on exiting or in your .Rhistory. The httr package (on which this package relies) has a very good appendix in one of its vignettes on ways to keep data like this more secure, you can read the vignette here, but the relevant section is repeated in the appendix at the bottom of this page.

return

The function returns an environment (stored as bf in the usage section) with various methods for retrieving exchange data. To view the available methods you can print the environment:

bf

<betfaiR API>
Methods available: 
    $account(pwd) 
    $cancelOrders(..., marketId = NA) 
    $clearedOrders(betStatus = "SETTLED", eventTypeIds = NULL, eventIds = NULL, marketIds = NULL, runnerIds = NULL, 
   betIds = NULL, side = "BACK", from = NULL, to = NULL) 
    $competitions(filter = marketFilter()) 
    $countries(filter = marketFilter()) 
    $currentOrders(betId = NULL, marketId = NULL, orderProjection = "ALL", from = NULL, to = NULL, orderBy = "BY_BET", 
   sort = "EARLIEST_TO_LATEST", fromRecord = NULL, count = NULL) 
    $events(filter = marketFilter()) 
    $eventTypes(filter = marketFilter()) 
    $login(usr, pwd, key, jurisdiction = "default") 
    $marketBook(marketIds = list(), priceProjection = "EX_BEST_OFFERS", orderProjection = "EXECUTABLE", matchProjection = "NO_ROLLUP", 
   getRunners = NULL) 
    $marketCatalogue(filter = marketFilter(), marketProjection = "EVENT", sort = NULL, maxResults = 1, keepRules = FALSE) 
    $marketPnL(marketIds, settled = NULL, bsp = NULL, NET = NULL) 
    $marketTypes(filter = marketFilter()) 
    $placeOrders(marketId, selectionId, orderType = "LIMIT", handicap = NULL, side = "BACK", order = limitOrder()) 
    $replaceOrders(..., marketId) 
    $session() 
    $updateOrders(..., marketId) 
    $venues(filter = marketFilter())

method	details	available	help
`account`	Return environment with methods for retrieving data about your account	`TRUE`	bf_account
`cancelOrders`	Cancel existing orders that may be unmatched or partially matched	`TRUE`	cancelOrders
`clearedOrders`	Retrieve data about cleared orders	`TRUE`	clearedOrders
`competitions`	Retrieve data about the different competitions with current markets	`TRUE`	competitions
`countries`	Retrieve data about the different countries hosting events	`TRUE`	countries
`currentOrders`	Retrieve data about current orders	`TRUE`	currentOrders
`events`	Retrieve data about the different events	`TRUE`	events
`eventTypes`	Retrieve data about the different event types, ie. sports	`TRUE`	eventTypes
`login`	Login in, a session token will be returned, over-writing the previous token when betfair(usr, pwd, key) was used	`TRUE`	login
`marketBook`	Retrieve dynamic data about markets. Data includes prices, the status of the market, the status of the selections, the traded volume, and the status of any orders you have in the market	`TRUE`	marketBook
`marketCatalogue`	Retrieve data about the different types of markets	`TRUE`	marketCatalogue
`marketPnL`	Retrieve current profit and loss for markets	`TRUE`	marketPnL
`marketTypes`	Retrieve counts for the different market types	`TRUE`	marketTypes
`placeOrders`	Place a bet. This likely needs work, so please proceed cautiously, and if possible provide feedback	`TRUE`	placeOrder
`replaceOrders`	Replace existing orders with new instructions	`TRUE`	replaceOrders
`session`	Prints session token	`TRUE`	session
`updateOrders`	Update existing orders with new instructions	`TRUE`	updateOrders
`venues`	Retrieve data about the venues hosting racing (horse and greyhound)	`TRUE`	venues

appendix

username, password and API key best practices

The betfaiR package requires a valid Betfair username, password, and API key - see the Betfair documentation on how to get an API key. The steps below show how to securely store your credentials as environment variables, preventing them from being shared inadvertently via .Rhistory or .RData files.

Identify your home directory. Not sure? Enter normalizePath("~/") in the R console.
Create a new text file. If in RStudio, do File > New File > Text file

Create the following lines:

BETFAIR_USR=yourusername
BETFAIR_PWD=yourpassword
BETFAIR_KEY=yourAPIkey

Make sure the last line in the file is empty (if it isn’t R will silently fail to load the file). If you’re using an editor that shows line numbers there should be four lines, 3 containing the three variables above, and a fourth empty one.
Save the file in your home directory with the filename .Renviron. If questioned, YES you do want to use a filename that begins with a dot .. Note that by default dotfiles are usually hidden. But within RStudio, the file browser will make .Renviron visible and therefore easy to edit in the future.
Restart R. .Renviron is processed only at the start of an R session.
Use Sys.getenv() to access your username, password, and API key. For example you would use them like so with the betfair function:

# load library
library(betfaiR)
# login
bf <- betfair(usr = Sys.getenv("BETFAIR_USR"),
              pwd = Sys.getenv("BETFAIR_PWD"),
              key = Sys.getenv("BETFAIR_KEY"))

Warning in bf_login(usr = usr, pwd = pwd, key = key, jurisdiction =
jurisdiction): Login failed: INPUT_VALIDATION_ERROR

bf

<betfaiR API>
Methods available: 
    $account(pwd) 
    $cancelOrders(..., marketId = NA) 
    $clearedOrders(betStatus = "SETTLED", eventTypeIds = NULL, eventIds = NULL, marketIds = NULL, runnerIds = NULL, 
   betIds = NULL, side = "BACK", from = NULL, to = NULL) 
    $competitions(filter = marketFilter()) 
    $countries(filter = marketFilter()) 
    $currentOrders(betId = NULL, marketId = NULL, orderProjection = "ALL", from = NULL, to = NULL, orderBy = "BY_BET", 
   sort = "EARLIEST_TO_LATEST", fromRecord = NULL, count = NULL) 
    $events(filter = marketFilter()) 
    $eventTypes(filter = marketFilter()) 
    $login(usr, pwd, key, jurisdiction = "default") 
    $marketBook(marketIds = list(), priceProjection = "EX_BEST_OFFERS", orderProjection = "EXECUTABLE", matchProjection = "NO_ROLLUP", 
   getRunners = NULL) 
    $marketCatalogue(filter = marketFilter(), marketProjection = "EVENT", sort = NULL, maxResults = 1, keepRules = FALSE) 
    $marketPnL(marketIds, settled = NULL, bsp = NULL, NET = NULL) 
    $marketTypes(filter = marketFilter()) 
    $placeOrders(marketId, selectionId, orderType = "LIMIT", handicap = NULL, side = "BACK", order = limitOrder()) 
    $replaceOrders(..., marketId) 
    $session() 
    $updateOrders(..., marketId) 
    $venues(filter = marketFilter())

FAQ: Why define this environment variable via .Renviron instead of in .bash_profile or .bashrc?

Because there are many combinations of OS and ways of running R where the .Renviron approach just works and the bash stuff does not. When R is a child process of, say, Emacs or RStudio, you can’t always count on environment variables being passed to R. Put them in an R-specific start-up file and save yourself some grief.