The BullionVault XML API

Abstract

There are two interfaces into the BullionVault system: The normal GUI interface for users and an XML interface for trading robots. While the XML interface is not considered a primary BullionVault service, it can be used to greatly simplify the development of trading robots.

This document describes the XML interface, giving a bot writer sufficient information to get started. It is not a comprehensive guide, nor does it give any information on trading strategies.

Audience

This document is aimed at programmers. In particularly, the reader should be familiar with CGI and the HTTP request/response protocol as well as XML file formats.

Disclaimer

The XML interface is supplied as is, with no warranty or support. BullionVault itself uses the interface, and for this reason has a vested interest in its accuracy and stability, however BullionVault makes no guarantees of the stability of the interface or the accuracy of the information it provides.

Trading involves risk of financial loss. Automated trading involves many additional risks including accuracy of information, reliability of connections, speed of system response, etc. By using the XML API you accept all risks involved, including, but not limited to financial loss for any reason.

BullionVault reserves the right to charge or suspend clients whose robots breach the Terms of Use — e.g. by using excessive system resources. Please poll the system within sensible limits.

Overview

The BullionVault API operates in a similar fashion to the normal GUI site. CGI parameters are submitted and a response is sent back from the server. The key difference is that the response is XML rather than HTML. As such, it should be relatively easy for a skilled programmer to interface with the system and trade by wire. All the GUI pages which are necessary for trading (e.g. the market viewer) have XML equivalents. Most auxiliary pages not necessary for trading (e.g. statements and account settings) have no XML equivalent and must be used manually.

Security

BullionVault uses an enhanced login protocol comprising of a normal username & password login together with an optional (but recommended) memorable information check. Any sensitive or valuable communications will be performed over this secure connection. Please note that our webservers use a session cookie to track your login session (JSESSIONID). Your robot must treat cookies in a similar fashion to a normal browser, or your login will be continually forgotten.

On first requesting a secure page using an HTTPS client, the user or bot is temporarily diverted to a username/password screen at:

https://www.bullionvault.com/secure/login.do

This screen's CGI parameters j_username j_password to be submitted to:

https://www.bullionvault.com/secure/j_security_check

The post body would contain:

j_username=XXX&j_password=YYY

On success, the user is then either logged in or will be shown the memorable information check page if this security enhancement is enabled..

There is no XML equivalent of the memorable information check page. To simplify processing of this check, the bot can inspect a META tag in the html head section of the challenge, which appears as follows:

<meta name="X-Challenge" CONTENT="0,2,5"/>

Three characters must be correctly submitted to the server. The CONTENT attribute gives the position of these characters, zero-indexed. Thus in the example above the bot must submit the first, third and sixth memorable information characters as response[0], response[1] and response[2].

For example, if the memorable information is 'ABCDEFGHI' the correct submission will be:

https://www.bullionvault.com/secure/second_login.do?response[0]=A&response[1]=C&response[2]=F

After successfully logging in the user can now access secure pages.

XML API requests

The XML API currently provides 8 services:

• View the market
• Place an order
• Cancel an order
• View balance
• View orders
• View single order
• View weight unit setting
• Update weight unit setting

The interface for these is described below.

View market

URL: https://www.bullionvault.com/secure/api/v2/view_market_xml.do

CGI Parameter	Description	Example
considerationCurrency	The currency to view. May be one of USD, GBP, EUR or blank for all.	considerationCurrency=USD
securityId	The ID of the security to view. May be any valid security ID, or blank for all.	securityId=AUXLN
quantity	The minimum quantity to show. A value of 0.005 will filter out all bids/offers smaller than 5 grams. Use 0.001 to show all bids/offers.	quantity=0.001
marketWidth	The maximum number of bids and offers returned for each market. The default value is 1.	marketWidth=3

Note that the view market API should be accessed via https://www.bullionvault.com/secure/api/v2/view_market_xml.do (which requires you to be logged in). The non-logged in version (https://www.bullionvault.com/view_market_xml.do) is cached on the server and is not as up-to-date as the logged in version.

