XML API BullionVaults

Zusammenfassung

Das BullionVault-System hat zwei Oberflächen: Die normale Benutzeroberfläche und eine XML-Oberfläche für Trading Roboter. Obwohl die XML-Oberfläche nicht eines der primären Dienste BullionVaults ist, kann es die Entwicklung von Trading Roboter vereinfachen. In diesem Dokument wird die XML-Oberfläche beschrieben und die zum Starten der Trading Roboter nötigen Informationen angegeben. Es ist kein ausführliches Dokument und es enthält keine Informationen über Handelsstrategien.

Zielgruppe

Dieses Dokument ist für Entwickler geeignet. Insbesondere sollte der Leser mit CGI, dem HTTP-Protokoll für Abfrage/Rückmeldung und den XML-Dateiformate vertraut sein.

Disclaimer

Die XML-Oberfläche wird weder mit Garantie noch mit Support geliefert. BullionVault selber benutzt die Oberfläche und hat daher ein starkes Interesse an ihre Genauigkeit und Stabilität. BullionVault kann aber nicht die Stabilität der Oberfläche oder die Genauigkeit der angegebenen Informationen garantieren.

Geschäfte sind mit dem Risiko finanziellen Verlustes verbunden. Automatische Geschäfte sind mit vielen zusätzlichen Risikofaktoren verbunden, inklusive die Genauigkeit der Informationen, die Zuverlässigkeit der Verbindungen, Geschwindigkeit der Systemantwort u.s.w. Durch die Benutzung von XML API akzeptieren Sie alle die damit verbundenen Risiken inklusive der eventuelle finanzielle Verlust.

BullionVault behält sich das Recht vor, Kunden Kosten zu berechnen oder sie zu sperren, wenn ihre Handelsroboter gegen die Nutzungsbedingungen zum Beispiel durch exzessiven Gebrauch von Systemressourcen verstoßen. Nutzen Sie bitte das System in sinnvollem Mass.

Überblick

Die Programmierschnittstelle BullionVaults läuft auf ähnlicher Weise wie eine Webseite mit normaler Benutzeroberfläche. Die CGI-Protokolle werden gesendet und der Server sendet die Antwort zurück. Der Unterschied ist, dass die Antwort im XML- und nicht HTML-Format ist. Ein erfahrener Entwickler sollte daher keine Probleme mit diesem System haben. Alle die für Aufträge notwendigen Benutzeroberflächen-Seiten (z.B. die Marktseiten) haben eine entsprechende XML-Version. Die meisten zusätzlichen Seiten, die nicht für Geschäfte notwendig sind (z.B. Kontoauszüge und -einstellungen), haben keine entsprechende XML-Version und müssen manuell benutzt werden.

Sicherheit

BullionVault benutzt ein erweitertes Anmeldungsprotokoll, das einen normalen Benutzername, ein Passwort und eine optionale (aber empfohlene) Kontrolle der persönlichen Sicherheitsfrage enthält. Alle privaten Mitteilungen werden über diese sichere Verbindung durchgeführt. Die öffentlichen Informationen wie die Marktanzeige können über eine unsichere HTTP-Verbindung aufgerufen werden. Unsere Webserver benutzen ein Cookie, um Ihre Anmeldesession rück zu verfolgen (JSESSIONID). Ihre Roboter müssen Cookies so behandeln, wie ein normaler Browser, sonst wird Ihre Anmeldung immer wieder vergessen.

Wenn Sie zum ersten Mal eine sichere Seite über einem HTTPS-Client benutzen, wird der Benutzer oder der Roboter temporär an die Anmeldeseite weitergeleitet:

https://Gold.BullionVault.de/secure/login.do

Die CGI-Parameter der CGI-Seite j_username j_password, die gesendet werden an:

https://Gold.BullionVault.de/secure/j_security_check?j_username=XXX&j_password=YYY

Wenn korrekt, wird der Benutzer entweder angemeldet oder die Kontrollseite der persönlichen Sicherheitsfrage wird angezeigt (wenn aktiviert).

Es gibt keine entsprechende XML-Seite für die Kontrollseite der persönlichen Sicherheitsfrage. Damit die Roboter leichter diese Kontrollen durchführen können, wird wie folgt in dem Kopf der Seite ein META-Tag eingefügt:

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

Diese Zeichen müssen korrekt dem Server gesendet werden. Das Inhaltsattribut erteilt die Position dieser Zeichen in aufsteigender der Zahlen. In dem obigen Beispiel muss der Roboter das erste, dritte und sechste Zeichen der persönlichen Sicherheitsfrage als Antwort [0], Antwort [1] und Antwort [2] angeben. Wenn zum Beispiel die persönliche Sicherheitsfrage 'ABCDEFGHI' sind, soll Folgendes angegeben werden:

https://Gold.BullionVault.de/secure/second_login.do?response[0]=A&response[1]=C&response[2]=F

