integrating-jupiter

Jupiter API 連携

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

ベース URL: https://api.jup.ag 認証: portal.jup.ag の x-api-key（Jupiter REST エンドポイントで必須）

使用する場合／使用しない場合

次の場合に使用します：

• Jupiter のエンドポイントを選択または呼び出す必要があるタスク。
• スワップ、レンディング、無期限先物、注文、価格、ポートフォリオ、送信、Studio、ロック、ルーティングに関するタスク。
• Jupiter API 呼び出しのデバッグ支援が必要な場合。

次の場合は使用しないでください：

• Jupiter API を使用しない一般的な Solana のセットアップ。
• API の動作に関する判断を伴わない、UI のみのタスク。

トリガー: swap、quote、gasless、best route、lend、borrow、earn、liquidation、perps、leverage、long、short、position、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

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

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

const API_KEY = process.env.JUPITER_API_KEY!;  // from 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: 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();
}

// Sign and send any Jupiter transaction
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 ファミリー	最初のアクション
スワップ／見積もり	Ultra Swap	GET /ultra/v1/order -> 署名 -> POST /ultra/v1/execute
レンディング／借り入れ／利回り	Lend	POST /lend/v1/earn/deposit または /withdraw
レバレッジ／無期限先物	Perps	Anchor IDL を介してオンチェーンで実行（REST API はまだありません）
指値注文	Trigger	POST /trigger/v1/createOrder -> 署名 -> POST /trigger/v1/execute
DCA／定期購入	Recurring	POST /recurring/v1/createOrder -> 署名 -> POST /recurring/v1/execute
トークン検索／検証	Tokens	GET /tokens/v2/search?query={mint}
価格の検索	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 トレイト）と RFQ（Webhook）のどちらの経路を使うか選択

API プレイブック

各ブロックを最小限の実行仕様として使用してください。完全なリクエスト／レスポンス形式、TypeScript インターフェース、パラメーターの詳細については、リンク先のリファレンスを参照してください。

Ultra Swap

• ベース URL: https://api.jup.ag/ultra/v1
• トリガー: swap、quote、gasless、best route
• 手数料: 5～10 bps（標準）、またはカスタム手数料を設定した場合はインテグレーター手数料の 20%
• レート制限: 基本は 10 秒あたり 50 リクエスト。24 時間の execute 量に応じて増加します（レート制限を参照）。
• エンドポイント: /order（GET）、/execute（POST）、/holdings/{account}（GET）、/shield（GET）、/search（GET）、/routers（GET）
• 注意点: 署名済みペイロードの TTL は約 2 分です。受信後、トランザクションは変更できません。コードとログでは order と execute を分離してください。状況が変化した可能性がある場合は、実行前に見積もりを取り直してください。
• 参照先: 概要 | 注文 | 実行 | レスポンス

---

レンド

• ベース 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 エンコードされた署名なしの VersionedTransaction を返します。
• 参考資料：概要 | Earn | SDK

---

パープス

• ステータス：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 トークン × 2 種類の担保 USDC／USDT）です。アカウントモデルに照らして、証拠金／レバレッジを検証してください。
• 参考資料：概要 | ポジションアカウント | ポジションリクエスト

---

トリガー（指値注文）

• ベース URL：https://api.jup.ag/trigger/v1
• トリガー：limit order、trigger、price condition
• 手数料：0.1%（非ステーブルペア）、0.03%（ステーブルペア）
• ページネーション：1 ページあたり 10 件の注文
• エンドポイント：/createOrder（POST）、/cancelOrder（POST）、/cancelOrders（POST、1 トランザクションあたり最大 5 件）、/execute（POST）、/getTriggerOrders（GET）
• 注意点：フロントエンドでは最低額が 5 USD に設定されていますが、オンチェーンには最低額がありません。プログラムはレートが有利かどうかを検証しないため、作成前に目標価格を検証してください。Token-2022 は無効です。デフォルトではスリッページがゼロの「Exact」モードです。約定率を高める「Ultra」モードを使うには、slippageBps を設定してください。
• 参考資料：概要 | 作成 | 注文の取得 | ベストプラクティス

