よくある質問/概要/ステップ・バイ・ステップ・ガイド

BullionVaultにおけるXML API

概念

BullionVaultシステムへは二つのインターフェイスがあります。ユーザーが利用する通常のGUIインターフェイスとトレーディングボットが利用するXMLインターフェイスです。XMLインターフェイスは、BullionVaultの主なサポートとは考慮されていませんが、トレーディングボットを構築する際に、これを利用することで、その開発を簡素化することができます。
この書類は、XMLインターフェイスを説明し、ボット構築者に十分な情報を提供します。しかし、これは広範囲にわたるガイドではなく、取引ストラテジィーを説明するものでもありません。

対象

この書類は、プログラマーを対象として作成されています。特に、この書類の読者は、XMLのファイルフォーマットはもちろんのこと、CGIとHTTPのリクエストーレスポンス型のプロトコルを熟知している必要があります。

免責条項

XMLインターフェイスは、保証及びサポートを含まずに提供されます。BullionVaultは、このインターフェイスを利用しています。そのために、これが正確で安定したものであることが重要です。しかしながら、BullionVaultは、このインターフェイスが安定していること、もしくは、これが提供する情報が正確であることを保証するものではありません。

トレーディングにおいては、経済的な損失は起こりうるものです。自動的なトレーディングには、情報の正確さ、接続の信頼度、システムレスポンスのスピードなどによる、多くの追加リスクが伴います。XML APIを利用する際、経済損失に限定されない、これらのリスクを受け入れなければなりません。

BullionVaultは、ボットがシステムを必要以上に使用する場合、その使用料を請求、もしくは使用を停止する権利を保持します。

概要

BullionVaultのAPIは、通常のGUIサイトと同様な型式で作動します。CGIパラメーターが、提出され、その返答がサーバーから送信されます。ここでの違いは、その返答は、HTMLでははく、XMLで行われるということです。そのため、熟練したプログラマーにとっては、システムとインターフェイスを行い、オンラインで取引を行うのは、比較的容易であるはずです。取引のために必要となる全てのGUIページ(マーケットページ等)は、同様なXMLがあります。取引に必要としない補足的ページ(口座明細、口座設定ページ等)は、同様なXMLはありません。そのため、手動で行わなければなりません。

セキュリティー

BullionVaultは、通常のユーザーネームとパスワードに加え、選択可能な忘れがたい情報といった、拡張されたログインプロトコルを使用します。あらゆる機密であるべき情報の連絡は、この接続を通して行われます。マーケットのような一般に公開されている情報へのアクセスは、HTTP接続を利用します。ログインセッション(JSESSIONID)をモニターするために、弊社ウェブサーバーは、セッションHTTP cookieを利用することを覚えておいてください。ボットは、通常のブラウザーと同様にこのHTTP cookieを扱わなければなりません。そうでなければ、ログイン詳細情報は忘れられます。

HTTPSクライアント認証を使用し、情報が守られたページへのアクセスすることを求めると、ユーザーもしくはボットへは、一時的にユーザーネームとパスワードを入力する下記のページが表示されます

https://live.bullionvault.com/secure/login.do

このスクリーンのCGIパラメータであるj_username j_passwordが提出されるべきです。

https://live.bullionvault.com/secure/j_security_check?j_username=XXX&j_password=YYY
これが滞りなく行われると、ユーザーはログインするか、忘れがたい情報が設定されている場合は、この情報を入力するページが表示されます。

忘れがたい情報入力画面と同様なEMLはありません。この入力ページの処理を簡易化するために、ボットはhtmlの上段に表示される下記のメタタグを確認します。

<meta name="X-Challenge" CONTENT="0,2,5"/>
3つの文字もしくは記号がサーバーへ正しく提出される必要があります。その内容の特性が、これらの文字もしくは記号の位置を与えます。そのため、先の例においては、ボットが一番目、3番目と6番目の忘れがたい情報の文字もしくは記号をresponse[0]、response[2]、response[5]と提出しなければなりません。
例えば、忘れがたい情報が「ABCDEFGHI]であった場合、正しい答えは下記のようになります。
https://live.bullionvault.com/secure/second_login.do?response[0]=A&response[1]=C&response[2]=F

ログインが正しく行われた後、ユーザーは情報が守られたページへアクセスすることが可能となります。

XML API リクエスト

XML APIは、下記の6つのサービスを提供します。

  • マーケットを確認
  • 注文を提出
  • 注文を取消す
  • 残高を確認
  • 注文を確認
  • 一つの注文のみを確認
これらのインターフェイスは下記に表示します。

マーケットを確認

URL: http://live.bullionvault.com/view_market_xml.do
CGIパラメーター 詳細説明
considerationCurrency 通貨を定義。USD、GBP、EUR、もしくは全てのために空欄。 considerationCurrency=USD
securityId 保管場所を定義。AUXLN (London)、AUXZU (Zurich)、AUXNY (New York)、もしくは全てのために空欄。 securityId=AUXLN
quantity 最少量を定義。0.005と規定されると、5グラム以下の全ての買い、売り注文は取り除かれます。全ての買い及び売り注文を見るためには、0.001と設定。 quantity=0.001
marketWidth それぞれの市場へ提出できる買い及び売り注文の最大数。デフォルトは1。 marketWidth=3

市場閲覧のためのAPIは、https://live.bullionvault.com/secure/api/v2/view_market_xml.do でログイン後にアクセスできることをご注意ください。 ログインを必要としないバージョン(http://live.bullionvault.com/view_market_xml.do)は、サーバー上でキャッシュされていますが、ログインを必要とするバージョンのように更新されていません。 is cached on the server and is not as up-to-date as the logged in version.