Nach der Anmeldung kann der Benutzer auch in die sicheren Seiten navigieren.

XML API-Anfragen

Der XML API liefert die folgenden 8 Dienste:

Den Markt anzeigen
Einen Auftrag erteilen
Einen Auftrag abbrechen
Das Saldo anzeigen
Aufträge anzeigen
Einen einzelnen Auftrag anzeigen
Die Einstellungen zur Gewichtseinheit anzeigen
Die Einstellungen zur Gewichtseinheit aktualisieren

Die entsprechende Benutzeroberfläche wird hier beschrieben.

Marktübersicht

URL: https://Gold.bullionvault.de/view_market_xml.do

CGI-Parameter	Beschreibung	Beispiel
considerationCurrency	Die anzuzeigende Währung: USD, GBP, EUR oder keine.	considerationCurrency=USD
securityId	Der anzuzeigende Tresor: AUXLN (Gold London), AUXZU (Gold Zürich), AUXNY (Gold New York), AUXSG (Singapur), AUXTN (Toronto), AGXZU (Silber Zürich), AGXLN (Silber London), AGXSG (Silber Singapur), AGXTN (Silber Toronto) oder keiner.	securityId=AUXLN
quantity	Die mindeste anzuzeigende Menge: Der Wert 0,005 wird alle Ankaufs- / Verkaufsangebote unter 5 Gramm ausschliessen. Der Wert 0,001 wird alle Angebote anzeigen.	quantity=0.001
marketWidth	Die höchste Anzahl an Ankaufs- und Verkaufsangeboten auf jedem einzelnen Markt. Der Standardwert ist 1.	marketWidth=3

Bitte beachten Sie, dass Sie Zugang zu der Ansicht Märkte API über die folgende Adresse erhalten: https://gold.bullionvault.de/secure/api/v2/view_market_xml.do (Sie müssen hiefür angemeldet sein.) Die Version, die Sie sehen, wenn Sie nicht angemeldet sind (https://gold.bullionvault.de/view_market_xml.do) ist auf dem Server gespeichert und nicht so aktuell wie die Version, für die Sie sich anmelden müssen.

Beispielantworten:

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

Auftrag abbrechen

URL: https://Gold.BullionVault.de/secure/cancel_order_xml.do

CGI-Parameter	Beschreibung	Beispiel
orderId	Die Auftragsnummer die von place_order gesendet wird.	orderId=12345
confirmed	Für Roboter muss dieser Wert immer wahr (true) sein.	confirmed=true

Einen Auftrag erteilen

URL: https://Gold.BullionVault.de/secure/place_order_xml.do

CGI-Parameter	Beschreibung	Beispiel
actionIndicator	B oder S, d.h. kaufen (Gold für Geld) oder verkaufen (Geld für Gold).	actionIndicator=S
considerationCurrency	Die zu handelnde Währung: USD, GBP, EUR.	considerationCurrency=USD
securityId	Der zu handelnde Tresor: AUXLN (London), AUXZU (Zürich), AUXNY (New York).	securityId=AUXZU
quantity	Die zu handelnde Menge (in Kilo). 1,234 entspricht 1 Kilo und 234 Gramm. Sie darf nicht mehr als 3 Dezimalstellen enthalten.	quantity=1.234
limit	Der Grenzpreis als ganze Zahl des Angebots.	limit=13437
typeCode	Einer der Folgenden Codes TIL_CANCEL (Bis Wiederruf), TIL_TIME (Bis Uhrzeit), IMMEDIATE (Gleich ausführen) oder FILL_KILL (Alles oder nichts).	typeCode=TIL_TIME
clientTransRef	Ihr Referenzcode.	clientTransRef=ABC12345
confirmed	Für Roboter muss dieser Wert immer wahr (true) sein.	confirmed=true
goodUntil	Es muss leer sein, ausser der typeCode ist TIL_TIME: In diesem Fall muss es ein Zeitstempel im Format 'yyyy-MM-dd%20HH:mm' sein.	goodUntil=2005-06-02 19:15

Beispielantworten:

		<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"/>
			</message>
		</envelope>

Das Saldo anzeigen

URL: https://Gold.BullionVault.de/secure/view_balance_xml.do

CGI-Parameter	Beschreibung	Beispiel
simple	Bitte geben Sie an, ob eine einfache Reaktion zum Saldo gewünscht wird, inklusive der Kundenpositionen, aber ohne Informationen zu ausstehenden Gebühren. Für die große Mehrheit unserer Benutzer ist diese zusätzliche Information nicht notwendig und sorgt für zusätzliche Systemlast auf unserem Server. Es wird dringend empfohlen, die Konfiguration simple=true zu verwenden.	simple=true

Beispielantworten:

		<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>
				</clientBalance>
			</message>
		</envelope>

Aufträge anzeigen

