L'XML API di BullionVault

Sommario

Il sistema di BullionVault dispone di due interfacce: la normale interfaccia utente (GUI) per tutti gli utenti e l'interfaccia XML per i trading robots. Mentre l'interfaccia XML non è considerata quella primaria del servizio di BullionVault, essa può essere utilizzata per semplificare notevolmente lo sviluppo dei trading robots. Il presente documento descrive il funzionamento dell'interfaccia XML sia per l'esperto di informatica che per chi non è esperto. Esso non vuole essere né una guida esaustiva né dare informazioni di alcun genere sulle strategie di compravendita.

A chi è indirizzato questo documento

Questo documento è indirizzato a programmatori informatici, in particolare a chi conosce il linguaggio CGI, il procotollo request/response in HTTP e i file in formato XML.

Dichiarazione di non responsabilità

L'interfaccia XML viene fornita come disponibile, senza garanzia né supporto. Questa è l'interfaccia di BullionVault, che è stata testata per garantire l'accuratezza e la stabilità della stessa. Tuttavia BullionVault non garantisce la totale stabilità dell'interfaccia o l'accuratezza delle informazioni fornite.

Le compravendite includono il rischio di perdite finanziarie. Le compravendite automatiche includono diversi altri tipi di rischi compresa l'accuratezza delle informazioni, l'affidabilità delle connessioni, la velocità di risposta del sistema, ecc. Tramite l'utilizzo dell'XML API l'utente accetta tutti i rischi coinvolti, compresi ma non limitati ai rischi di perdita finanziaria per qualsiasi motivo.

BullionVault si riserva il diritto di modificare o sospendere dall'attività clienti i cui robot violano il Termini di utilizzo — Ad esempio, utilizzando risorse di sistema eccessive. Si prega di effettuare il polling del sistema entro limiti ragionevoli

Introduzione

Gli API di BullionVault operano in maniera simile al normale sito con da GUI. I parametri CGI vengono forniti e la risposta viene inviata di ritorno dal server. La differenza fondamentale è che la risposta è in formato XML anziché HTML. Dovrebbe essere quindi relativamente facile per un programmatore esperto impostare l'interfaccia con il sistema e compravendere online. Tutte le pagine GUI necessarie per le compravendite (ad es. le pagine dei mercati) hanno elementi equivalenti in XML. La maggior parte delle pagine ausiliarie che non servono per le compravendite (ad es. gli estratti conto e le impostazioni del conto) non hanno un equivalente XML e devono essere utilizzate manualmente.

La sicurezza

BullionVault utilizza un protocollo di accesso avanzato che comprende un normale nome utente e la password di accesso assieme ad un altro controllo tramite la domanda di sicurezza, un controllo opzionale ma raccomandato. Tutte le comunicazioni private verranno effettuate tramite questa connessione sicura. Le informazioni disponibili pubblicamente, come ad esempio le pagine dei mercati, possono essere visualizzate tramite la connessione non sicura HTTP. I web server di BullionVault utilizzano un cookie per le sessioni per rintracciare tutte le sessioni di accesso (JSESSIONID). I robot dei clienti devono trattare i cookies in maniera simile ai normali browser, altrimenti l'accesso viene dimenticato.

La prima volta che viene richiesta la pagina sicura tramite un HTTPS client, l'utente o il robot viene convogliato temporaneamente alla pagine del nome utente / della password su:

https://oro.bullionvault.it/secure/login.do

Il CGI parameters j_username j_password di questa pagina deve essere inviata a:

https://oro.bullionvault.it/secure/j_security_check?j_username=XXX&j_password=YYY

Se l'accesso viene eseguito correttamente, l'utente entra nel suo conto oppure viene visualizzata la pagina per il controllo della domanda di sicurezza.

Non vi è nessun equivalente di XML per la pagina della domanda di sicurezza. Per facilitare l'esecuzione di questo controllo per i robot, è stato inserito il seguente META tag nella sezione in alto dell'HTML:

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

I tre caratteri devono essere inviati correttamente al server. L'attributo del contenuto indica la posizione di questi caratteri in ordine crescente. Nell'esempio precedente, ad esempio, il robot deve inserire prima il primo, poi il terzo e infine il sesto carattere della domanda di sicurezza, ovvero response[0], response[1] and response[2]. Se la domanda di sicurezza è 'ABCDEFGHI', deve essere immesso quanto segue:

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

