package gmocoin

GMOコイン API from OCaml

GMOコイン 暗号資産取引所API のOCaml SDKです。

セットアップ

Private APIを使うには、カレントディレクトリに gmocoin-auth.conf を作成し、1行目にAPIキー、2行目にAPIシークレットを書いてください。

YOUR_API_KEY
YOUR_API_SECRET

open Gmocoin

let () =
  let auth = Auth.auth () in
  Lwt_main.run begin
    PrivateApi.assets auth () >>= fun assets ->
    ...
  end

実装上の注意

• TLSバックエンド: api.coin.z.com はcohttp-lwt-unixの既定TLSバックエンド (ocaml-tls, "native") で接続すると、ハンドシェイク後や応答読み取り中に断続的にECONNRESET/EPIPEで切断されることを確認しています(WAF等によるTLSフィンガープリント判定と見られます)。lib/http.mlでプロセス起動時にCONDUIT_TLS=openssl環境変数を自動設定してOpenSSLバックエンドを強制していますが、これでも完全には解消しないため、Http.get(冪等なGETのみ)は該当エラーを検知すると最大5回まで自動リトライします。POSTは二重注文を避けるため意図的にリトライしません。
• 署名対象パス: GMOコインの署名は /v1/... (/privateを含まない、クエリ文字列も含まない) を対象にHMAC-SHA256で計算します。実際のリクエストURLには/privateを付与しますが、署名にはそのまま使わないようApiCommon内で分離しています。
• レスポンスエンベロープ: 全レスポンスは {"status": 0, "data": ..., "responsetime": "..."} という共通形式です。statusが0以外の場合、型付きの{status: int; messages: {message_code; message_string} list}を積んだApiCommon.Api_errorを投げます。ただしPublicApi.statusだけは例外にせず(string, ApiCommon.api_error) result Lwt.tを返します(取引所稼働状況の確認自体がメンテナンス中に例外で失敗するのは本末転倒なため)。
• 数値の文字列表現: price/sizeなど大半の数値フィールドはJSON上で文字列 ("455659") として返されるため、型定義でもstringとしています。呼び出し側で必要に応じてfloat_of_string等に変換してください。

テスト

dune test

test/test_gmocoin.mlにJSONパース(公式ドキュメントのレスポンス例をそのまま使用、MARKET注文でpriceが欠落するケースやCANCELED注文でcancelTypeが付くケースなどoptionフィールドの境界も含む)とRateLimiterのスライディングウィンドウ挙動を検証する単体テスト(alcotest)があります。ネットワークアクセスは行いません。

レートリミッター

API制限に基づき、ApiCommonがPrivate APIの全リクエストに自動で流量制限をかけます(RateLimiterモジュール、スライディングウィンドウ方式)。上限に達した場合は例外を投げずに、枠が空くまで自動的に待機してから送信します。

Public WebSocket / Private WebSocketの「subscribe/unsubscribeは1秒間1回まで」という制限には未対応です(Public WebSocket APIは実装済みですが、同一接続内で複数チャンネルを連続購読する際の間隔調整はまだ入れていません)。

API実装状況

Public API

ベースURL: https://api.coin.z.com/public

Public WebSocket API

エンドポイント: wss://api.coin.z.com/ws/public/v1(概要ページの記載は/ws/publicだが、実際のサンプルコードは全て/v1付き)

Realtime.updates ~symbol channelsで指定した銘柄・チャンネルをまとめて購読し、update Lwt_stream.t(Ticker | Orderbook | Tradeのバリアント)として受信できます。板情報だけのように単一チャンネルしか使わないことが多いため、パターンマッチ不要でその型のストリームを直接返す専用関数も用意しています: Realtime.ticker_updates / Realtime.orderbook_updates / Realtime.trade_updates(内部的にはupdatesを1チャンネルだけで呼んでいるだけ)。bin/main.mlのwatch_and_buyはRealtime.orderbook_updatesを使い、板情報のbest_bidが閾値以下になるたびにPrivateApi.orderで成行の現物買い注文を出すサンプル実装です。

実装時に分かった注意点:

• tickerチャンネルは値動きがないと配信されないことを確認しました(25秒待っても何も届かないケースあり)。常にスナップショットが届くorderbooksチャンネルの方が、bid/ask監視には適しています。
• 板情報のレスポンスには、ドキュメントに記載のないgroupingフィールドが実際には含まれていました(Realtime.orderbookではstring optionとして吸収)。
• 接続はPrivate APIのHTTPと同様、既定のTLSバックエンドだと不安定なため、`OpenSSLクライアントを明示的に指定しています。
• サーバーから1分に1回pingが送られ、pongを返さないと切断されます。Realtime.updates内で自動的に応答します。

Private API

ベースURL: https://api.coin.z.com/private。すべて認証が必要です。

Private WebSocket API

エンドポイント: wss://api.coin.z.com/ws/private/v1/<token>(tokenはPrivateApi.ws_auth_postで取得)

公開チャンネル用のupdatesと違い、private_updatesは接続が切れても内部で自動再接続はしない(アクセストークンが期限切れ(60分)で無効になっている可能性があり、その場合は再接続してもトークンを取り直さない限り無意味なため)。切断時はストリームの読み出しが例外で終わるので、呼び出し側で新しいトークンを取得してから呼び直すこと。