---

リカーリング（DCA）

• ベース URL：https://api.jup.ag/recurring/v1
• トリガー：dca、recurring、scheduled swaps
• 手数料：すべてのリカーリング注文に 0.1%
• 制約：合計最低額 100 USD、注文数は最低 2 件、1 件あたりの最低額 50 USD
• ページネーション：1 ページあたり 10 件の注文
• エンドポイント：/createOrder（POST）、/cancelOrder（POST）、/execute（POST）、/getRecurringOrders（GET）
• 注意点：Token-2022 はサポートされていません。価格ベースのリカーリング注文は非推奨です。params.time のみを使用してください。
• 参考資料：概要 | 作成 | 注文の取得 | ベストプラクティス

---

Tokens

• ベース URL: https://api.jup.ag/tokens/v2
• トリガー: token metadata、token search、verification、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 を表示してください。
• 参照: 概要 | Token info v2

---

価格

• ベース URL: https://api.jup.ag/price/v3
• トリガー: price、valuation、price feed
• 上限: 1リクエストあたり最大50個のミント ID
• エンドポイント: /price/v3?ids={mints}（GET、カンマ区切り）
• 注意事項: 価格の信頼性が低いトークンは、null を返すか、応答から省略されます（エラーではありません）。安全性が重要な操作では、データが欠落している場合や信頼度が低い場合は処理を中止してください。confidenceLevel フィールドを使用してください。
• 参照: 概要 | Price v3

---

ポートフォリオ

• ベース 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 positions

---

予測市場

• ベース URL: https://api.jup.ag/prediction/v1
• ステータス: ベータ版（破壊的変更の可能性があります）
• 地域制限: 米国および韓国の IP はブロックされます
• 価格の規則: ネイティブ単位1,000,000 = 1.00米ドル
• トリガー: 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件につき1ドルを受け取ります。
• 参照: 概要 | Events | Positions

---

送信

• ベース 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 からの請求には対応していません）。招待コードは決して公開しないでください。
• 参照: 概要 | Invite code | Craft send

---

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 = プロキシアカウントが見つかりません。
• 参考資料：概要 | トークンの作成 | 手数料の請求

---

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 ルーティング。Ultra を支えています）、JupiterZ（RFQ マーケットメイカーの見積もり）
• DEX 統合（Iris への統合）：無料、手数料なし。前提条件：コードの健全性、セキュリティ監査、市場での実績。jupiter-amm-interface クレートを実装してください。重要：実装内でネットワーク呼び出しを行わないでください（アカウントは事前に一括取得され、キャッシュされています）。参照実装：github.com/jup-ag/rust-amm-implementation
• RFQ 統合（JupiterZ）：マーケットメーカーは /jupiter/rfq/quote（POST、250ms）、/jupiter/rfq/swap（POST）、/jupiter/rfq/tokens（GET）に Webhook をホストします。要件：約定率 95％、応答時間 250ms、有効期限 55s。SDK：github.com/jup-ag/rfq-webhook-toolkit
• 市場への掲載：作成から 30 日未満のトークンは即時ルーティングされます。通常のルーティング（30 分ごとに確認）には、$500 の往復取引で損失が 30％未満、または $1k と $500 を比較した価格インパクトが 20％未満であることが必要です。
• 参考資料：概要 | DEX 統合 | RFQ 統合 | 市場への掲載

---

レート制限

Ultra Swap（動的、取引量ベース）：

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

クォータは 10 分ごとに再計算されます。Pro プランで Ultra の上限は増加しません。

その他の API：ポータルレベルで管理されます。ポータルのレート制限を確認してください。

HTTP 429 の場合：ジッターを加えた指数バックオフを使用してください：delay = min(baseDelay * 2^attempt + random(0, jitter), maxDelay)。10 秒のスライディングウィンドウが更新されるまで待ってください。積極的に大量のリクエストを送信しないでください。

