Jupiter API 統合

すべての Jupiter API に対応した単一スキル。高速ルーティングと決定的な実行に最適化されています。

ベース URL: https://api.jup.ag 認証: portal.jup.ag から取得した x-api-key (Jupiter REST エンドポイントに必須)

使用・未使用シーン

使用する場合:

• タスクで Jupiter エンドポイントを選択または呼び出す必要がある
• スワップ、レンディング、パープス、オーダー、価格設定、ポートフォリオ、送信、スタジオ、ロック、またはルーティングが関連している
• ユーザーが Jupiter API 呼び出しのデバッグサポートを必要としている

使用しない場合:

• タスクが Jupiter API 使用なしの汎用 Solana セットアップ
• タスクが API 動作決定なしの UI のみ
• エージェントコンテキストが DeFi/暗号資産ではない (汎用トリガー buy、sell、trade は DeFi ドメインを想定)

トリガー: swap、quote、gasless、best route、buy、sell、trade、convert、token exchange、jupiter api、jup.ag、ultra、metis、ultra swap、ultra api、ultra-api.jup.ag、lend、borrow、earn、yield、apy、deposit、liquidation、perps、leverage、long、short、position、futures、margin trading、limit order、trigger、price condition、dca、recurring、scheduled swaps、token metadata、token search、verification、shield、price、valuation、price feed、portfolio、positions、holdings、prediction markets、market odds、event market、invite transfer、send、clawback、create token、studio、claim fee、vesting、distribution lock、unlock schedule、dex integration、rfq integration、routing engine、status page、health check、service health、accumulate、auto-buy

開発者向けクイックスタート

import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js';

const API_KEY = process.env.JUPITER_API_KEY!;  // portal.jup.ag から取得
if (!API_KEY) throw new Error('Missing JUPITER_API_KEY');
const BASE = 'https://api.jup.ag';
const headers = { 'x-api-key': API_KEY };

async function jupiterFetch<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: { ...headers, ...init?.headers },
  });
  if (res.status === 429) throw { code: 'RATE_LIMITED', retryAfter: Number(res.headers.get('Retry-After')) || 10 };
  if (!res.ok) {
    const raw = await res.text();
    let body: any = { message: raw || `HTTP_${res.status}` };
    try {
      body = raw ? JSON.parse(raw) : body;
    } catch {
      // keep text fallback body
    }
    throw { status: res.status, ...body };
  }
  return res.json();
}

// Jupiter トランザクションに署名して送信
async function signAndSend(
  txBase64: string,
  wallet: Keypair,
  connection: Connection,
  additionalSigners: Keypair[] = []
): Promise<string> {
  const tx = VersionedTransaction.deserialize(Buffer.from(txBase64, 'base64'));
  tx.sign([wallet, ...additionalSigners]);
  const sig = await connection.sendRawTransaction(tx.serialize(), {
    maxRetries: 0,
    skipPreflight: true,
  });
  return sig;
}

インテントルーター (最初のステップ)

ユーザーインテント	API ファミリー	最初のアクション
スワップ/クォート	Swap	GET /swap/v2/order -> 署名 -> POST /swap/v2/execute
レンディング/借用/利回り	Lend	POST /lend/v1/earn/deposit または /withdraw
レバレッジ/パープス	Perps	Anchor IDL 経由のオンチェーン (REST API なし)
リミットオーダー	Trigger	JWT 認証 -> POST /trigger/v2/orders/price
DCA/リカリング買い	Recurring	POST /recurring/v1/createOrder -> 署名 -> POST /recurring/v1/execute
トークン検索	Tokens	GET /tokens/v2/search?query={mint}
トークン検証/メタデータ更新	jupiter-vrfd スキルを使用	延期 — このスキルでは処理されません
価格ルックアップ	Price	GET /price/v3?ids={mints}
ポートフォリオ/ポジション	Portfolio	GET /portfolio/v1/positions/{address}
予測マーケット統合	Prediction Markets	GET /prediction/v1/events -> POST /prediction/v1/orders
招待送信/クローバック	Send	POST /send/v1/craft-send -> 署名 -> RPC に送信
トークン作成/手数料	Studio	POST /studio/v1/dbc-pool/create-tx -> アップロード -> 送信
ベスティング/配布	Lock	オンチェーンプログラム LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn
DEX/RFQ 統合	Routing	DEX (AMM トレイト) vs RFQ (webhook) パスを選択

