API Reference

From Bitmessage Wiki
Jump to: navigation, search

Introduction

The PyBitmessage API uses XML-RPC.

Enable the API

To enable the API, copy and paste these lines into the bitmessagesettings section of the keys.dat file. Note that the values "username" and "password" below are merely examples, and should be replaced by values that cannot feasibly be guessed:

apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username 
apipassword = password

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.

Remote Access

To access the Bitmessage API from a remote location, change the apiinterface value from 127.0.0.1 to 0.0.0.0.

The following Python code offers a demonstration of how to create a client that can connect to the PyBitmessage API.

In this example, the username is "username", the password is "password", the IP address of the server running PyBitmessage is 105.168.1.0 (a random example), and the port number which PyBitmessage has been configured to listen on is 8442. In order to connect with the remote copy of PyBitmessage, these settings must match those in PyBitmessage's "keys.dat" file.

import xmlrpclib
import json
import time

api = xmlrpclib.ServerProxy("http://username:password@105.168.1.0:8442/")
print api.add(2,3)

A more complete example can be found in the api_client.py file in the PyBitmessage source code.

List of Operations

Required arguments are denoted inside < and > Optional arguments are inside [ and ].

Command Parameters Minimum Version Description
helloWorld <firstWord> <secondWord> 0.2.7 returns 'firstWord-secondWord'. Used as a simple test of the API.
add <integer> <integer> 0.2.7 returns the sum of the integers. Used as a simple test of the API.
statusBar <message> 0.2.7 Displays the message in the status bar on the GUI
listAddresses2 0.4.0 Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
  • label (base64, decodes into utf-8)
  • address (ascii/utf-8)
  • stream (integer)
  • enabled (bool)
  • chan (bool)

This is called listAddresses2 because 'listAddresses' is obsolete.

createRandomAddress <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] 0.2.7 Creates one address using the random number generator. label should be base64 encoded. 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. totalDifficulty and smallMessageDifficulty default to 1.

Returns the address.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make an address at the same time.

createDeterministicAddresses <passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] 0.3.4 Similar to createRandomAddress except that you may generate many addresses in one go. passphrase should be base64 encoded. 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. totalDifficulty and smallMessageDifficulty default to 1.

Returns a list of new addresses. This list will be empty if the addresses already existed.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make addresses at the same time.

getDeterministicAddress <passphrase> <addressVersionNumber> <streamNumber> 0.3.1 Similar to createDeterministicAddresses except that the one address that is returned will not be added to the Bitmessage user interface or the keys.dat file. passphrase should be base64 encoded. addressVersionNumber should be set to 3 or 4 as these are the only ones currently supported. streamNumber must be set to 1 as this is the only one currently supported.

Returns a single address.

Warning: At present, Bitmessage gets confused if you use both this API command and the UI to make addresses at the same time.

getAllInboxMessages 0.2.7 Does not include trashed messages. Returns a list of objects with these properties:
  • msgid (hex)
  • toAddress (ascii/utf-8)
  • fromAddress (ascii/utf-8)
  • subject (base64, decodes into utf-8)
  • message (base64, decodes into utf-8)
  • encodingType (integer)
  • receivedTime (integer, Unix time)
  • read (integer representing binary state (0 or 1))

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 base64 encoding Bitmessage uses includes line breaks including one on the end of the string.

getAllInboxMessageIDs 0.2.7 Returns a list of msgids of all Inbox messages with there properties:
  • msgid (hex)
getInboxMessageByID <msgid> [read] 0.4.0 Returns an object with these properties:
  • msgid (hex)
  • toAddress (ascii/utf-8)
  • fromAddress (ascii/utf-8)
  • subject (base64, decodes into utf-8)
  • message (base64, decodes into utf-8)
  • encodingType (integer)
  • receivedTime (integer, Unix time)
  • read (integer representing binary state (0 or 1))

Optionally sets the specific message to have a read status of 'read' (bool).

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it should be given in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.

getSentMessageByAckData <ackData> 0.3.4 Returns an object with these properties:
  • msgid (hex)
  • toAddress (ascii/utf-8)
  • fromAddress (ascii/utf-8)
  • subject (base64, decodes into utf-8)
  • message (base64, decodes into utf-8)
  • encodingType (integer)
  • lastActionTime (integer, Unix time)
  • status (ascii/utf-8)
  • ackData (hex)
getAllSentMessages 0.3.4 Returns an object with these properties:
  • msgid (hex)
  • toAddress (ascii/utf-8)
  • fromAddress (ascii/utf-8)
  • subject (base64, decodes into utf-8)
  • message (base64, decodes into utf-8)
  • encodingType (integer)
  • lastActionTime (integer, Unix time)
  • status (ascii/utf-8)
  • ackData (hex)
getSentMessageByID <msgid> 0.3.4 Returns an object with these properties:
  • msgid (hex)
  • toAddress (ascii/utf-8)
  • fromAddress (ascii/utf-8)
  • subject (base64, decodes into utf-8)
  • message (base64, decodes into utf-8)
  • encodingType (integer)
  • lastActionTime (integer, Unix time)
  • status (ascii/utf-8)
  • ackData (hex)
getSentMessagesBySender <fromAddress> 0.3.4 Returns a list of objects with these properties:
  • msgid (hex)
  • toAddress (ascii/utf-8)
  • fromAddress (ascii/utf-8)
  • subject (base64, decodes into utf-8)
  • message (base64, decodes into utf-8)
  • encodingType (integer)
  • lastActionTime (integer, Unix time)
  • status (ascii/utf-8)
  • ackData (hex)