Sample response:

<envelope>
	<message type="MARKET_DEPTH_A" version="0.1">
		<market>
			<pitches>
				<pitch securityId="AUXLN" considerationCurrency="USD">
					<buyPrices>
						<price actionIndicator="B" quantity="0.1" limit="12510"/>
						<price actionIndicator="B" quantity="0.2" limit="12500"/>
						<price actionIndicator="B" quantity="0.1" limit="12490"/>
					</buyPrices>
					<sellPrices>
						<price actionIndicator="S" quantity="0.2" limit="12590"/>
						<price actionIndicator="S" quantity="0.1" limit="12600"/>
						<price actionIndicator="S" quantity="0.1" limit="12610"/>
					</sellPrices>
				</pitch>
			</pitches>
		</market>
	</message>
</envelope>

Cancel order

URL: https://www.bullionvault.com/secure/api/v2/cancel_order_xml.do

CGI Parameter	Description	Example
orderId	The order ID returned by place_order.	orderId=12345
confirmed	For bots, this value must always be true.	confirmed=true

Sample response:

<envelope>
	<message type="SINGLE_ORDER_A" version="0.1">
		<order orderId="19223" clientTransRef="CLIENT119222" actionIndicator="B" securityId="AUXZU" considerationCurrency="USD" quantity="0.1" quantityMatched="0" totalConsideration="0" totalCommission="0" limit="12679" typeCode="TIL_CANCEL" orderTime="2017-09-18 08:06:15 UTC" goodUntil="" lastModified="2017-09-18 08:06:15 UTC" statusCode="CANCELLED" tradeType="ORDER_BOARD_TRADE" orderValue="1267.9"/>
		<cancellable/>
	</message>
</envelope>

Place order

URL: https://www.bullionvault.com/secure/api/v2/place_order_xml.do

CGI Parameter	Description	Example
actionIndicator	One of B or S for buy (gold with currency) or sell (gold for currency).	actionIndicator=S
considerationCurrency	The currency to trade. Must be one of USD, GBP, EUR.	considerationCurrency=USD
securityId	The ID of the security to trade. May be any valid security ID.	securityId=AUXZU
quantity	The quantity to trade, in kilos. 1.234 represents 1 kilo, 234 grams. Must have no more than 3 decimal places.	quantity=1.234
limit	The limit price for the bid or offer, as an integer.	limit=13437
typeCode	One of TIL_CANCEL (Good until cancelled), TIL_TIME (Good until time), IMMEDIATE (Execute immediate) or FILL_KILL (Fill or kill).	typeCode=TIL_TIME
clientTransRef	Your reference code. Must be unique for this account.	clientTransRef=ABC12345
confirmed	For bots, this value must always be true.	confirmed=true
goodUntil	Must be blank unless the typeCode is TIL_TIME, in which case it must be a timestamp in the format 'yyyy-MM-dd%20HH:mm%20UTC'. The time should be in UTC.	goodUntil=2005-06-02 09:15

Sample response:

<envelope>
	<message type="PLACE_ORDER_A" version="0.1">
		<order orderId="1080" clientTransRef="asdf" actionIndicator="B" securityId="AUXLN"
			considerationCurrency="USD" quantity="0.001" quantityMatched="0.001"
			totalConsideration="12.59" totalCommission="0.11" limit="13500" typeCode="TIL_CANCEL"
			orderTime="2005-06-02 14:14:24 UTC" goodUntil="" lastModified="2005-06-02 14:14:25 UTC"
			statusCode="DONE" tradeType="ORDER_BOARD_TRADE"/>
	</message>
</envelope>

View balance

URL: https://www.bullionvault.com/secure/api/v2/view_balance_xml.do

CGI Parameter	Description	Example
simple	Specify whether to return a simple balance response, including client positions but without any pending settlement information. For the vast majority of bot users this extra information is not required and places extra load on our servers, It is strongly advised to pass simple=true.	simple=true

