概要#

Catapult API は、合成トークンのデリバティブ・プラットフォーム（取引とトークンデータ）を、リクエスト/レスポンス操作のための単一の GraphQL エンドポイントと、リアルタイムのサブスクリプションのための WebSocket エンドポイントを通じて提供します。

ベースエンドポイント#

すべての HTTP リクエストは POST を使用し、{ "query": "...", "variables": { ... } } という形の JSON ボディを送ります。

認証#

認証が必要な操作は、Authorization ヘッダーで送る JWT ベアラートークン を使用します:

Authorization: Bearer <your-jwt-token>

トークンは JSON Web Token (JWT) で、デフォルトでは発行から 730 日（約 2 年） 有効です。 期限切れ前にローテーションしてください。公開されているのは ping のみで、他のすべての操作には ベアラートークンが必要 です。さらに tokens や turboToken などの読み取りには tokens.read 権限が必要です。

API キーの作成#

catapult.trade/settings/api-key（Settings → API Key）のアカウントダッシュボードからトークンを生成します。アカウントは catapult.trade で管理できます。

規約#

• ID は不透明な文字列です。パースしないでください。
• 金額は String! 型の 文字列エンコードされた整数 です（例: balanceUsdtDrops）。 float ではなく BigInt としてパースしてください。カスタムスカラーは DateTime のみです。
• タイムスタンプは DateTime スカラー（ISO-8601、UTC）を使用します。
• リストクエリは input.pagination によるカーソルページネーションです: limit（デフォルト 10）と afterCursor / beforeCursor。

クイック例#

query Tokens {
  # PublicTokenListInput とトークンのフィールドの詳細は Reference タブを参照
  tokens(input: { pagination: { limit: 5 } }) {
    items { id }
  }
}

API キー OAuth#

このリンクを使うと、コピートレードなどの機能を構築するためにユーザーの API キーを取得できます。ユーザーが自分の API キーに権限を付与すると、その API キーはあなたのホワイトリスト登録済みコールバック URL に渡されます。

https://catapult.trade/settings/api-key?bot_id=<WHITELISTED_BOT_ID>

<WHITELISTED_BOT_ID> を、ホワイトリストに登録済みのボットの ID に置き換えてください。

ボットのホワイトリスト登録#

当社の開発チームに連絡してボットをホワイトリストに登録してください:

[email protected]

単位と規約#

最初にお読みください。API のすべての金額フィールドはこれらの規約に依存します。

USDT drops (*UsdtDrops)#

すべての USDT 金額は USDT × 1,000,000（小数 6 桁）の整数で、UsdtDrops という接尾辞が 付きます。これらは String!（文字列エンコードされた整数）として送信されます。float ではなく BigInt としてパースしてください。

変換: usdt = drops / 1e6、drops = round(usdt × 1e6) — BigInt で計算します。

レバレッジ (leverageX10)#

レバレッジは レバレッジ × 10 として符号化されます。leverageX10: 125 は 12.5×、 30 は 3× を意味します。

証拠金と想定元本#

notional = collateral × leverage。差し入れる額が 証拠金 (collateral)、ポジションの USDT 額面が 想定元本 (notional) です。

ポジションを開くときの額は 手数料控除前の証拠金 です。tradeOpen は usdtDrops （USDT 建て）または amountWei（トークン建て）の ちょうど 1 つ を取り、エンジンが それとレバレッジから想定元本を導出します。これは想定元本では ありません。

残高#

userBalance { balanceUsdtDrops, inPositionsBalanceUsdtDrops }:

トークンのメディア (fileId)#

トークン画像は fileId を tokenCreate に渡して添付します。取得方法は 2 つあります:

1. ランダマイザー — tokenRandomizedPreset がそのまま使える fileId（名前・シンボル・ モードなども）を返し、tokenCreate にそのまま渡せます。
2. 独自アップロード — 3 ステップの S3 presigned-POST フロー:
   • fileUpload(input) → S3 presigned-POST URL と、クライアントが multipart POST に 含める必要のあるフォームフィールドを返します。
   • クライアントはそのフォームフィールドを付けて、その S3 URL に画像を POST します。
   • fileFinalize(id) → S3 POST 成功後にアップロード完了を記録し、公開ファイル URL を返します。 得られたファイルをトークン画像として使用します。

アップロード制限: JPEG または PNG のみ、最大 5 MB、最小 314×314 px。presigned POST は fileUpload 呼び出しから 15 秒以内に完了する必要があり、アップロードは IP あたり 1 時間 200 回 に制限されます。

トークンのスピードモード#