API プレイブック

各ブロックを最小限の実行契約として使用します。フルリクエスト/レスポンス形状、TypeScript インターフェース、パラメータ詳細については、リンクされた参考資料を取得してください。

Swap

• ベース URL: https://api.jup.ag/swap/v2
• トリガー: swap、quote、gasless、best route
• 手数料: ペアごとに変動 — 0 bps (Jupiter トークン/ペッグ)、2 bps (SOL-Stable)、5 bps (LST-Stable)、10 bps (ほとんどのペア)、50 bps (24 時間以内のトークン)。リファラル手数料: 50-255 bps (Jupiter が 20% を保持)。
• レート制限: 50 req/10s ベース、24 時間実行額でスケール (レート制限を参照)
• エンドポイント: /order (GET)、/execute (POST)、/build (GET、Metis のみの生命令)
• ルーティング: 4 つのルーターが競合 — Metis (API 値: iris)、JupiterZ (jupiterz)、Dflow (dflow)、OKX (okx)。レスポンス mode フィールド: "ultra" (すべてのルーター、デフォルトパラメータ) または "manual" (オプションパラメータで制限)。/build は Metis のみを使用。
• ガスレス: 3 つのパス — 自動 (Jupiter 負担)、JupiterZ (MM 負担)、統合者支払者 (payer パラメータ、Metis のみのルーティング)。適格性はバランス、取引額、使用パラメータで異なります。現在の閾値と除外パラメータについては ガスレスドキュメント を参照。
• 注意点: 署名済みペイロードの TTL は約 2 分。トランザクションは受信後、変更不可。コードとログで order/execute を分割。条件が変わった可能性がある場合は実行前に再クォート。referralAccount/referralFee/receiver は JupiterZ のみを無効化 (Metis/Dflow/OKX は残る)。payer はルーティングを Metis のみに削減 (ガスレスドキュメント参照; ルーティングドキュメントはすべての 4 つを JupiterZ 無効化としてグループ化するが、追加の Dflow/OKX 制限を詳細化していない)。/build トランザクションは /execute を使用不可 — RPC 経由で自己管理。
• 古い統合から移行中? jupiter-swap-migration スキルを使用。
• 参考: 概要 | Order & Execute | Build | 手数料 | ルーティング | ガスレス | 移行 | OpenAPI

/swap/v2/execute で返される一般的なエラーコード (推奨されるアクション付き):

コード	カテゴリ	意味	再試行可能	アクション
0	成功	トランザクション確認済み	—	—
-1	Execute	キャッシュ済みオーダーが見つからない/期限切れ	はい	再クォートして再試行
-2	Execute	無効な署名済みトランザクション	いいえ	トランザクション署名を修正
-3	Execute	無効なメッセージバイト	いいえ	シリアライゼーションを修正
-1000	Aggregator	ランディング試行失敗	はい	調整パラメータで再クォート
-1001	Aggregator	不明なエラー	はい	バックオフで再試行
-1002	Aggregator	無効なトランザクション	いいえ	トランザクション構築を修正
-1003	Aggregator	トランザクション未署名	いいえ	すべての必須署名者を確認
-1004	Aggregator	無効なブロック高	はい	再クォート (ブロックハッシュ古い)
-2000	RFQ	ランディング失敗	はい	再クォートして再試行
-2001	RFQ	不明なエラー	はい	バックオフで再試行
-2002	RFQ	無効なペイロード	いいえ	リクエストペイロードを修正
-2003	RFQ	クォート期限切れ	はい	再クォートして再試行
-2004	RFQ	スワップ拒否	はい	再クォート (別ルート検討)
429	レート制限	レート制限済み	はい	指数バックオフ、10s ウィンドウ待機

---

Lend

