API Reference
Enable the API
To enable the API, copy and paste these lines into the bitmessagesettings section of the keys.dat file:
apienabled = true apiport = 8442 apiinterface = 127.0.0.1 apiusername = bradley apipassword = yourSuperWonderfulPassword98a8#5223345
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
apinotifypath = c:\\example\\example.exe
One of these arguments will be passed to your program: startingUp, newMessage, newBroadcast. Be sure your program doesn't crash when given newer arguments introduced in the future as this list will likely expand.
List of Operations
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
| Command | Parameters | Description |
|---|---|---|
| helloWorld | <firstWord> <secondWord> | returns 'firstWord-secondWord'. Used as a simple test of the API. |
| add | <integer> <integer> | returns the sum of the integers. Used as a simple test of the API. |
| statusBar | <message> | Displays the message in the status bar on the GUI |
| listAddresses | Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
| |
| createRandomAddress | <label> [eighteenByteRipe] | Creates one address using the random number generator. eighteenByteRipe is a boolean telling Bitmessage whether to generate an address with an 18 byte RIPE hash(as opposed to a 19 byte hash). This is the same setting as the "Do extra work to make the address 1 or 2 characters shorter" in the user interface. Using False is recommended if you are running some sort of website and will be generating a lot of addresses. Note that even if you don't ask for it, there is still a 1 in 256 chance that you will get an address with an 18 byte RIPE hash so if you actually need an address with a 19 byte RIPE hash for some reason, you will need to check for it. eighteenByteRipe defaults to False.
Returns the address. |
| createDeterministicAddresses | <passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] | Similar to createRandomAddress except that you may generate many addresses in one go. numberOfAddresses defaults to 1. addressVersionNumber and streamNumber may be set to 0 which will tell Bitmessage to use the most up-to-date addressVersionNumber and the most available streamNumber. Using zero for each of these fields is recommended. eighteenByteRipe defaults to False.
Returns a list of new addresses. This list will be empty if the addresses already existed. |
getAllInboxMessages |
Does not include trashed messages. Returns a list of objects with these properties:
The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it is shown in hex as that is the de facto standard. The encodingType property is currently always set to 2 because, unfortunately, the inbox table in Bitmessage does not record the encoding type. In the future Bitmessage will record it and at that time this field will be accurate therefore the field is included here to maintain forwards compatibility. | |
| trashMessage | <msgid> | returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked. msgid is encoded in hex just like in the getAllInboxMessages function. |
| sendMessage | <toAddress> <fromAddress> <subject> <message> [encodingType] | returns ackdata encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility. |
| sendBroadcast | <fromAddress> <subject> <message> [encodingType] | returns ackdata encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility. |
