XML API de BullionVault

Résumé

Le système de BullionVault a deux interfaces: l'interface GUI normale pour les utilisateurs et l'interface XML pour les robots informatiques "traders". L'interface XML n'est pas considérée comme un service "primaire" de BullionVault mais peut être utilisé pour simplifier le développement des robots informatiques. Ce document décrit l'interface XML, procurant à un développeur de robots informatiques suffisamment d'informations pour se lancer. Il ne s'agit pas d'un guide complet et nous ne donnons aucune information sur les stratégies d'achat ou de vente.

Pour qui ?

De document est destiné aux programmeurs / développeurs. Le lecteur doit être familier avec les protocoles de demande/réponse et avec les formats de fichiers XML.

Avertissement

L'interface XML est fournit sans garanties ni support. BullionVault utilise cette interface et a donc tout intérêt à ce qu'elle soit stable et fiable. Cependant, BullionVault ne garantit aucunement la stabilité de l'interface, ni l'exactitude des informations qu'elle procure.

Acheter et vendre comme un "trader" implique des risques de pertes financières. L'automatisation de cette activité implique des risques supplémentaires (exactitude des informations, fiabilité des connexions, vitesse du système de réponse etc.). En utilisant XML API vous acceptez tous les risques encourus incluant (mais non limités à) le risque financier quelle qu'en soit la raison.

BullionVault se réserve le droit de facturer ou de suspendre les clients dont les robots enfreignent les Conditions d'utilisation — par exemple en utilisant des ressources système excessives. Veuillez interroger le système dans des limites raisonnables.

Vue d'ensemble