• ベース URL: https://api.jup.ag/lend/v1
• トリガー: lend、borrow、earn、liquidation
• プログラム: Earn jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9、Borrow jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi
• SDK: @jup-ag/lend (TypeScript)
• エンドポイント: /earn/deposit (POST)、/earn/withdraw (POST)、/earn/mint (POST)、/earn/redeem (POST)、/earn/deposit-instructions (POST)、/earn/withdraw-instructions (POST)、/earn/tokens (GET)、/earn/positions (GET)、/earn/earnings (GET)
• 注意点: 各状態変更アクション前にアカウント状態を再計算。健全性係数、清算境界などのリスクチェックをプリコンディションとしてエンコード。すべての deposit/withdraw/mint/redeem は base64 unsigned VersionedTransaction を返す。
• SDK レベルの統合: @jup-ag/lend と @jup-ag/lend-read の使用については jupiter-lend スキルを使用。
• 参考: 概要 | Earn | SDK | OpenAPI

---

Perps

• ステータス: API は 進行中。REST エンドポイントなし。Anchor IDL 経由でオンチェーンと対話。
• トリガー: perps、leverage、long、short、position
• コミュニティ SDK: github.com/julianfssen/jupiter-perps-anchor-idl-parsing
• 注意点: 最大 9 個の同時ポジション: 3 ロング (SOL、wETH、wBTC) + 6 ショート (3 トークン x 2 担保 USDC/USDT)。アカウントモデルに対してマージン/レバレッジを検証。
• 参考: 概要 | ポジションアカウント | ポジションリクエスト

---

Trigger (リミットオーダー)

• ベース URL: https://api.jup.ag/trigger/v2
• トリガー: limit order、trigger、price condition
• 最小オーダー: USD 相当 10 USD
• 認証: デュアル認証 — x-api-key (すべてのリクエスト) + Authorization: Bearer <jwt> (オーダー変更)。JWT はチャレンジ-レスポンス経由で取得: POST /auth/challenge → ウォレットでチャレンジに署名 → POST /auth/verify → トークン受け取り。JWT 有効期限は開きっぱなしのオーダーに影響しない — 実行を続ける。
• エンドポイント: /auth/challenge (POST、ボディ: walletPubkey + type)、/auth/verify (POST、ボディ: type + walletPubkey + base58 signature)、/vault (GET)、/vault/register (GET)、/deposit/craft (POST)、/orders/price (POST 作成、PATCH 更新)、/orders/price/cancel/{orderId} (POST、出金開始)、/orders/price/confirm-cancel/{orderId} (POST、署名済み出金 + cancelRequestId を送信)、/orders/history (GET、ウォレット JWT 経由で暗黙的)
• オーダータイプ: single (単一方向トリガー)、oco (利確 + 損切ペア)、otoco (エントリートリガー + OCO)。triggerCondition: "above" または "below"。
• アーキテクチャ: オフチェーン カストディアル金庫 (Privy) (ウォレットごと)。オーダーは実行まで オンチェーン非表示 — MEV 耐性。USD 価格でトリガー (プール率比でない)。部分約定対応。
• 注意点: オーダー作成は 3 ステップ — GET /vault/register (新規の場合は登録)、POST /deposit/craft (returns transaction + requestId)、出金 tx に署名、その後 POST /orders/price (depositRequestId + depositSignedTx 付き)。キャンセルは 2 ステップ — POST /cancel/{orderId} returns transaction + requestId; 署名、その後 POST /confirm-cancel/{orderId} (signedTransaction + cancelRequestId 付き)。レスポンスフィールドは id (orderId でない)。
• 参考: 概要 | オーダー作成 | オーダー履歴 | オーダー管理 | OpenAPI

---

Recurring (DCA)

• ベース URL: https://api.jup.ag/recurring/v1
• トリガー: dca、recurring、scheduled swaps
• 手数料: すべてのリカリングオーダーで 0.1%
• 制約: 最小 100 USD 合計、最小 2 オーダー、最小 50 USD / オーダー
• ページネーション: ページあたり 10 オーダー
• エンドポイント: /createOrder (POST)、/cancelOrder (POST)、/execute (POST)、/getRecurringOrders (GET)
• 注意点: Token-2022 は非対応。オーダー スケジューリングに params.time を使用; 価格ベースのオーダーは非対応。
• 参考: 概要 | 作成 | オーダー取得 | ベストプラクティス | OpenAPI