URL: https://Gold.BullionVault.de/secure/view_orders_xml.do

CGI-Parameter	Beschreibung	Beispiel
securityId	Der anzuzeigende Tresor: AUXLN (London), AUXZU (Zürich), AUXNY (New York) oder keiner.	securityId=AUXNY
considerationCurrency	Die anzuzeigende Währung: USD, GBP, EUR oder keine.	considerationCurrency=USD
status	Er filtert die angezeigte Auftragsliste. Einer der folgenden Statusoptionen: OPEN (alle offene Aufträge anzeigen), DEALT (alle gehandelte Aufträge anzeigen), OPEN_DEALT (offene + gehandelte Aufträge), CLOSED (geschlossene Aufträge), REJECTED (zurückgewiesene Aufträge) oder ganz leer. Es ist höchst ratsam, dass Roboterentwickler nur OPEN oder ZURÜCKGEWIESEN benutzen, und den Status der anderen Aufträgen mittels view_single_order kontrollieren. Auf dieser Weise werden Benutzer eine viel schnellere Antwort bekommen.	status=OPEN
fromDate	Auf Wunsch Möglichkeit, um die Aufträge zu filtern, damit nur die angezeigt werden, die nach einem bestimmten Datum erteilt wurden. Ohne andere Angaben werden die Information für die letzten 30 Tage angezeigt.	fromDate=20130921
toDate	Auf Wunsch Möglichkeit, um die Aufträge zu filtern, damit nur die angezeigt werden, die vor einem bestimmten Datum erteilt wurden. Bitte beachten Sie: Die größtmögliche Differenz zwischen dem fromDate und toDate beträgt 31 Tage.	toDate=20130925
page	Die Antwort zu den anzuzeigenden Aufträgen ist in Seiten aufgeteilt, angefangen von Seite 0. Benutzen Sie diesen Parameter, um die Seite zu wählen.	page=0

Beispielantworten:

		<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"/>
					<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"/>
					<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"/>
					<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"/>
				</orders>
			</message>
		</envelope>

Einen einzelnen Auftrag anzeigen

URL: https://Gold.BullionVault.de/secure/view_single_order_xml.do

CGI-Parameter	Beschreibung	Beispiel
orderId	Die Auftragsnummer die von place_order gesendet wird.	orderId=1207516

Beispielantworten:

		<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"/>
			</message>
		</envelope>

Ergänzende Bemerkungen

Das Feld statusCode für Auftragsantworten enthält einen der folgenden Werte:

Einstellungen der Gewichtseinheiten anzeigen

URL: https://gold.bullionvault.de/secure/api/v2/view_weight_unit_xml.do

Wert	Beschreibung
OPEN	Der Auftrag ist offen.
DONE	Der Auftrag ist geschlossen
EXPIRED	Der Auftrag ist abgelaufen
CANCELLED	Der Auftrag wurde abgebrochen
KILLED	Der Auftrag wurde gelöscht, weil er nicht entgegengenommen wurde
NOFUNDS	Der Auftrag wurde wegen ungenügender Gelder zurückgewiesen
BADLIMIT	Der Auftrag wurde wegen zu hochem/niedrigen Grenzbetrag zurückgewiesen
SILVER_RESTRICTED	Kauf und Handel von Silber nicht erlaubt.
QUEUED	Der Auftrag ist gereiht und wird demnächst ausgeführt

CGI Parameter	Beschreibung	Beispiel
n/a	n/a	n/a

Beispielantworten:

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

Einstellungen der Gewichtseinheiten aktualisieren

URL: https://gold.bullionvault.de/secure/api/v2/update_weight_unit_xml.do

CGI Parameter	Beschreibung	Beispiel
newUnitOfWeight	Die von Ihnen wählbaren Gewichtseinheit sind KG und TOZ.	newUnitOfWeight=TOZ

Häufig gestellte Fragen

F. Wo kann ich weitere Informationen erhalten?A. Die beste Informationsquelle ist die Client-Benutzeroberfläche. XML API und die Client-Benutzeroberfläche funktionieren auf der gleichen Art und Weise; der Unterschied liegt in der Datenanzeige.

F. Kann BullionVault 'X' hinzufügen?A. Ja, obwohl die Entwicklung von XML API momentan nicht unsere Priorität ist. Bitte emailen Sie Ihre Vorschläge an xmlapi@bullionvault.de. xmlapi@BullionVault.com.

F. Wie aktuell sind die XML-Daten?A. Genau so aktuell wie die Daten der Benutzeroberfläche. Beide werden von der gleichen Quelle generiert.

F. Gibt es einen öffentlichen Testserver? A. Nein, obwohl wir diese Möglichkeit bei hoher Anfrage in Betracht nehmen würden. Bitte emailen Sie Ihre Vorschläge an xmlapi@bullionvault.de. xmlapi@BullionVault.com.