L'API BullionVault opère comme le site GUI normal. Les paramètres CGI sont traités et la réponse est renvoyée du serveur. La principale différence est que la réponse est XML plutôt que HTML. Ainsi, il est relativement facile pour un programmeur qualifié d'interfacer avec le système et d'acheter ou de vendre de façon automatique. Toutes les pages GUI qui sont nécessaires à l'achat ou à la vente (par exemple la page d'affichage des marchés) ont des équivalents XML. Presque toutes les pages auxiliaires non nécessaires au trading (par exemple les relevés et la page de réglages) n'ont pas d'équivalent XML et doivent être configurées manuellement.

Sécurité

BullionVault utilise un protocole de connexion amélioré comprenant une connexion standard avec nom d'utilisateur et mot de passe ainsi qu'une option (recommandée) nécessitant un mot de passe supplémentaire. Toute information "sensible" est communiquée en passant par ce mode de connexion sécurisé. Les informations accessibles au public, comme celles concernant le marché par exemple, sont accessibles via une connexion HTTP non sécurisée. Veuillez noter que nos serveurs informatiques utilisent des sessions de cookies pour suivre vos connexions (JSESSIONID). Votre robot informatique doit traiter les cookies comme un outil de navigation normal ou votre connexion sera continuellement effacée.

A la première demande d'une page sécurisée utilisant HTTPS client, l'utilisateur ou le robot informatique est temporairement envoyé sur un écran de connexion avec nom d'utilisateur et mot de passe à saisir à l'adresse suivante :

https://or.bullionvault.fr/secure/login.do

Les paramètres CGI de cet écran j_username j_password sont soumis à :

https://or.bullionvault.fr/secure/j_security_check?j_username=XXX&j_password=YYY

En cas de succès, l'utilisateur est soit connecté directement, soit voit s'afficher un écran où il doit entrer son mot de passe supplémentaire si cette option de sécurité est activée.

Il n'y a pas d'équivalent XML à cette page de mot de passe supplémentaire. Pour faciliter cette opération aux robots informatiques une balise METAexiste dans la section HTML principale :

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

Trois caractères doivent être soumis correctement au serveur. L'attribut CONTENU donne la position de ces trois caractères, zéro indexé. Par exemple, le robot doit fournir le premier, le troisième et le sixième caractère en tant que réponse [0], réponse [1] et réponse [2]. Par exemple, si le mot de passe supplémentaire est "ABCDEFGHI" la réponse correcte sera :

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

Après s'être connecté, l'utilisateur peut accéder aux pages sécurisées.

Requêtes XML API

XML API fournit huit services différents à l'heure actuelle :

Consulter le marché
Passer un ordre
Annuler un ordre
Consulter les soldes
Suivre les ordres
Suivre un ordre en particulier
Configuration de l’unité de poids
Actualisation de la configuration de l’unité de poids

L'interface servant à faire cela est décrite ci-dessous.

Consulter le marché

URL : https://or.bullionvault.fr/view_market_xml.do

CGI Paramètre	Description	Exemple
Rémunération devise	Devise à consulter. Un de ces devises: USD, GBP, EUR ou laissez vide pour toutes.	considerationCurrency=USD
Sécurité	Coffre-fort à consulter. Un de ces coffres : AUXLN (Or Londres), AUXZU (Or Zurich), AUXNY (Or New York), AUXSG (Or Singapour), AUXTN (Or Toronto), AGXZU (Argent Zurich), AGXLN (Argent Londres), AGXSG (Argent Singapour), AGXTN (Argent Toronto) ou laissez vide pour tous.	securityId=AUXLN
Quantité	Quantité minimale à afficher. Une valeur de 0.005 exclut toutes les offres de vente ou d'achat inférieures à 5 grammes. Utilisez0.001 pour afficher toutes les offres de vente et d'achat.	quantity=0.001
Profondeur de marché	Nombre maximum d'offres d'achat et de vente pour chaque marché. La valeur par défaut est 1.	marketWidth=3

Voici le lien pour le " view market API " https://live.bullionvault.com/secure/api/v2/view_market_xml.do (vous devez vous connecter pour ce faire). La version non connectée http://live.bullionvault.com/view_market_xml.do est en cache sur le serveur et n’est pas autant actualisée que la version connectée.

Exemple de réponse :

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

Annulation d'un ordre

URL : https://or.bullionvault.fr/secure/cancel_order_xml.do

CGI Paramètre	Description	Exemple
Réf. ordre	La référence de l'ordre devient place_order.	orderId=12345
Confirmé	Pour les robots, cette valeur doit toujours être exacte.	confirmed=true

Passer un ordre

URL : https://or.bullionvault.fr/secure/place_order_xml.do

Paramètre CGI	Description	Exemple
actionIndicator	B ou S pour acheter (or contre devises) ou vendre (or contre devises).	actionIndicator=S
considerationCurrency	Devise d'échange. Doit être soit USD, soit GBP, soit EUR.	considerationCurrency=USD
securityId	Coffre-fort de l'échange commercial. Un de ces coffres : AUXLN (Or Londres), AUXZU (Or Zurich), AUXNY (Or New York), AUXSG (Or Singapour), AUXTN (Or Toronto), AGXZU (Argent Zurich), AGXLN (Argent Londres), AGXSG (Argent Singapour), AGXTN (Argent Toronto) ou laissez vide pour tous.	securityId=AUXZU
quantity	La quantité achetée ou vendue, en kilogrammes. 1.234 représente 1 kilo et 234 grammes. Ne doit pas compter plus que 3 décimales.	quantity=1.234
limit	Prix limité pour l'offre d'achat ou de vente, nombre entier.	limit=13437
typeCode	TIL_CANCEL (Valable jusqu'à annulation), TIL_TIME (Valable jusqu'à date), IMMEDIATE (Exécution immédiate) or FILL_KILL (Exécuter entièrement ou annuler).	typeCode=TIL_TIME
clientTransRef	Votre référence.	clientTransRef=ABC12345
confirmed	Pour les robots, cette valeur doit toujours être exacte.	confirmed=true
goodUntil	Doit être laissé vide à moins que le typeCode soit TIL_TIME. Dans ce cas le format doit être le suivant: 'yyyy-MM-dd%20HH:mm'.	goodUntil=2005-06-02 19:15

Exemple de réponse :

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

Consulter un solde

URL : https://or.bullionvault.fr/secure/view_balance_xml.do

Paramètre CGI	Description	Exemple
simple	Indique le renvoi ou pas d’une réponse simple de solde, ce qui inclut les positions des clients mais sans les informations concernant les règlements en cours. Pour la grande majorité des utilisateurs de robots informatiques, cette information n’est pas nécessaire et ajoute davantage de charge au serveur. Il est fortement conseillé de configurer simple=true .	simple=true

Exemple de réponse :

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

Suivre les ordres

URL : https://or.bullionvault.fr/secure/view_orders_xml.do

Paramètre CGI	Description	Exemple
securityId	Coffre-fort à consulter. Un de ces coffres : AUXLN (Or Londres), AUXZU (Or Zurich), AUXNY (Or New York), AUXSG (Or Singapour), AUXTN (Or Toronto), AGXZU (Argent Zurich), AGXLN (Argent Londres), AGXSG (Argent Singapour), AGXTN (Argent Toronto) ou laissez vide pour tous.	securityId=AUXNY
considerationCurrency	Devise à consulter. Peut être USD, GBP, EUR ou laissez vide pour tous.	considerationCurrency=USD
status	Filtres des ordres. Soit OPEN (montre tous les ordres ouverts), DEALT (montre tous les ordres exécutés), OPEN_DEALT (ordres ouverts + exécutés), CLOSED (ordres fermés), REJECTED (ordres rejetés) ou laissez vide pour tous. Il est vivement recommandé aux programmateurs de robots informatiques de n'utiliser que OPEN ou REJECTED, et de contrôler le statut des autres ordres en utilisantview_single_order. Cela procure un feedback plus rapide à l'utilisateur.	status=OPEN
fromDate	Paramètre optionnel pour filtrer les ordres, renvoyant seulement ceux placés après une date donnée. Si pas fourni, les ordres des trente derniers jours seront affichés.	fromDate=20130921
toDate	Paramètre optionnel pour filtrer les ordres, renvoyant seulement ceux placés avant une date spécifiée.Veuillez noter : la différence maximale entre fromDate et toDate est de 31 jours.	toDate=20130925
page	La réponse pour consulter les ordres est paginée, commençant page zéro. Utilisez ce paramètre pour sélectionner la page.	page=0

Exemple de réponse :

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

Suivre un ordre en particulier

URL : https://or.bullionvault.fr/secure/view_single_order_xml.do

Paramètre CGI	Description	Exemple
orderId	La référence de l'ordre devient place_order.	orderId=1207516

Exemple de réponse :

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

Notes complémentaires

Le champ statusCode pour les réponses aux ordres a les valeurs suivantes :

Valeur	Description
OPEN	Ordre ouvert
DONE	Ordre fermé
EXPIRED	Ordre fermé suite à expiration
CANCELLED	Ordre annulé
KILLED	Ordre annulé car ne pouvait pas être entièrement exécuté
NOFUNDS	Ordre rejeté pour cause de crédit insuffisant
BADLIMIT	Ordre rejeté pour cause de limite trop élevée/basse
SILVER_RESTRICTED	Ce compte ne vous permet pas d'acheter ou de vendre de l'argent-métal.
QUEUED	Ordre en attente d'exécution

Le champ tradeType pour les réponses des ordres a l'une des valeurs suivantes :

Valeur	Description
ORDER_BOARD_TRADE	Ordre placé sur la plate-forme des marchés (ordre standard).
ORDER_AT_FIX	Ordre au Cours du jour (FIX).
CLIENT_ORDER	Ordre sur le marché spot.

Configuration de l’unité de poids

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

Paramètre CGI	Description	Exemple
n/a	n/a	n/a

Exemple de réponse :

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

Actualisation de la configuration de l’unité de poids

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

Paramètre CGI	Description	Exemple
newUnitOfWeight	La préférence de l’unité de poids à configurer pour le compte. KG et TOZ (once troy)	newUnitOfWeight=TOZ

Questions fréquentes

Question : Où puis-je trouver plus d'informations ? Réponse : Votre meilleur source d'information est de copier le client GUI. XML API et le client GUI sont fonctionnellement identiques - la véritable différence réside dans la présentation des données.

Question : Est-il possible d'ajouter un dispositif X ? Réponse : C'est possible même si le développement de XML API n'est pas une priorité actuelle. Vous pouvez nous envoyer vos suggestions par email. xmlapi@BullionVault.com

Question : Les données XML sont-elles actuelles ? Réponse : Aussi actuelle que les données GUI. Elles proviennent généralement de la même source.

Question : Un test public du serveur est-il disponible ? Réponse : Non, mais nous le prendrons en considération en cas de demande suffisante. Veuillez nous envoyer vos suggestions par email. xmlapi@BullionVault.com