Bitmessage Wiki - User contributions [en]

API Reference

2013-08-20T10:33:21Z

Ax64ax:

=== Introduction ===

The PyBitmessage API uses [https://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file (the values "username" and "password" are merely examples):
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
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.
<pre>
import xmlrpclib
import json
import time

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

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! 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
|-
| listAddresses|| || 0.2.7 || Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
* label (utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
|-
| 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 as this is the only one 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.
|-
|<code>getAllInboxMessages</code>|| || 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)
* [[Protocol_specification#Message_Encodings|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.
|-
| getInboxMessageByID || <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)
* [[Protocol_specification#Message_Encodings|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 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)
* [[Protocol_specification#Message_Encodings|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)
* [[Protocol_specification#Message_Encodings|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)
* [[Protocol_specification#Message_Encodings|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)
* [[Protocol_specification#Message_Encodings|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] || 0.2.7 || 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.
|-
| sendBroadcast || <fromAddress> <subject> <message> [encodingType] || 0.2.7 || 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.
|-
| getStatus || <ackData> || 0.3.0 || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| 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.
|-
| listSubscriptions|| || Source || Returns a list of objects with these properties:
* label (utf-8)
* address (ascii/utf-8)
* enabled (bool)
|}

'''Note:''' Version "source" indicates, that the function is only available in the source version of PyBitmessage and has not yet been included in a precompiled binary.

==== Possible error values ====

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

{|class="wikitable"
! 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 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 or 3. 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: asdfasdf
|}

Protocol specification

2013-08-20T10:31:59Z

Ax64ax:

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-256)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#Object_types|object]]
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the length as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the length as uint32_t
|-
| - || 9 || 0xff followed by the length as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. This protocol and structure supports IPv6, '''but note that the original client currently only supports IPv4 networking'''. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 (or 8)|| time || uint32 || the Time. Protocol version 1 clients use 4 byte time while protocol version 2 clients use 8 byte time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. The original client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== Message types ==

=== version ===

When a node creates an outgoing connection, it will immediately advertise its version. The remote node will respond with its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|message header]] with the command string "verack".

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 34x? || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getdata ===

getdata is used in response to an ''inv'' message to retrieve the content of a specific object after filtering known elements.

Payload (maximum payload length: 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

== Object types ==
Objects are a subset of network messages. They are shared throughout a stream. A client should advertise objects that are not older than 2.5 days. To be a valid object, the [[Proof of work|Proof Of Work]] has to be done.

=== getpubkey ===

When a node has the hash of a public key (from an address) but not the public key itself, it must send out a request for the public key.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||POW nonce||uint64_t||Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 4 (or 8)||time||uint32_t||The time that this message was generated and broadcast. We are transitioning to 8 byte time.
|-
| 1+||address version||var_int||The address' version
|-
| 1+||stream number||var_int||The address' stream number
|-
| 20||pub key hash||uchar[]||The ripemd hash of the public key
|}

=== pubkey ===

A version 2 public key. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 8||POW nonce||uint64_t||Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 4 (or 8)||time||uint32_t||The time that this message was generated and broadcast. We are transitioning to 8 byte time.
|-
| 1+||address version||var_int||The address' version which is set to 2.
|-
| 1+||stream number||var_int||The address' stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 8||POW nonce||uint64_t||Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 4 (or 8)||time||uint32_t||The time that this message was generated and broadcast. We are transitioning to 8 byte time.
|-
| 1+||address version||var_int||The address' version which is set to 3.
|-
| 1+||stream number||var_int||The address' stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the time to the extra_bytes.
|}

=== msg ===
Used for person-to-person messages.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||POW nonce||uint64_t||Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 4 (or 8)||time||uint32_t||The time that this message was generated and broadcast. We are transitioning to 8 byte time.
|-
| 1+ ||streamNumber||var_int||The stream number of the destination address.
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== broadcast ===
Version 1 broadcast messages are sent in-the-clear. Version 2 are encrypted. Users who are subscribed to the sending address will see the message appear in their inbox.

Version 1 broadcast format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || POW nonce|| uint64_t|| The [[Proof of work|Proof Of Work]] nonce
|-
| 4 (or 8) || time|| uint32_t|| The time that the message was broadcast. We are transitioning to 8 byte time.
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 1 in this case.
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 20 || address hash|| uchar[]||The sender's address hash. This is included so that nodes can more cheaply detect whether this is a broadcast message for which they are listening, although it must be verified with the public key above.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which covers everything from the broadcast version down through the message.
|}

Version 2 broadcasts:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || POW nonce|| uint64_t|| The [[Proof of work|Proof Of Work]] nonce
|-
| 4 (or 8) || time|| uint32_t|| The time that the message was broadcast. We are transitioning to 8 byte time.
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 in this case.
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Broadcast_Data|Unencrypted Broadcast Data Format]]
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 in this case. This is included here so that it can be signed.
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which covers everything from the broadcast version down through the message.
|}

API Reference

2013-08-06T12:41:54Z

Ax64ax:

=== Introduction ===

The PyBitmessage API uses [https://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file (the values "bradley" and "password" are merely examples):
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = bradley
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
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 "bradley", 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.
<pre>
import xmlrpclib
import json
import time

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

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! 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:
* label (utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 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] || 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> || 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 as this is the only one 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.
|-
|<code>getAllInboxMessages</code>|| || 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)
* [[Protocol_specification#Message_Encodings|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.
|-
| getInboxMessageByID || <msgid> || 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)
* [[Protocol_specification#Message_Encodings|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 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> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| 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 which may optionally include line breaks. 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.
|-
| getStatus || <ackData> || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| addSubscription|| <address> [label] || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listSubscriptions|| || Returns a list of objects with these properties:
* label (utf-8)
* address (ascii/utf-8)
* enabled (bool)
|}

==== Possible error values ====

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

{|class="wikitable"
! 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 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 or 3. 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: asdfasdf
|}

API Reference

2013-08-06T12:40:43Z

Ax64ax:

=== Introduction ===

The PyBitmessage API uses [https://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = bradley
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
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 "bradley", 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.
<pre>
import xmlrpclib
import json
import time

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

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! 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:
* label (utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 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] || 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> || 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 as this is the only one 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.
|-
|<code>getAllInboxMessages</code>|| || 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)
* [[Protocol_specification#Message_Encodings|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.
|-
| getInboxMessageByID || <msgid> || 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)
* [[Protocol_specification#Message_Encodings|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 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> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| 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 which may optionally include line breaks. 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.
|-
| getStatus || <ackData> || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| addSubscription|| <address> [label] || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listSubscriptions|| || Returns a list of objects with these properties:
* label (utf-8)
* address (ascii/utf-8)
* enabled (bool)
|}

==== Possible error values ====

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

{|class="wikitable"
! 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 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 or 3. 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: asdfasdf
|}

API Reference

2013-08-06T12:21:26Z

Ax64ax:

=== Introduction ===

The PyBitmessage API uses [https://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = bradley
apipassword = bradley'spassword
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
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 "bradley", 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.
<pre>
import xmlrpclib
import json
import time

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

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! 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:
* label (utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 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] || 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> || 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 as this is the only one 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.
|-
|<code>getAllInboxMessages</code>|| || 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)
* [[Protocol_specification#Message_Encodings|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.
|-
| getInboxMessageByID || <msgid> || 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)
* [[Protocol_specification#Message_Encodings|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 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> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| 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 which may optionally include line breaks. 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.
|-
| getStatus || <ackData> || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| addSubscription|| <address> [label] || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listSubscriptions|| || Returns a list of objects with these properties:
* label (utf-8)
* address (ascii/utf-8)
* enabled (bool)
|}

==== Possible error values ====

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

{|class="wikitable"
! 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 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 or 3. 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: asdfasdf
|}

API Reference

2013-08-06T12:18:53Z

Ax64ax:

The PyBitmessage API uses [https://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = bradley
apipassword = yourSuperWonderfulPassword98a8#5223345
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
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 "bradley", 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.
<pre>
import xmlrpclib
import json
import time

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

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! 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:
* label (utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 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] || 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> || 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 as this is the only one 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.
|-
|<code>getAllInboxMessages</code>|| || 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)
* [[Protocol_specification#Message_Encodings|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.
|-
| getInboxMessageByID || <msgid> || 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)
* [[Protocol_specification#Message_Encodings|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 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> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 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)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| 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 which may optionally include line breaks. 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.
|-
| getStatus || <ackData> || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| addSubscription|| <address> [label] || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listSubscriptions|| || Returns a list of objects with these properties:
* label (utf-8)
* address (ascii/utf-8)
* enabled (bool)
|}

==== Possible error values ====

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

{|class="wikitable"
! 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 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 or 3. 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: asdfasdf
|}