すべてのトークンは 5 つの スピードモード のいずれかで動作します。作成/ランダム化の フィールドは turboTokenMode、トークンレコードは speedMode を公開します。SLOW と NORMAL は同じモードの 2 つの呼び名です。

以下の最大レバレッジとライフタイムの値は、サーバー側で変わり得る 現在の設定 です。 現在値として扱い、ライブの leverage-config クエリで確認してください。

最大レバレッジはエンジンの固定上限#

各モードの最大レバレッジはエンジンが適用する厳格な上限です。表の値を直接使用してください。 それを超える注文はエンジンが拒否します。

手数料とポジションサイズ#

開設手数料（〜1%）#

ポジションを開くと 約 1% の開設手数料（0.01）が、送付する 証拠金から差し引かれます:

collateral_post_fee = collateral_sent × (1 − fee)

ロックされる証拠金をちょうど notional / leverage にするには、次を送付します:

collateral_sent = (notional / leverage) / (1 − fee)

ポジションごとの想定元本上限#

サーバー側で ポジションごとの想定元本上限 が適用されます。現在は (トークン, レバレッジ, サイド) ごとに 20,000 USDT です。超過すると Maximum notional limit … exceeded が返ります。正確な値はライブ設定で確認してください。モードやレバレッジによって異なる場合が あります。

利用可能な最大ポジション（想定元本）#

fee = 0.01、free = balanceUsdtDrops / 1e6、 inPos = inPositionsBalanceUsdtDrops / 1e6、capTotal = 任意の自前の総証拠金上限、 capPos = ポジションごとの想定元本上限（〜20,000）、L = レバレッジ とすると:

maxCollateralFromBalance = free × (1 − fee)
remainingTotalBudget     = capTotal − inPos          # 総上限を適用する場合
maxNewCollateral         = min(maxCollateralFromBalance, remainingTotalBudget)
maxNotionalAchievable    = maxNewCollateral × L
maxPositionNotional      = min(maxNotionalAchievable, capPos)

実際に送付する証拠金 = (maxPositionNotional / L) / (1 − fee)。

丸めの落とし穴。 (1 − fee) で割った後、素朴な round(collateral × 1e6) は上限を 数 drops 超過し、開設が拒否されます。送付前に証拠金を drops（BigInt）で小さな刻み （例: 10 drops = 0.00001 USDT）に 切り捨て ます。失うのはごくわずかなセント未満で、 どのレバレッジでも上限内に収まります。

計算例#

FLASH、3×、手数料 1%、想定元本上限 20,000:

collateral_post_fee target = 20,000 / 3        = 6,666.67
collateral_sent            = 6,666.67 / 0.99 ≈ 6,734.01   (drops で切り捨て)
→ 手数料控除後のロック ≈ 6,666.67、想定元本 ≈ 20,000

ステータスコード#

GraphQL のレスポンスは、操作が失敗しても HTTP 200 を返します。errors[] 配列と各エラーの extensions.code を確認してください。トランスポートレベルの問題には標準の HTTP ステータス コードを使用します。

HTTP ステータスコード#

GraphQL サービスは、認証・権限・レート制限の失敗をレスポンス内で 200 として返します （GraphQL エラーコードを参照）。トランスポートレベルの 401 / 403 / 429 は、上流の ゲートウェイ/CDN が API 到達前にリクエストを拒否した場合にのみ発生します。

GraphQL エラーコード#

コードは大文字小文字を区別します。完全一致で照合してください。ドメインコードは PascalCase （例: RateLimited）、一部のフレームワークコードは大文字スネークケース（例: UNAUTHENTICATED）です。

エラーの形式#

{
  "errors": [
    { "message": "Token not found", "extensions": { "code": "NotFound" } }
  ],
  "data": null
}

レート制限#

GraphQL 操作は、API トークン（jti）と IP ごとに 1 つのレート制限バケットを共有します: クエリ 600 回/分、ミューテーション 60 回/分。制限を超えると、 errors[] に extensions.code = RateLimited のエラーを 1 件含む HTTP 200 レスポンスが 返ります。API は 429 ステータスや Retry-After ヘッダーを返しません。リトライのタイミングの ヒントはエラーの extensions に含まれます。

HTTP（GraphQL）の制限#

WebSocket の制限#

WebSocket の制限はサーバー側で設定可能なため、本番ではこれらのデフォルトと異なる場合が あります。制限は IP 単位ではなく 接続単位 で適用されます。

レスポンスヘッダー#

