We use cookies (including third-party cookies) to remember your site preferences, to help us understand how visitors use our sites and to make any adverts we show on 3rd party sites more relevant. To learn more, please see our privacy policy and our cookie policy.
To agree to our use of cookies, click 'Accept' or choose 'Options' to set your preferences by cookie type.
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.
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.
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.
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.
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.
The XML API currently provides 8 services:
The interface for these is described below.
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>
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>
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>
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>
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>
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>
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. |
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>
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 |
| 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 |
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.
BullionVault Ltd © 2024
We use cookies to remember your site preferences, record your referrer, improve the performance of our site and to make any adverts we show on 3rd party sites more relevant. For more information, see our cookie policy.
Please select an option below and 'Save' your preferences.
You can update your cookie preferences at any time from the 'Cookies' link in the footer.
You have not been active for some time.
For your security you will be logged out in minutes unless you take action.
