Help: FAQs, overviews and step by step guides

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?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.