Betfair Bot SDK guidance for a beginner
Posted in Bfexplorer Labs by StefanBelo Tags: BOT
Before reading this article you should watch following video tutorials:
And read this article to learn what you can develop using Bfexplorer BOT SDK: Bfexplorer BOT SDK and what betfair bots you can program in C# or Visual Basic
My preferred programming language is C# so my bot examples are in C#, but you can use any .NET programming language for your betfair bot development. Visual Studio directly supports C++, C#, F# and Visual Basic, and support for other languages such as M, Python, and Ruby among others is available via language services installed separately. I assume that readers of this article have at least base understanding of OOP.
To understand what you can do and how by using Bfexplorer BOT SDK, you must first understand what it is a betfair bot in Bfexplorer PRO2 context. Most betfairians would say that bfexplorer is a bot. Well that is not quite the truth.
If you want to build your betting or trading strategy from scratch then first you must learn how to use betfair api and build your own interface for interaction with it. Create some kind of market monitoring system, because you would like to monitor more markets, not just one. Create a base user interface for showing market data, bets, and so.
Using Bfexplorer BOT SDK to develop your betfair bot you implement just bot logic. Bfexplorer BOT SDK allows to develop two types of bots: IBot and ILookUpBot. The first one, IBot is able to run on a market. The second one, ILookUpBot is used by tool: Trade opportunity lookup. The bot interfaces say more.
public interface ILookUpBot
{
string Name { get; set; }
bool DoYourJob(MonitoredMarket monitoredMarket);
}
public interface IBot
{
DateTime LastTimeExecuted { get; }
MonitoredMarket MonitoredMarket { get; }
string Name { get; set; }
void DoMyBetsUpdate(MonitoredMarketStatus monitoredMarketStatus,
BetTaskType betTaskType, long betOperationId);
bool DoYourJob();
}
The above interfaces are implemented by set of classes from which should be derived your own bot classes. In the BOT SDK you can find following bot classes: Bot, MarketBot, RunnerBot, MyMarketBot, MyRunnerBot and LookUpBot. The Bot class implements:
public abstract class Bot : IBot
{
protected const int MaxTimeToMatchBetInSeconds = 15;
protected const int MaxTimeToPlaceBetInSeconds = 60;
protected IBetfairService betfairService;
protected BetStakeCalculation betStakeCalculation;
protected bool betStateConfirmed;
protected bool? haveMatchedBets;
protected bool? haveUnmatchedBets;
protected DateTime? lastTimeBetOperation;
protected DateTime lastTimeExecuted;
protected MonitoredMarket monitoredMarket;
protected bool stopLossActive;
protected TradingState tradingState;
protected bool updatingActive;
public Bot(IBetfairService betfairService, MonitoredMarket monitoredMarket);
public BetPrice BackBetPrice { get; }
public DateTime LastTimeExecuted { get; }
public BetPrice LayBetPrice { get; }
public MonitoredMarket MonitoredMarket { get; }
public string Name { get; set; }
public abstract bool DoYourJob();
public virtual void DoMyBetsUpdate(MonitoredMarketStatus monitoredMarketStatus,
BetTaskType betTaskType, long betOperationId);
protected bool CancelAll();
protected void CancelBets(List betsToCancel);
protected void CancelBetsAndPlaceBet(Runner runner,
BetType type, double odds, double stake, bool atInPlayKeepBet = false);
protected void PlaceBet(Runner runner,
BetType type, double odds, double stake, bool atInPlayKeepBet = false);
protected void PlaceBets(IList bets, bool atInPlayKeepBet = false);
protected void UpdateBet(UpdateBet betToUpdate);
protected void UpdateBets(List betsToUpdate);
protected virtual bool ConfirmBotState(BetTaskType betTaskType, long betOperationId);
protected virtual void DoMyBetsUpdateUnmatched();
protected abstract void DoSetBetPosition();
protected abstract long GetBetOperationId();
protected abstract bool GetHaveMatchedBets();
protected abstract bool GetHaveUnmatchedBets();
protected bool GetIsSafeToOperate();
protected abstract List GetUnmatchedBets();
protected void CheckBotStatus();
protected void SetUnknownBetState();
protected void ShowMessage(string message);
}
You can use Object Browser and browse publicly available classes for BeloSoft.BetfairService assembly in the namespace: BeloSoft.Betfair.Trading to see what other bot classes are implemented.
In the BOT SDK project you can see source code for more bots, have a look at for instance the class: PlaceBetForRequiredProfitBot to understand how you should implement your bot when you want to place a bet and manage it till the bet is fully matched.
In this project you can see how you can build a bot assembly that can be loaded by Bot Executor, and simple bot scripts, have a look at namespace: Bfexplorer.Scripting
Here you can see what is difference between RunnerBot or MyRunnerBot, and MarketBot and MyMarketBot. Simply said when you need to write some very simple bots that you do not want to add to the bot assembly list then use MyRunnerBot or MyMarketBot.
Have a look on this screenshot to understand what I mean by bot assembly:
The project bots from the namespace: BeloSoft.BfexplorerCommunityBotExecutor.Trading are listed in the Bot Criteria Editor, have a look on the interface IBotExecutor, to learn how it is done.
If you want to build your betting or trading strategy with an user interface (Bfexplorer PRO plugin) then you have to implement IBfexplorerPlugin or IBfexplorerPlugin2 interface for your UI.
On the screenshot below (click on it to zoom it), you can see the source code for football betting strategy, on the right side of the screenshot there is Bfexplorer PRO2 running this betting strategy, so you can see how your UI could look like.
In the source code you can see that I build Bet365DataProviderService, to get live data (match score and time, and market odds) from bet365 website.
The betting solution uses MyFootballSolutionTradeOpportunityLookupService to browse football match odds markets from betfair.
To execute this betting strategy I created MyBotLookUp to start bet placing at preset critria, this LookUpBot is executed by MyFootballSolutionTradeOpportunityLookupService. Because the betting strategy required decision making depending on current match score and odds offered by bet365 I created another action bot (MarketBot) MyBotStarterMarketBot, and finally the bot for bet placing: (RunnerBot) PlaceLayBetsBot.
Tuesday, August 02, 2011
API Documentation
Hi Stefan
It's been a frustrating experience trying to use the SDK to implement my own bots without any API documentation in the form of documented classes, methods, properties, fields, parameters, etc. For example I had to figure out myself that the return value of the DoYouWork() method determines if the bot should be stopped or not. It seems obvious when you know this, but without knowing this simple fact, I had to write code just to try test and see what difference it made. That's how I figured it out. A simple line of documentation would have saved me maybe half an hour.
I had to write my own test bots to dump various properties, fields etc to a log file just so I could figure out what they actually mean and do. And many of them I'm still not clear on. What is an AsianLineId? Does it relate to Asian Handicaps? I could find no explanation. Simple comments embedded into the classes themselves would have saved me many hours. There are still many classes, methods and properties who's purpose I'm not clear on. What does GetIsSafeToOperate() do exactly?
What exactly does CheckBotStatus() do? And that's just the Bot class itself. Many of the other classes are still a mystery to me. Simple one line comments for each of these methods would make my life so much easier and take all the guesswork out of trying to implement a bot (and also save me a huge amount of time).
The tutorials and forum posts are extremely valuable but should definitely be supplemented by embedded API documentation using /// comments in the code.
I'm writing this email to urge you to please include embedded documentation in all the public classes. If by some remote chance you're not familiar with the documentation-related tools available, this is useful:
http://stackoverflow.com/questions/641364/c-documentation-generator
Much appreciated!
Regards Aharon
Tuesday, August 02, 2011
I would really appreciate if you post any general questions to bfexplorer forum or comment any appropriate article. My answer could help not only you, but other betfair software developers who would use Bfexplorer BOT SDK in a future.
Yes, I am familiar with documentation systems which are able to generate documentation from a source code, but in this case it would be useless just have look at on my source code. (zoom it)
I am used to comment classes, structures, interfaces, methods and properties but I do not use any description to my code. I use it just to separate code structure, to make it more readable. My first language is not English, but even so I think that my naming convention used in my code is quite descriptive. I released Bfexplorer BOT SDK the source code including BfexplorerCommunityBot assembly. This solution contains 28 bot classes showing simple scenarios and use of most classes you could use in your own bot classes.
I thought that any software developer should be skilled enough to manage how to operate bfexplorer application. I mean how to use Bfexplorer PRO not how to program bots. So first, as any bfexplorer user does is to login to betfair with bfexplorer, open market/s for monitoring, try to place, update, cancel bets. Setup a first bot using Bot Executor and Bot Criteria Editor, then start a bot and see what bot does on a market. Stop running bot and so on.
I believe that any software developer who runs a program/software/an application, first goes through the application menu, that gives overall understanding of what the application can do. I do not think I have to explain you what it is a toolbar or a context menu. This first impression can be done in couple minutes up to 1 hour, I really believe that 1 hour is enough to familiarize yourself with bfexplorer without reading any manual. If not that you can start reading web manual, and forum.
If you did so, then I believe you discovered tools Trade opportunity lookup and Execute my strategies on selections, and you wondered maybe how to use bot you have just configured by filling bot parameters in the Bot Criteria Editor. You may opened some Bfexplorer PRO plug-in clicking on Tools / My Bfexplorer Extensions, and as you are software developer you may ask yourself, can I program such bfexplorer plugin? Yes, you can program it.
Now, you are familiar with Bfexplorer PRO and you want to start coding/programming your own betfair bot. What I assumed was that any software developer would open BOT SDK solution and have a look at on the source code. As I already mention the BOT SDK solution contains 28 bot classes in 2 projects, and even more classes because the project BfexplorerCommunityBotExecutor implements bot assembly (bot plugin).
How many minutes did you spend just by browsing BOT SDK source code? Well, it is not important because any software developer press F5 to start debugging the code. At that moment the first problem could occur if your windows operating system is not 64 bit OS, you will have to change path to bfexplorer assemblies in both projects references.
If I were you I would start debugging the bot code for betfair bot: MyBots.HelloBetfairBot.
You may ask why? Well, it is the simplest bot, right? 14 lines of code (Most of the code is just class declaration, actually bot itself executes just one line of code: ShowMessage("Hello Betfair")) and you know how to run it from the Bot Executor because you already watched my video: How to program betfair bots
I believe you would understand why DoYourJob method returns false, when bot displayed Hello Betfair in the Output window. The answer is simple. Because DoYourJob is executed somewhere from bfexplorer, and DoYourJob returns bool-ean value to a caller method it must be some way of communication True/False to let a caller method know that a bot must be execute again. You could change the line: return false; to return true; to find out that in such case bot does not stop. You can stop it only by click on toolbar button Stop Bot.
If I may suggest you, use the tool: Debug my bot when debugging a bot source code, and debug in the training mode only.
The AsianLineId is implementation detail for betfair api and in the latest version of Bfexplorer PRO I removed this property.
GetIsSafeToOperate function checks if the market is Active state. It does not make any sense to start placing bets when the market is suspended. On the other hand in bot code where you do not want to place any bet, your bot can operate on a market even if the market is suspended, please have a look at on the bot source code: EventNotificationBot (you can find it in the namespace: BeloSoft.BfexplorerCommunityBotExecutor.Trading)
CheckBotStatus method, as the name could suggest, checks the bot status when bot started bet operation: placing or cancelling bets. As you already know betfair api is asynchronous, so bot just gives instruction to place, update, or cancel a bet, and bfexplorer bet service updates bot bet status by calling the method: DoMyBetsUpdate when the bet operation is done.
Your bot knows about its current state through variable tradingState, so if your bot just placed a back bet, the state of this variable is: TradingState.BackingInProgress, and when the back bet is fully matched the variable state is changed to: TradingState.BackingBetDone.
This way your bot knows about the bet placing status when the bot is executed, and can react as you want. Please have a lookat on the bot source code: PlaceBetTillTimeBot.
Well I really do not know why you did this one: "I had to write my own test bots to dump various properties, fields etc to a log file just so I could figure out what they actually mean and do."
In the Visual Studio (VS) you have got the tool: Object Browser. If you open BOT SDK solution in VS and set the Browse to My Solution, then the Object Browser will show you all referenced assemblies and there you can browse all publicly available classes, structures, interfaces, enums and delegates. Just browse namespaces: BeloSoft.Betfair.Data.Betting, BeloSoft.Betfair.Trading and many others to get you an idea what is already done and what you can use.
The correct use of all those classes you can find in these 28 bot classes. If you are not sure, what to use and how, please write your post on forum including a code snippet if you like.
You can get familiar with Bfexplorer BOT SDK only by writing a bot code. If you have no inspiration on simple bots, you can read forum, people ask for simple bot scripts.
Tuesday, August 02, 2011
A few questions
Hi Stefan
I've read through most of the forum posts but I still have a few unanswered questions while trying to implement a bot to run on Bfexplorer:
1) When and how frequently does the DoYourWork() method get called on a bot? What events/situations will cause that method to get called by Bfexplorer?
2) I presume that I need to maintain the bot's state internally so that each time DoYourWork() gets called, the bot will do the suitable action. Is this correct?
3) How do I ensure that my bot will run some specific logic (e.g. place an initial bet) at exactly 1 minute before a game starts, even if I start the bot hours earlier?
4) How can I accurately track where the game is up to (e.g. first half, second half, overtime, etc) and also determine exactly how many minutes remain at each point in the game? Does the live streaming service provide this data? Is it event driven or do I have to continuously poll the service for this data?
5) It seems that every time I make a change to my code, I need to restart Bfexplorer as it somehow caches the bot so my changes don't show until I restart the program. Is this correct?
6) I notice that the total number of chargeable calls as reported by the program is non-zero and increases every few seconds. Yet I've set the refresh rate to 5 seconds and also there are no charges indicated on my Betfair account statement. So I'm confused as to why Bfexplorer says there are charges when there don't seem to be any charges.
7) Is there a way to ensure/guarantee that I won't exceed the free 20 requests per second limit or is it just guesswork without any guarantees? These charges can very quickly add up so I need to be sure that the program will not exceed the free 20-requests-per-minute limit.
Thanks Aharon
Tuesday, August 02, 2011
1) When you start a bot, the bot instance is created and the bot is immediately executed. Because betfair bot operates on a market or a market selection, interacting with current price offer, therefore any bot is executed only when monitored market prices are changed, it includes market status changes as well.
It does not make any sense to execute a bot on market prices data which were not changed from the moment the bot was last time executed.
As you know you can set market refresh time for active and passive markets. Bfexplorer is able to monitor market prices for many markets simultaneously, therefore 1 market is active (the one presented in the market grid view) and the rest of markets is passive.
If you leave default setting for the refresh rate, then active market is refreshed each 1 second and the passive one each 5 seconds. So your bot on the active market is executed every 1 second, and on passive markets every 5 seconds, if market prices change.
If there are no market price changes then bot is executed every 60 seconds.
2) The bot already manages its state for you, have a look at on the variable: tradingState. If you need to maintain your bot's specific state then your bot must implement such state operation.
For instance in my trading bots I used to create BotStatus enum defining bot status: OpenPosition, ClosePosition, JobDone. So such trading bot knows if the job is done, or bot should place its opening bet.
The tradingState maintains bet status: WaitingForTrade, BackingInProgress, BackingBetDone, LayingInProgress, LayingBetDone, CancelingAllUnmatchedBetsInProgress
3) Read what I said in point 2) and have a look at on the betfair bot source code: PlaceBetTillTimeBot, if you want to manage the bet placing time by your bot.
You maybe know that there are two tools for automated betting or trading in Bfexplorer PRO:
Trade opportunity lookup (TOL)
Execute my strategy on selections
So if you use one of these tools for bet placing, then you can set the parameter: Start monitoring, to a time at which you want to place your bet. TOL will start market monitoring at this time, and bot is executed as well. In such case your bot does not have to manage a time, just place a bet.
But of course there are many other scenarios, for instance you would like to start market monitoring 30 minutes before event start, and at the same time you want to execute your bot, so your bot will be able to gather some market data, and later for instance 10 minutes before official event start time, the bot will process market data and decide to place a bet, at a preset time. In such case the bot must work with a time parameter/s.
As I said, have a look at on the bot source code PlaceBetTillTimeBot. This bot manages two times parameters. Have a look at on bfexplorer bots as well, all these bots use different time parameters.
4) If you are talking about football (soccer) match, then have a look at on the betfair bot source code: FootballBotExecutorLookUpBot. By the way, this source code shows how to write a LookUpBot, this bot type is primary used by TOL.
5) It depends on how you execute your bot code. If it is executed as a bot script, so the bot source code is compiled by bfexplorer then yes, you must restart bfexplorer. If you run a bot from bot assembly and debug your bot code in Visual Studio (VS), then you can make source code changes, well of course only when VS allows to do so. On 64 bit OS this VS feature is not supported, only if all assemblies are compiled as 32 bit assemblies.
6) That is only naming convention. In the latest version of Bfexplorer PRO I removed chargeable text from the tooltip window. What I wanted to say by that text was that only chargeable calls are counted.
7) You must set the refresh rate wisely. You know how many markets you want to monitor simultaneously, and on which markets you will place bets, because bfexplorer monitors bet status as well, and those are chargeable calls too.