Sample response:

<envelope>
	<message type="CLIENT_BALANCE_A" version="0.1">
		<clientBalance>
			<clientPositions>
				<clientPosition securityId="AUXLN" available="3.026" total="3.026"
					classNarrative="GOLD" totalValuation="40578.66" valuationCurrency="USD"/>
				<clientPosition securityId="AUXNY" available="5" total="5"
					classNarrative="GOLD" totalValuation="67050" valuationCurrency="USD"/>
				<clientPosition securityId="AUXZU" available="3.983" total="3.983"
					classNarrative="GOLD" totalValuation="53412.03" valuationCurrency="USD"/>
				<clientPosition securityId="EUR" available="39983" total="39983"
					classNarrative="CURRENCY" totalValuation="49059.15" valuationCurrency="USD"/>
				<clientPosition securityId="GBP" available="24799.04" total="24799.04"
					classNarrative="CURRENCY" totalValuation="45084.66" valuationCurrency="USD"/>
				<clientPosition securityId="USD" available="49954.9" total="49954.9"
					classNarrative="CURRENCY" totalValuation="49954.9" valuationCurrency="USD"/>
			</clientPositions>
			<pendingSettlements>
				<pendingSettlement securityId="AUXZU" total="250.919" classNarrative="GOLD"
					totalValuation="3181652.92" valuationCurrency="USD">
					<pendingTransfers>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_RCT" balance="200"
							dueDate="2012-10-18 00:00:00 UTC"valuation="2536000" valuationCurrency="USD"/>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_RCT" balance="50"
							dueDate="2012-10-18 00:00:00 UTC" valuation="634000" valuationCurrency="USD"/>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_RCT" balance="0.919"
							dueDate="2012-11-02 00:00:00 UTC" valuation="11652.92" valuationCurrency="USD"/>
					</pendingTransfers>
				</pendingSettlement>
				<pendingSettlement securityId="AUXLN" total="0.92" classNarrative="GOLD"
					totalValuation="11656.4" valuationCurrency="USD">
					<pendingTransfers>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_RCT" balance="0.92"
							dueDate="2012-11-08 00:00:00 UTC" valuation="11656.4" valuationCurrency="USD"/>
					</pendingTransfers>
				</pendingSettlement>
				<pendingSettlement securityId="AGXLN" total="2.952" classNarrative="SILVER"
					totalValuation="37401.84" valuationCurrency="USD">
					<pendingTransfers>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_RCT" balance="1"
							dueDate="2012-10-04 00:00:00 UTC" valuation="12670" valuationCurrency="USD"/>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_RCT" balance="1.032"
							dueDate="2012-10-10 00:00:00 UTC" valuation="13075.44" valuationCurrency="USD"/>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_RCT" balance="0.92"
							dueDate="2012-10-31 00:00:00 UTC" valuation="11656.4" valuationCurrency="USD"/>
					</pendingTransfers>
				</pendingSettlement>
				<pendingSettlement securityId="USD" total="-44851.52" classNarrative="CURRENCY"
					totalValuation="-44851.52" valuationCurrency="USD">
					<pendingTransfers>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_EXP" balance="-13271.52"
							dueDate="2012-10-10 00:00:00 UTC" valuation="-13271.52" valuationCurrency="USD"/>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_EXP" balance="-20000"
							dueDate="2012-10-18 00:00:00 UTC" valuation="-20000" valuationCurrency="USD"/>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_EXP" balance="-11500"
							dueDate="2012-10-31 00:00:00 UTC" valuation="-11500" valuationCurrency="USD"/>
						<pendingTransfer type="CLIENT" lowestLedger="UNS_EXP" balance="-80"
							dueDate="" valuation="-80" valuationCurrency="USD"/>
					</pendingTransfers>
				</pendingSettlement>
				<pendingSettlement securityId="GBP" total="-98248.29" classNarrative="CURRENCY"
					totalValuation="-177829.4" valuationCurrency="USD">
					<pendingTransfers>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_EXP" balance="-6430"
							dueDate="2012-10-04 00:00:00 UTC" valuation="-11638.3" valuationCurrency="USD"/>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_EXP" balance="-10000"
							dueDate="2012-10-18 00:00:00 UTC" valuation="-18100" valuationCurrency="USD"/>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_EXP" balance="-81818.29"
							dueDate="2012-11-02 00:00:00 UTC" valuation="-148091.1" valuationCurrency="USD"/>
					</pendingTransfers>
				</pendingSettlement>
				<pendingSettlement securityId="EUR" total="-14260" classNarrative="CURRENCY"
					totalValuation="-17283.12" valuationCurrency="USD">
					<pendingTransfers>
						<pendingTransfer type="OFF_MARKET_TRADE" lowestLedger="UNS_EXP" balance="-14260"
							dueDate="2012-11-08 00:00:00 UTC" valuation="-17283.12" valuationCurrency="USD"/>
					</pendingTransfers>
				</pendingSettlement>
			</pendingSettlements>
		</clientBalance>
	</message>