API はレート制限ヘッダー（X-RateLimit-*、Retry-After）を返しません。上流のゲートウェイが 付加する場合がありますが、依存しないでください。

落とし穴と冪等性#

インテグレーターが最も間違えやすい点のチェックリスト。

金額とサイズ#

• drops は整数 — 端から端まで BigInt。*UsdtDrops を float でパースしないでください。
• 送付する開設額（usdtDrops または amountWei）は 手数料控除前の証拠金 であり、 想定元本ではありません。
• 想定元本上限 は drops で適用されます。数 drops の超過を避けるため証拠金を 切り捨て ます（「手数料とポジションサイズ」参照）。
• 最大レバレッジはモードごとのエンジン固定上限 です（「トークンのスピードモード」参照）。 直接使用してください。

トークン#

• ランダマイザーは ランダムな rank（Competition | Private | Public）を返します。 トークンをリスト/コピー取引可能にする必要がある場合は Public を強制してください。
• tokenCreate は 常に残高ベースの支払い を使用します。支払いタイプは上書きできません。
• tokens にサーバー側の「アクティブ」フラグはありません。クライアント側で endDate で フィルタしてください。

開設と決済#

• tradeOpen は usdtDrops（USDT 建て）または amountWei（トークン建て）の ちょうど 1 つ を必要とします。両方も、どちらもなしも不可。
• tradeClose は USER_SELL で開いているポジションを決済します。

テイクプロフィット / ストップロス (tradeLimit*)#

• tradeLimitCreate は 少なくとも 1 つのトリガー（SL または TP）を必要とします。
• update では、あるサイドに明示的な null を渡すとそれが クリア され、省略 したフィールドは 保持 されます。
• tradeLimitUpdate は すべて null の入力を拒否 します（Validation failed: input=MissingValue）。 クリアするには tradeLimitDelete を使用してください。
• サイドごとの削除はありません。tradeLimitDelete は TP と SL の 両方 を削除します。

サブスクリプション (WebSocket)#

• connection_init で payload: { Authorization: "Bearer <apiKey>" } により認証します。
• positions サブスクリプションは PublicPositionEvent ユニオン を配信します — PublicPositionOpenedEvent | PublicPositionClosedEvent | PublicPositionUpdatedEvent。 イベント固有のフィールドを読む前に type フィールドで判別してください。
• PublicPositionClosedEvent は positionId, tokenId, type, closeType, closedAt, closePriceUsdtDrops, receivedAmountUsdtDrops, pnlUsdtDrops を持ちます。buyPriceUsdtDrops, collateralUsdtDrops, notionalUsdtDrops, leverageX10 は決済イベントではなく PublicPositionOpenedEvent のフィールドです。
• 決済イベントは at-least-once で、再配信されません。 再接続中に発行された決済は新しい サブスクリプションでは取りこぼされます。取りこぼしを捕捉するため （再）購読時に各オープン ポジションをポーリング し、positionId で重複排除 してください。

WebSocket API#

リアルタイムデータは、GraphQL over WebSocket プロトコル（graphql-transport-ws） を用いた WebSocket 接続で配信されます。価格のリアルタイム更新などの subscription 操作に使用します。

接続#

次のアドレスへ WebSocket を開きます:

wss://public-api.catapult.trade/graphql

サブプロトコル graphql-transport-ws をネゴシエートします。ソケットが開いたら connection_init メッセージを送信すると、サーバーが connection_ack を返します。

ライフサイクル#

1. クライアントがサブプロトコル graphql-transport-ws でソケットを開く。
2. クライアント → {"type":"connection_init"}。
3. サーバー → {"type":"connection_ack"}。
4. クライアント → 一意の id と GraphQL ドキュメントを含む subscribe。
5. サーバー → 1 つ以上の next メッセージ、その後 complete。

サブスクライブ#

{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription($t: ID!) { priceTicks(tokenId: $t) { tokenId price } }",
    "variables": { "t": "<tokenId>" }
  }
}

データメッセージ#

{
  "id": "1",
  "type": "next",
  "payload": { "data": { "priceTicks": { "tokenId": "tok_123", "price": "0.0123" } } }
}

サブスクライブ解除#

1 つのサブスクリプションを停止するには complete メッセージを送信します。すべてを 停止するにはソケットを閉じます。

{ "id": "1", "type": "complete" }

エラー#

操作レベルのエラーは、対応する id の error メッセージとして届きます:

{ "id": "1", "type": "error", "payload": [{ "message": "Token not found" }] }

10 秒以内に connection_init を送信しない接続は、コード 4408（接続初期化タイムアウト） で閉じられます。