本番環境向けの堅牢化

1. 認証：x-api-key がない、または無効な場合は、速やかに失敗させます。
2. タイムアウト：見積もりは5秒、実行は30秒に設定し、さらに操作全体のタイムアウトも設定します。
3. 再試行：一時的な障害、ネットワーク障害、レート制限による失敗に限り、指数バックオフとジッターを適用して再試行します。
4. 冪等性：Ultra の /execute は、同じ signedTransaction と requestId を受け取った場合、最大2分間、重複実行せずに受け付けます。
5. 検証：呼び出し前に、ミントアドレス、金額の精度、ウォレットの所有権を検証します。
6. 安全性：アプリ設定に基づき、スリッページと最大金額のガードレールを適用します。
7. 可観測性：requestId、API ファミリー、エンドポイント、レイテンシ、ステータス、エラーコードをログに記録します。
8. UX の耐障害性：実行可能な状態（「再試行」「パラメーターを調整」「残高不足」「レート制限中」）を返します。
9. 整合性：ユーザーへの最終的な成功通知の前に、非同期の状態（送信済み、確認済み、失敗）を照合します。
10. 最新性：動作が想定されるフローと異なる場合は、参照先のドキュメントを再取得します。

統合のベストプラクティス

1. エンドポイント呼び出しを実装する前に、API 固有の概要を確認します。
2. すべてのリクエストで認証を必須の前提条件とします。参照：ポータルのセットアップ
3. 固定の想定ではなく、ドキュメントに記載されたレート制限の動作に基づいて再試行ロジックを設計します。参照：レート制限
4. ドキュメントに記載されたレスポンスの仕様に基づき、すべての成功以外のレスポンスを型付きアプリケーションエラーに対応付けます。参照：API レスポンス
5. 注文ベースのプロダクト（Ultra／Trigger／Recurring）では、作成、実行、取得の各フェーズをコードとログで分けます。
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';

    // Rate limit — retry with backoff
    if (code === 429 || code === 'RATE_LIMITED') {
      return { ok: false, error: { code: 'RATE_LIMITED', message: 'Rate limited', retryable: true } };
    }

    // Ultra execute errors (negative codes)
    if (typeof code === 'number' && code < 0) {
      const retryable = [-1, -1000, -1001, -1005, -1006, -2000, -2003, -2005].includes(code);
      return { ok: false, error: { code, message: error?.error ?? 'Execute failed', retryable } };
    }

    // Program errors (positive codes like 6001 = slippage)
    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 } };
  }
}

コンテキストの最新性に関するポリシー

プレイブックを実行する前に、参照先のドキュメントや仕様から常に最新のコンテキストを取得してください。

1. Intent Router で意図を判断します。
2. コーディングの前に、プレイブックにリンクされた参照先（概要と API 固有のドキュメント）を取得します。
3. 検証や曖昧さの解消に必要な場合は、OpenAPI 仕様を取得します。
4. 取得したドキュメントは、キャッシュされたメモリよりも信頼できる情報源として扱います。
5. 取得したドキュメントがこのファイルと矛盾する場合は、取得したドキュメントに従い、相違点を記録します。
6. ドキュメントを取得できない場合は、コンテキストが古い、または未検証であることを明示し、入手可能な範囲で最善のガイダンスに従って続行します。
7. 認証の不変条件を維持します。Jupiter REST エンドポイントでは x-api-key が必須です（Perps／Lock のようなオンチェーンのみのフローを除く）。

運用上の参照先

• ポータルのセットアップ — API キーの設定
• レート制限 — 全体のレート制限ポリシー
• Ultra のレート制限 — 動的なボリュームベースの制限
• API レスポンス — レスポンス形式の標準
• Ultra のレスポンス — 詳細なエラーコード
• ステータスページ — サービスの健全性
• ドキュメントサイトマップ — ドキュメントの完全な索引
• ツールキット — プラグイン、Wallet Kit、紹介プログラム