Dopo aver effettuato l'accesso l'utente può navigare a tutte le pagine.

Le richieste XML API

L'XML API al momento offre 6 servizi:

Visualizzare i mercati
Immettere un ordine
Annullare un ordine
Visualizzare i saldi
Visualizzare gli ordini
Visualizzare i singoli ordini

L'interfaccia di queste pagine viene descritta in seguito.

Visualizzare il mercato

URL: https://Oro.bullionvault.it/view_market_xml.do

Parametro CGI	Descrizione	Esempio
considerationCurrency	La valuta da visualizzare. USD, GBP, EUR oppure niente.	considerationCurrency=USD
securityId	La camera blindata da visualizzare. AUXLN (Londra), AUXZU (Zurigo), AUXNY (New York) oppure niente	securityId=AUXLN
quantity	La quantità minima da visualizzare. Il valore 0.005 filtra tutte le offerte inferiori ai 5 grammi. Immettere 0.001 per visualizzare tutte le offerte*.	quantity=0.001
marketWidth	Il numero massimo delle offerte per ciascun mercato. Il valore di default è 1.	marketWidth=3

Si noti che l'accesso alla schermata aggiornata dell'API dovrebbe effettuarsi tramite il seguente link https://live.bullionvault.com/secure/api/v2/view_market_xml.do (ad accesso effettuato). La versione accessibile agli utenti non registrati, disponibile al seguente link (http://live.bullionvault.com/view_market_xml.do), potrebbe non essere aggiornata come la precedente.

Risposta esemplificativa.

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

Annullare un ordine

URL: https://oro.bullionvault.it/secure/cancel_order_xml.do

Parametro CGI	Descrizione	Esempio
orderId	L'ID dell'ordine restituito da place_order.	orderId=12345
confirmed	Per i robot questo valore deve essere sempre true.	confirmed=true

Immettere un ordine

URL: https://oro.bullionvault.it/secure/place_order_xml.do

Parametro CGI	Descrizione	Esempio
actionIndicator	B oppure S per comprare (buy - oro con denaro) o vendere (sell - oro per denaro)	actionIndicator=S
considerationCurrency	La valuta da utilizzare. USD, GBP oppure EUR.	considerationCurrency=USD
securityId	La camera blindata da utilizzare. Scegliendo tra AUXLN (Oro Londra), AUXZU (Oro Zurigo), AUXNY (Oro New York), AUXSG (Oro Singapore), AUXTN (Oro Toronto), AGXZU (Argento Zurigo), AGXLN (Argento Londra), AGXSG (Argento Singapore), AGXTN (Argento Toronto) oppure lasciando il campo in bianco	securityId=AUXZU
quantity	La quantità da trattare, in chili. 1.234 rappresenta 1 chilo e 234 grammi. Non può avere più di tre decimali.	quantity=1.234
limit	Il prezzo limite per l'offerta, come numero intero.	limit=13437
typeCode	TIL_CANCEL (Valido finché annullato), TIL_TIME (Valido fino a ora), IMMEDIATE (Esegui subito) oppure FILL_KILL (Tutto o niente).	typeCode=TIL_TIME
clientTransRef	Il codice di riferimento.	clientTransRef=ABC12345
confirmed	Per i robot questo valore deve essere sempre true.	confirmed=true
goodUntil	Deve essere vuoto a meno che il typeCode non sia TIL_TIME, caso in cui esso deve essere una data ed ora nel formato 'yyyy-MM-dd%20HH:mm'.	goodUntil=2005-06-02 19:15

Risposta esemplificativa.

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

Visualizzare i saldi

URL: https://oro.bullionvault.it/secure/view_balance_xml.do

Parametro CGI	Descrizione	Esempio
simple	Specificare se ritornare al semplice responso relativo al saldo, insieme alla situazione del cliente senza alcuna informazione relativa agli ordini pendenti. Per la stragrande maggioranza degli utenti che usano i robot quest'informazione addizionale non è richiesta e comporta un carico supplementare sui nostri server. E' vivamenteraccomandabile andare oltre. simple=true .	simple=true

Risposta esemplificativa.

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

Visualizzare gli ordini