---

Tokens

• ベース URL: https://api.jup.ag/tokens/v2
• トリガー: token metadata、token search、shield
• エンドポイント: /search?query={q} (GET、コンマ区切りミント、最大 100)、/tag?query={tag} (GET、verified または lst)、/{category}/{interval} (GET、カテゴリ: toporganicscore、toptraded、toptrending; インターバル: 5m、1h、6h、24h)、/recent (GET)
• 注意点: ミントアドレスをプライマリアイデンティティとして使用; シンボル/名前を利便性として扱う。UX に audit.isSus と organicScore を表示。
• 参考: 概要 | トークン情報 v2 | OpenAPI

---

Price

• ベース URL: https://api.jup.ag/price/v3
• トリガー: price、valuation、price feed
• 制限: リクエストあたり最大 50 ミント ID
• エンドポイント: /price/v3?ids={mints} (GET、コンマ区切り)
• 注意点: 信頼できない価格設定を持つトークンは null を返すか省略 (エラーではない)。安全性に敏感なアクション では欠落/低信頼度データで閉じて失敗。confidenceLevel フィールドを使用。
• 参考: 概要 | Price v3 | OpenAPI

---

Portfolio

• ベース URL: https://api.jup.ag/portfolio/v1
• ステータス: ベータ — Jupiter プラットフォーム のみ
• トリガー: portfolio、positions、holdings
• エンドポイント: /positions/{address} (GET)、/positions/{address}?platforms={ids} (GET)、/platforms (GET)、/staked-jup/{address} (GET)
• 注意点: 空のポジションを有効な状態として扱う。レスポンスはベータ — 安定した内部スキーマに正規化。要素タイプ: multiple、liquidity、trade、leverage、borrowlend。
• 参考: 概要 | Jupiter ポジション | OpenAPI

---

Prediction Markets

• ベース URL: https://api.jup.ag/prediction/v1
• ステータス: ベータ (破壊的変更の可能性あり)
• 地理的制限: 米国および韓国の IP はブロック
• 価格規約: 1,000,000 ネイティブユニット = $1.00 USD
• トリガー: prediction markets、market odds、event market
• デポジットミント: JupUSD (JuprjznTrTSp2UFa3ZBUFgwdAmtZCq4MQCwysN55USD)、USDC
• エンドポイント: /events (GET)、/events/search (GET)、/markets/{marketId} (GET)、/orderbook/{marketId} (GET)、/orders (POST)、/orders/status/{pubkey} (GET)、/positions (GET)、/positions/{pubkey} (DELETE)、/positions/{pubkey}/claim (POST)、/history (GET)、/leaderboards (GET)
• 注意点: 請求前に position.claimable をチェック。勝者は契約あたり $1 を獲得。
• 参考: 概要 | イベント | ポジション | OpenAPI

---

Send

• ベース URL: https://api.jup.ag/send/v1
• ステータス: ベータ
• トリガー: invite transfer、send、clawback
• 対応トークン: SOL、USDC、ミームコイン
• エンドポイント: /craft-send (POST)、/craft-clawback (POST)、/pending-invites (GET)、/invite-history (GET)
• 注意点: デュアル署名要件 — 送信者 + 受取人キーペア (招待コードから派生)。クレームは Jupiter Mobile 経由のみ (API クレーム非対応)。招待コードを絶対に公開しないでください。
• 参考: 概要 | 招待コード | 送信 | OpenAPI

---

Studio