返答例

	<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://live.bullionvault.com/secure/cancel_order_xml.do
CGIパラメーター 詳細説明
orderId place_orderによって、そのorder IDは表示されます。 orderId=12345
confirmed ボットにとって、値は常にtrueでなければなりません。 confirmed=true

注文の提出

URL: https://live.bullionvault.com/secure/place_order_xml.do
CGIパラメーター 詳細説明
actionIndicator (通貨で金を)購入もしくは(通貨のために金を)売却のために、BもしくはS。 actionIndicator=S
considerationCurrency 取引を行うための通貨を定義。USD、GBP、EURの一つでなければなりません。 considerationCurrency=USD
securityId 取引を行う保管場所を定義。AUXLN (London)、AUXZU (Zurich)、AUXNY (New York)の一つでなければなりません。 securityId=AUXZU
quantity キログラムで表示される取引量。1.234は、1キログラム234グラムを表す。3小数点以上でなければなりません。 quantity=1.234
limit 整数で表示される買い及び売り注文の限度。 limit=13437
typeCode TIL_CANCEL(限定期間なし)、TIL_TIME(年月日まで)、IMMEDIATE(即座に取引)もしくは、FILL_KILL(全てを取引または全て取消)の一つでなければなりません。 typeCode=TIL_TIME
clientTransRef 参照コード。この口座に独特のものである必要があります。 clientTransRef=ABC12345
confirmed ボットにとっては、この数値は常にtrueでなければなりません。 confirmed=true
goodUntil TIL_TIMEでない限りは空欄。TIL_TIMEである場合は、「yyyy-MM-dd%20HH:mm」で表示されなければなりません。 goodUntil=2005-06-02 19:15

返答の例

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

残高の確認

URL: https://live.bullionvault.com/secure/view_balance_xml.do
CGIパラメーター 詳細説明
simple 簡易的な残高を返答するかを指定。これは、顧客のポジションを含むものの、決済待ち取引の情報は含まない。大部分のボットのユーザーは、この情報は必要せず、これは、サーバーの負荷を高めるために、これを強く
simple=true
とすることを推奨。
simple=true

返答例

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

注文確認

URL: https://live.bullionvault.com/secure/view_orders_xml.do
CGIパラメーター 詳細説明
securityId 保管場所を定義。AUXLN (London)、AUXZU (Zurich)、AUXNY (New York)の一つ、もしくは全ての注文を見るために空欄。 securityId=AUXNY
considerationCurrency 通貨を定義。USD、GBP、EURの一つ、もしくは全ての注文を見るために空欄。 considerationCurrency=USD
status 注文のリストを注文の状態に応じてふるいにかける。OPEN(全ての未成立の注文)、DEALT(全ての成立した注文)、OPEN_DEALT(未成立と成立した注文)、CLOSED(未完了の注文)、REJECTED(システムが受領しなかった注文)の一つ、もしくは全ての注文を見るために空欄。ボットを最大限利用するために、注文状態ととしてOPENを選択することをボット作成者へ強く勧めます。他の注文は、 view_single_order messageを利用して確認すべきです。 status=OPEN
fromDate 注文をフィルターにかけるためのオプショナルなパラメーター。与えられた日数以前に出した注文を見るためのもの。 もし、これが指定されない場合は、デフォルトで30日前までと設定。. fromDate=20130921
toDate 注文をフィルターにかけるためのオプショナルのパラメーター。与えられた日より前に出した注文を見るためのもの。 注:fromDateとtoDateの最大の日数差は31日。 toDate=20130925
page 注文確認の返答にページ数がつけられています。ここにおける最初のページは0です。このパラメーターを利用して、ページの選択をします。 page=0

返答例

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

単独注文を確認

URL: https://live.bullionvault.com/secure/view_single_order_xml.do
CGIパラメーター 詳細説明
orderId place_orderによって、そのorder IDは表示されます。 orderId=1207516

返答例

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

追加事項

注文の返答に関するstatusCodeの欄には、下記の値の一つが表示されているはずです。

詳細説明
OPEN 注文は未成立です。
DONE 注文は処理されました。
EXPIRED 注文は期限が切れました。
CANCELLED 注文は取消されました。
KILLED 注文は、全て成立しなかったために、取消されました。
NOFUNDS 注文は、十分な資金がなかったために受領されませんでした。
BADLIMIT 注文は、限度額が高すぎるか、低すぎたため受領されませんでした。
SILVER_RESTRICTED この口座では、銀は取引できません。
QUEUED 注文は、処理されるのを待っています。

よくある質問

Q. さらに詳細情報はどこで得られますか?
A. その最も良い情報元としては、Client GUIを見るべきです。XML APIとClient GUIは機能的には同じものです。ここでの違いは、データがどのように表示されているかです。
Firefoxを利用している場合は、その情報の流れを理解する上で、Firebugは役立ちます。

Q. feature Xを追加することはできますか?
A. できますが、XML APIの開発には、高い優先順位はつけられていません。提案がある場合は、xmlapi@BullionVault.comまでEメールでご連絡ください。。

Q. XMLデータは、どのくらい新しいものですか?
A. GUIデータと同様です。これらのデータは、同じ情報源から作成されています。表示方法のみが異なるのです。

Q. 一般が利用できるテストサーバーは、ありますか?
A. ありません。しかし、需要があるようでしたら、考慮します。提案がある場合は、xmlapi@BullionVault.comまで、Eメールでご連絡ください。


© BullionVault Ltd