trashMessage <msgid> 0.2.7 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] [TTL] 0.2.7 or 0.4.5 returns ackdata encoded in hex. subject and message must be encoded in base64 which may optionally include line breaks. If used, the encodingType must be set to 2; this is included for forwards compatibility. TTL is specified in seconds; values outside the bounds of 3600 to 2419200 will be moved to be within those bounds. TTL defaults to 4 days. TTL is only available in PyBitmessage version 0.4.5 and higher.
sendBroadcast <fromAddress> <subject> <message> [encodingType] [TTL] 0.2.7 or 0.4.5 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. TTL is specified in seconds; values outside the bounds of 3600 to 2419200 will be moved to be within those bounds. TTL defaults to 4 days. TTL is only available in PyBitmessage version 0.4.5 and higher.
getStatus <ackData> 0.3.0 returns one of these strings: notFound, findingPubkey, doingPOW, sentMessage, or ackReceived notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
listSubscriptions 0.4.0 Returns a list of objects with these properties:
  • label (base64, decodes into utf-8)
  • address (ascii/utf-8)
  • enabled (bool)
addSubscription <address> [label] 0.3.1 Subscribe to an address. label must be base64-encoded.
deleteSubscription <address> 0.3.1 Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
listAddressBookEntries 0.4.0 Returns a list of objects with these properties:
  • address (ascii/utf-8)
  • label (base64, decodes into utf-8)
addAddressBookEntry <address> <label> 0.4.0 Add an entry to your address book. label must be base64-encoded.
deleteAddressBookEntry <address> 0.4.0 Delete an entry from your address book. The program does not check to see whether it was there in the first place.
trashSentMessageByAckData <ackData> 0.4.0 Trashes a sent message based on its ackdata. ackData should be encoded in hex. Returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked.
createChan <passphrase> 0.4.2 Creates a new chan. passphrase must be base64 encoded. Outputs the corresponding Bitmessage address.
joinChan <passphrase> <address> 0.4.2 Join a chan. passphrase must be base64 encoded. Outputs "success"
leaveChan <address> 0.4.2 Leave a chan. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
deleteAddress <address> 0.4.2 Permanently delete an address from Your Identities and your keys.dat file. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
decodeAddress <address> 0.4.2 Returns an object with these properties:
  • status (ascii/utf-8)
  • addressVersion (ascii integer)
  • streamNumber (ascii integer)
  • ripe (base64, decodes into binary data)
addAddressToBlackWhiteList <address> [label] 0.4.5 Add an entry to your black or white list- whichever you are currently using. label must be base64-encoded.
removeAddressFromBlackWhiteList <address> 0.4.5 Delete an entry from your black or white list- whichever you are currently using (but not both).
clientStatus 0.4.0 Returns the softwareName, softwareVersion, networkStatus, networkConnections, numberOfPubkeysProcessed, numberOfMessagesProcessed, and numberOfBroadcastsProcessed. networkStatus will be one of these strings: "notConnected", "connectedButHaveNotReceivedIncomingConnections", or "connectedAndReceivingIncomingConnections".

Note: If the minimum required version is higher than page is obsolete then the code is available in source but not yet available in a compiled binary.

Possible error values

Here are the various error numbers and descriptions you might see.

Error Number Message
0000 API Error 0000: I need parameters!
0001 API Error 0001: The specified passphrase is blank.
0002 API Error 0002: The address version number currently must be 3 or 4 (or 0 which means auto-select).
0003 API Error 0003: The stream number must be 1 (or 0 which means auto-select). Others aren't supported.
0004 API Error 0004: Why would you ask me to generate 0 addresses for you?
0005 API Error 0005: You have (accidentally?) specified too many addresses to make. Maximum 999. This check only exists to prevent mischief; if you really want to create more addresses than this, contact the Bitmessage developers and we can modify the check or you can do it yourself by searching the source code for this message.
0006 API Error 0006: The encoding type must be 2 because that is the only one this program currently supports.
0007 API Error 0007: Could not decode address
0008 API Error 0008: Checksum failed for address
0009 API Error 0009: Invalid characters in address
0010 API Error 0010: Address version number too high (or zero) in address
0011 API Error 0011: The address version number currently must be 2, 3, or 4. Others aren't supported.
0012 API Error 0012: The stream number must be 1. Others aren't supported.
0013 API Error 0013: Could not find your fromAddress in the keys.dat file.
0014 API Error 0014: Your fromAddress is disabled. Cannot send.
0015 API Error 0015: The length of ackData should be 32 bytes (encoded in hex thus 64 characters).
0016 API Error 0016: You are already subscribed to that address.
0017 API Error 0017: Label is not valid UTF-8 data.
0018 API Error 0018: Chan name does not match address.
0019 API Error 0019: The length of hash should be 20 bytes (encoded in hex thus 40 characters).
0020 API Error 0020: Invalid method: <method_name_you_tried_to_execute>
0021 API Error 0021: Unexpected API Failure
0022 API Error 0022: Decode Error
0023 API Error 0023: Bool expected
0024 API Error 0024: Chan address is already present.
0025 API Error 0025: Specified address is not a chan address. Use deleteAddress API call instead.
0026 API Error 0026: Varint encoded in address is malformed.
0027 API Error 0027: Message is too long.
0028 API Error 0028: You have already black-/white-listed that address.
0029 API Error 0029: That entry does not exist in the black-/white-list.