• ベース URL: https://api.jup.ag/studio/v1
• ステータス: ベータ
• トリガー: create token、studio、claim fee
• エンドポイント: /dbc-pool/create-tx (POST)、/dbc-pool/submit (POST、multipart/form-data)、/dbc-pool/addresses/{mint} (GET)、/dbc/fee (POST)、/dbc/fee/create-tx (POST)
• フロー: create-tx -> 署名付き URL に画像アップロード -> 署名付き URL にメタデータアップロード -> 署名 -> /dbc-pool/submit 経由で送信
• 注意点: トークンが jup.ag の Studio ページを取得するには /dbc-pool/submit 経由で送信する必要があります (外部からではない)。エラーコード: 403 = プールの権限なし、404 = プロキシアカウント見つかりません。
• 参考: 概要 | トークン作成 | 手数料の請求 | OpenAPI

---

Lock

• プログラム ID: LocpQgucEQHbqNABEYvBvwoxCPsSbG91A1QaQhQQqjn
• トリガー: vesting、distribution lock、unlock schedule
• 統合: オンチェーンプログラムのみ (REST API なし)
• ソース: github.com/jup-ag/jup-lock
• UI: lock.jup.ag
• セキュリティ: OtterSec および Sec3 による監査済み
• 注意点: REST API なし。リポジトリの cli/src/bin/instructions ディレクトリから命令スクリプトを使用。
• 参考: Lock 概要

---

Routing

• トリガー: dex integration、rfq integration、routing engine
• エンジン: Juno (メタアグリゲータ)、Iris (マルチホップ DEX ルーティング、Swap API を強化)、JupiterZ (RFQ マーケットメーカークォート)
• DEX 統合 (Iris へ): 無料、手数料なし。前提条件: コード健全性、セキュリティ監査、市場流動性。jupiter-amm-interface クレートを実装。重要: 実装内のネットワーク呼び出しなし (アカウントは事前バッチおよびキャッシュ)。参考実装: github.com/jup-ag/rust-amm-implementation
• RFQ 統合 (JupiterZ): マーケットメーカーは /jupiter/rfq/quote (POST、250ms) で webhook をホスト、/jupiter/rfq/swap (POST)、/jupiter/rfq/tokens (GET)。要件: 95% 約定率、250ms レスポンス、55s 有効期限。SDK: github.com/jup-ag/rfq-webhook-toolkit
• マーケット掲載: 24 日以内のトークンのための即座ルーティング。通常ルーティング (30 分ごとにチェック) には $500 往復で < 30% 損失または $1k vs $500 比較で < 20% スリッページが必要。
• 参考: 概要 | DEX 統合 | RFQ 統合 | マーケット掲載

---

レート制限

Swap API (動的、額ベース):

24 時間実行額	10 秒ウィンドウあたりのリクエスト
$0	50
$10,000	51
$100,000	61
$1,000,000	165

クォータは 10 分ごとに再計算。Pro プランは Swap API 制限を増加させません。

その他の API: ポータルレベルで管理。ポータルレート制限を確認。

HTTP 429 時: ジッター付き指数バックオフ: delay = min(baseDelay * 2^attempt + random(0, jitter), maxDelay)。10s スライディングウィンドウの更新を待機。積極的にバースト しないでください。

本番環境の強化

1. 認証: x-api-key が欠落または無効の場合は早期失敗。
2. タイムアウト: クォート 5s、実行 30s、プラス総操作タイムアウト。
3. 再試行: 一時的/ネットワーク/レート制限失敗のみ、指数バックオフ + ジッター付き。
4. べき等性: Swap /execute は同じ signedTransaction + requestId を 2 分間受け入れ、重複実行なし。
5. 検証: 呼び出し前にミントアドレス、金額精度、ウォレット所有権を検証。
6. 安全性: アプリ設定からのスリッページおよび最大額ガードレールを強制。
7. 観測性: requestId、API ファミリー、エンドポイント、レイテンシー、ステータス、エラーコードをログ。
8. UX 耐性: アクション可能な状態を返す (retry、adjust params、insufficient balance、rate limited)。
9. 一貫性: 最終ユーザー成功前に非同期状態 (送信済み vs 確認済み vs 失敗) を調整。
10. 鮮度: 動作が予想フローと異なる場合は参考ドキュメントを再取得。

統合ベストプラクティス