</envelope>

View orders

URL: https://www.bullionvault.com/secure/api/v2/view_orders_xml.do

CGI Parameter	Description	Example
securityId	The ID of the security to view. May be any valid security ID, or blank for all.	securityId=AUXNY
considerationCurrency	The currency to view. May be one of USD, GBP, EUR or blank for all.	considerationCurrency=USD
status	Filters the list of orders returned. One of OPEN (show all open orders), DEALT (show all orders that have dealt), OPEN_DEALT (open + dealt orders), CLOSED (orders that are now closed), REJECTED (orders that were rejected) or blank for all. It is strongly recommended that bot writers use only the OPEN status, as it is specially optimized for bot use. Other orders should be viewed with the view_single_order message.	status=OPEN
fromDate	Optional parameter to filter the non open orders, only returning those placed after the given date. If not provided, will be set to 30 days ago. Date parameters do not apply to open orders.	fromDate=20130921
toDate	Optional parameter to filter the non open orders, only returning those placed before the given date. Please note: The maximum difference between fromDate and toDate is 31 days. Date parameters do not apply to open orders.	toDate=20130925
page	The response to view orders is paginated, starting at page zero. Use this parameter to select the page.	page=0

Sample response:

<envelope>
	<message type="ORDERS_A" version="0.4" page="0" pageSize="20">
		<orders clientId="******">
			<order orderId="1080" clientTransRef="asdf" actionIndicator="B"
				securityId="AUXLN" considerationCurrency="USD" quantity="0.001" quantityMatched="0.001"
				totalConsideration="12.59" totalCommission="0.11" limit="13500" typeCode="TIL_CANCEL"
					orderTime="2005-06-02 14:14:24 UTC" goodUntil="" lastModified="2005-06-02 14:14:25 UTC"
					statusCode="DONE" tradeType="ORDER_BOARD_TRADE"/>
			<order orderId="1061" clientTransRef="050520115557474" actionIndicator="B"
				securityId="AUXNY" considerationCurrency="USD" quantity="0.002" quantityMatched="0.002"
				totalConsideration="26.8" totalCommission="0" limit="13400" typeCode="TIL_CANCEL"
					orderTime="2005-05-20 15:59:33 UTC" goodUntil="" lastModified="2005-05-20 15:59:45 UTC"
					statusCode="DONE" tradeType="ORDER_BOARD_TRADE"/>
			<order orderId="1041" clientTransRef="050520120214131" actionIndicator="B"
				securityId="AUXNY" considerationCurrency="USD" quantity="0.002" quantityMatched="0.002"
				totalConsideration="27" totalCommission="0" limit="13500" typeCode="TIL_CANCEL"
					orderTime="2005-05-20 12:02:16 UTC" goodUntil="" lastModified="2005-05-20 12:02:17 UTC"
					statusCode="DONE" tradeType="ORDER_BOARD_TRADE"/>
			<order orderId="1000" clientTransRef="abc123" actionIndicator="B"
				securityId="AUXLN" considerationCurrency="GBP" quantity="0.1" quantityMatched="0.025"
				totalConsideration="182.5" totalCommission="1.46" limit="7300" typeCode="TIL_CANCEL"
					orderTime="2005-05-19 09:21:21 UTC" goodUntil="" lastModified="2005-05-19 09:21:21 UTC"
					statusCode="CANCELLED" tradeType="ORDER_BOARD_TRADE"/>
		</orders>
	</message>