URL: https://oro.bullionvault.it/secure/view_orders_xml.do

Parametro CGI	Descrizione	Esempio
securityId	La camera blindata da visualizzare. AUXLN (Londra), AUXZU (Zurigo), AUXNY (New York) oppure niente	securityId=AUXNY
considerationCurrency	La valuta da visualizzare. USD, GBP, EUR oppure niente.	considerationCurrency=USD
status	Filtra l'elenco degli ordini restituiti. OPEN (visualizza tutti gli ordini aperti), DEALT (visualizza tutti gli ordini eseguiti), OPEN_DEALT (visualizza tutti gli ordini aperti e quelli eseguiti), CLOSED (visualizza tutti gli ordini chiusi), REJECTED (visualizza tutti gli oridni respinti) oppure vuoto per tutti. Si consiglia vivamente agli sviluppatori di robot di utilizzare solo OPEN oppure REJECTED e di monitorare lo stato degli altri ordini tramite view_single_order. In questo modo il feedback è più veloce.	status=OPEN
fromDate	Paramentro opzionale che consente di filtrare gli ordini, mostrando solo quelli predisposti dopo una certa data. Se non specificato, sarà impostato ai 30 giorni precedenti.	fromDate=20130921
toDate	Parametro opzionale che consente di filtrare gli ordini, mostrando solo quelli predisposti prima di una certa data. Nota bene: La differenza massima tra fromDate and toDate è di 31 giorni.	toDate=20130925
page	La risposta per visualizzare gli ordini è impaginata partendo dalla pagina 0. Utilizzare questo parametro per selezionare la pagina.	page=0

Risposta esemplificativa.

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

Visualizzare i singoli ordini

URL: https://oro.bullionvault.it/secure/view_single_order_xml.do

Parametro CGI	Descrizione	Esempio
orderId	L'ID dell'ordine restituito da place_order.	orderId=1207516

Risposta esemplificativa.

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

Note aggiuntive

Il campo statusCode per le risposte degli ordini presenta uno dei seguenti valori:

Valore	Descrizione
OPEN	L'ordine è aperto
DONE	L'ordine è chiuso
EXPIRED	L'ordine è chiuso perché scaduto
CANCELLED	L'ordine è stato annullato
KILLED	L'ordine è stato annullato perché non è stato possibile corrisponderlo
NOFUNDS	L'ordine è stato rifiutato perché i fondi sono insufficienti
BADLIMIT	L'ordine è stato annullato perché il limite del prezzo era troppo alto / basso
SILVER_RESTRICTED	L'acquisto d'argento non è permesso su questo conto
QUEUED	L'ordine è stato accodato ed è in attesa di essere corrisposto

Visualizzare l'unità di peso

URL: https://oro.bullionvault.it/secure/api/v2/view_weight_unit_xml.do

Parametro CGI	Descrizione	Esempio
n/a	n/a	n/a

Risposta esemplificativa:

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

Aggiornare l'unità di peso

URL: https://oro.bullionvault.it/secure/api/v2/update_weight_unit_xml.do

Parametro CGI	Descrizione	Esempio
newUnitOfWeight	Impostazione dell'unità di peso preferita per il conto. Uno tra KG e TOZ	newUnitOfWeight=TOZ

Domande frequenti

D Dove trovo più informazioni?R. La fonte di informazioni migliore è tracciare la client GUI. L'XML API e la client GUI funzionano allo stesso modo. La differenza fondamentale è il modo di visualizzazione dei dati.

D. Posso aggiungere altri elementi?R. Si, ma lo sviluppo dell'XML API al momento non è una delle priorità di BullionVault. Per inviare suggerimenti utilizzare questo indirizzo: xmlapi@BullionVault.com.

D. Quanto sono attuali i dati XML?R. Tanto quanto i dati della GUI. Entrambi sono generati dalla stessa fonte.

D. Esiste un server pubblico per testare?R. No, ma se sussiste una domanda rilevante possiamo prenderlo in considerazione. Per inviare suggerimenti utilizzare questo indirizzo: xmlapi@BullionVault.com.

D. *E il formato dei separatori decimali?R. *Nelle stringhe in XML API i separatori decimali devono sempre rispettare la codifica inglese, ovvero il punto (".") per come separatore decimale e la virgola (",") come separatore delle migliaia.