1. コーディング前に API 固有の概要から始める。
2. すべてのリクエストに対して認証をハード前提条件として強制。参考: ポータルセットアップ
3. 固定の仮定ではなく、ドキュメント化されたレート制限動作の周りで再試行ロジックを設計。参考: レート制限
4. ドキュメント化されたレスポンスセマンティクスを使用して、すべての非成功レスポンスを型指定されたアプリエラーにマッピング。参考: API レスポンス
5. オーダーベースの製品 (Swap/Trigger/Recurring) の場合、コードとログで create/execute/retrieve フェーズを分離。
6. ネットワーク/サービスの健全性をランタイム動作の一部として扱う (適切に低下)。参考: ステータスページ

横断的エラーパターン

interface JupiterResult<T> {
  ok: boolean;
  result?: T;
  error?: { code: string | number; message: string; retryable: boolean };
}

async function jupiterAction<T>(action: () => Promise<T>): Promise<JupiterResult<T>> {
  try {
    const result = await action();
    return { ok: true, result };
  } catch (error: any) {
    const code = error?.code ?? error?.status ?? 'UNKNOWN';

    // レート制限 — バックオフで再試行
    if (code === 429 || code === 'RATE_LIMITED') {
      return { ok: false, error: { code: 'RATE_LIMITED', message: 'Rate limited', retryable: true } };
    }

    // Swap execute エラー (負のコード)
    if (typeof code === 'number' && code < 0) {
      const retryable = [-1, -1000, -1001, -1004, -2000, -2001, -2003, -2004].includes(code);
      return { ok: false, error: { code, message: error?.error ?? 'Execute failed', retryable } };
    }

    // プログラムエラー (6001 = スリッページのような正のコード)
    if (typeof code === 'number' && code > 0) {
      return { ok: false, error: { code, message: error?.error ?? 'Program error', retryable: false } };
    }

    return { ok: false, error: { code, message: error?.message ?? 'UNKNOWN_ERROR', retryable: false } };
  }
}

async function withRetry<T>(action: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const result = await jupiterAction(action);
    if (result.ok) return result.result!;
    if (!result.error?.retryable || attempt === maxRetries) throw result.error;
    const delay = Math.min(1000 * 2 ** attempt + Math.random() * 500, 10000);
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error('Retry exhausted');
}

完全に動作する例

本番対応コードスニペット。各例は上記セクションの jupiterFetch ヘルパーを使用; 本番環境では withRetry を execute 呼び出し周辺に適用。

• Swap: エンドツーエンド — Order -> 署名 -> execute -> 確認フロー
• Lend: USDC デポジット — Jupiter Lend 利回りプールへのデポジット
• Trigger: リミットオーダー — リミットオーダーの作成と実行
• Price: マルチトークンルックアップ — 信頼度フィルタリング付きの価格取得

フレッシュコンテキストポリシー

参照ドキュメント/仕様からプレイブック実行前に常に最新のコンテキストを取得。

1. インテントを Intent Router で解決。
2. コーディング前に、プレイブックのリンクされた参考資料を取得 (概要 + API 固有ドキュメント)。
3. 必要に応じて検証または曖昧さ解消のために OpenAPI 仕様を取得。
4. 取得したドキュメントをキャッシュメモリよりも信頼性の源と扱う。
5. 取得したドキュメントがこのファイルと競合する場合、取得したドキュメントに従い、不一致をメモ。
6. ドキュメントが取得できない場合、コンテキストが古い/未検証であることを述べ、最良の既知ガイダンスで続行。
7. 認証不変を保持: x-api-key は Jupiter REST エンドポイントに必須 (Perps/Lock のようなオンチェーンのみフロー でない)。

運用参考資料

• ポータルセットアップ — API キー設定
• レート制限 — グローバルレート制限ポリシー
• Swap ルーティング — ルーター競合およびパラメータ影響
• API レスポンス — レスポンス形式標準
• Swap order & execute — 詳細エラーコードおよびレスポンス形式
• ステータスページ — サービス健全性
• ドキュメントサイトマップ — フルドキュメントインデックス
• ツールキット — プラグイン、ウォレットキット、リファラルプログラム