</envelope>

View single order

URL: https://www.bullionvault.com/secure/api/v2/view_single_order_xml.do

CGI Parameter	Description	Example
orderId	The order ID returned by the place_order response.	orderId=1207516
clientTransRef	The transaction reference used in the place_order request (optional).	clientTransRef=BOTAUX20160905131249

Sample response:

<envelope>
	<message type="SINGLE_ORDER_A" version="0.1">
		<order orderId="1080" clientTransRef="asdf" actionIndicator="B" securityId="AUXLN" considerationCurrency="USD"
			quantity="0.001" quantityMatched="0.001" totalConsideration="12.59" totalCommission="0.11" limit="13500"
			typeCode="TIL_CANCEL" orderTime="2005-06-02 14:14:24 UTC" goodUntil="" lastModified="2005-06-02 14:14:25 UTC"
			statusCode="DONE" tradeType="ORDER_BOARD_TRADE"/>
	</message>
</envelope>

Additional notes

The statusCode field for order responses has one of the following values:

Value	Description.
OPEN	Order is open.
DONE	Order has closed.
EXPIRED	Order closed by expiring.
CANCELLED	Order was cancelled.
KILLED	Order was killed because it could not be filled.
NOFUNDS	Order was rejected due to insufficient funds.
BADLIMIT	Order was rejected due to limit too high/low.
SILVER_RESTRICTED	This account may not trade silver.
QUEUED	Order is queued awaiting processing.
AGIP_ENABLED	Selling is not allowed when Auto-Invest is enabled.

The tradeType field for order responses has one of the following values:

Value	Description.
ORDER_BOARD_TRADE	Order placed on the market order board (standard order).
ORDER_AT_FIX	Order at Fix price.
CLIENT_ORDER	Spot Market order.

View weight unit setting

URL: https://www.bullionvault.com/secure/api/v2/view_weight_unit_xml.do

CGI Parameter	Description	Example
n/a	n/a	n/a

Sample response:

<envelope>
	<message type="UNIT_OF_WEIGHT_SETTING" version="0.1">
		<unitOfWeightSetting value="KG"/>
	</message>
</envelope>

Update weight unit setting

URL: https://www.bullionvault.com/secure/api/v2/update_weight_unit_xml.do

CGI Parameter	Description	Example
newUnitOfWeight	The unit of weight preference to set for the account. One of KG and TOZ	newUnitOfWeight=TOZ

Values for securityId parameter

Security ID	Metal	Location
AUXZU	Gold	Zurich
AUXLN	Gold	London
AUXNY	Gold	New York
AUXTR	Gold	Toronto
AUXSG	Gold	Singapore
AGXZU	Silver	Zurich
AGXLN	Silver	London
AGXTR	Silver	Toronto
AGXSG	Silver	Singapore
PTXLN	Platinum	London

Frequently Asked Questions

Q. Can you add feature X?
A. Possibly, though development of the XML API is not a current priority. Please email any suggestions to xmlapi@BullionVault.com .

Q. How current is the XML data?
A. As current as the GUI data. They are both generated from the same source. Only the presentation differs.

Q. Is there a public test server available?
A. No, but if there is sufficient demand we would consider it. Please email any suggestions to xmlapi@BullionVault.com .

Q. When will the API be unavailable?
A. This RSS feed announces planned downtime.