integrating-jupiter

Jupiter API 統合

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

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

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

次の場合に使用します：

• Jupiter エンドポイントの選択または呼び出しが必要なタスク。
• スワップ、レンディング、無期限先物、注文、価格、ポートフォリオ、送金、Studio、ロック、ルーティングに関するタスク。
• 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!;  // from developers.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();
}

// 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;
}

トークンの数量と小数桁数

Jupiter のすべての amount フィールドは、トークンの**最小単位（生の整数値）**です。人間向け／UI 表示用の値ではありません。

• 一般的な小数桁数：SOL と wSOL = 9、USDC と USDT = 6。標準のミント：SOL So11111111111111111111111111111111111111112、USDC EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v。
• 人間向けの値から生の値への変換：raw = Math.round(human * 10 ** decimals)。例：1 SOL → 1_000_000_000、100 USDC → 100_000_000。slippageBps はベーシスポイントです：0.5% = 50、1% = 100。
• @solana/spl-token の getMint(connection, mintPubkey) を使って、オンチェーンでミントごとの小数桁数を取得してください。ハードコードは避けてください（小数桁数はトークンによって異なります）。また、小数桁数を調べる目的だけで Price API を呼び出さないでください。

インテントルーター（最初のステップ）

ユーザーの意図	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 トレイト）と RFQ（Webhook）のどちらの経路を使うか選択

API プレイブック

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

Swap

• ベース URL：https://api.jup.ag/swap/v2

• トリガー：swap、quote、gasless、best route

• 手数料：ペアによって異なります — 0 bps（Jupiter トークン／ペッグトークン）、2 bps（SOL-ステーブルコイン）、5 bps（LST-ステーブルコイン）、10 bps（大半のペア）、50 bps（上場から 24 時間未満のトークン）。紹介手数料：50～255 bps（Jupiter が 20％を保持）。

• レート制限：ベースは 10 秒あたり 50 リクエストで、24 時間の約定額に応じて増加します（レート制限を参照）。

• エンドポイント：/order（GET）、/execute（POST）、/build（GET、Metis 専用の生の命令）

• 見積もりと実行：読み取り専用の見積もり／価格のプレビューには、takerを省略してGET /orderを呼び出してください — レスポンスのtransactionはnullとなり、outAmount、routePlan[].swapInfo.label、価格インパクトのフィールドを確認できます。実際にスワップする場合に限り、takerを指定してください（その後、署名してPOST /executeを呼び出します）。個別の見積もりエンドポイントはありません — /swap/v1/quoteは非推奨です。見積もりにも/swap/v2/orderを使用してください。

• ルーティング：4 つのルーターが競合します — Metis（metis）、JupiterZ（jupiterz）、Dflow（dflow）、OKX（okx）。レスポンスのrouterフィールドには、これらのいずれかが返されます。swapTypeはaggregator（Metis、Dflow、または OKX）かrfq（JupiterZ）です。レスポンスのmodeフィールドは、"ultra"（すべてのルーター、デフォルトのパラメーター）または"manual"（任意のパラメーターによる制限）です。/buildは Metis のみを使用します。

• ガス代不要：3 つの方法があります — 自動（Jupiter が負担）、JupiterZ（MM が負担）、インテグレーター負担（payerパラメーター、Metis のみのルーティング）。利用条件は、残高、取引サイズ、使用するパラメーターによって異なります。現在のしきい値と対象外となるパラメーターについては、ガス代不要のドキュメントを参照してください。

• 注意点：

  • 署名済みペイロードの有効期間は約 2 分です。トランザクションは受信後に変更できません。
  • コードとログでは、注文と実行を分けてください。条件が変わった可能性がある場合は、実行前に見積もりを取り直してください。
  • 任意のパラメーターによるルーティングへの影響：referralAccountとreferralFeeを指定すると JupiterZ のみが無効になります（Metis／Dflow／OKX は引き続き利用可能です）。payer（インテグレーター負担のガス代不要）を指定すると、ルーティングは Metis のみに制限されます（JupiterZ、Dflow、OKX は無効になります）。receiverはルーティングを制限しませんが、takerとは異なる値である必要があります（receiver=takerを指定すると400 "Receiver cannot be same as taker"が返されます）。
  • /buildのトランザクションは/executeを使用できません — RPC を介してご自身で管理してください。

• 古いインテグレーションから移行しますか？ jupiter-swap-migrationスキルを使用してください。

• 参考資料：概要 | 注文と実行 | ビルド | ガス代不要 | 移行 | OpenAPI

  手数料は「注文と実行」および「ビルド」のページに記載されています。ルーター間の競合と、パラメーターがルーティングに与える影響の一覧は、「概要」と「注文と実行」のページにあります。

/swap/v2/executeが返す一般的なエラーコードと推奨される対応：

コード	カテゴリー	意味	再試行可能	対応
0	成功	トランザクションが確定しました	—	—
-1	実行	キャッシュされた注文が見つからないか、有効期限が切れています	はい	再見積もりして再試行します
-2	実行	署名済みトランザクションが無効です	いいえ	トランザクションの署名を修正します
-3	実行	メッセージのバイト列が無効です	いいえ	シリアライズを修正します
-1000	アグリゲーター	着地の試行に失敗しました	はい	パラメーターを調整して再見積もりします
-1001	アグリゲーター	不明なエラーです	はい	間隔を空けて再試行します
-1002	アグリゲーター	トランザクションが無効です	いいえ	トランザクションの構築を修正します
-1003	アグリゲーター	トランザクションに必要な署名がすべて揃っていません	いいえ	必要な署名者がすべて揃っていることを確認します
-1004	アグリゲーター	ブロック高が無効です	はい	再見積もりします（ブロックハッシュが古くなっています）
-2000	RFQ	着地に失敗しました	はい	再見積もりして再試行します
-2001	RFQ	不明なエラーです	はい	間隔を空けて再試行します
-2002	RFQ	ペイロードが無効です	いいえ	リクエストのペイロードを修正します
-2003	RFQ	見積もりの有効期限が切れています	はい	再見積もりして再試行します
-2004	RFQ	スワップが拒否されました	はい	再見積もりします。必要に応じて別のルートを使用します
429	レート制限	レート制限に達しました	はい	指数バックオフを適用し、10 秒間のウィンドウが経過するまで待ちます

成功時、/execute は { status: "Success", code: 0, signature, inputAmountResult, outputAmountResult, slot, totalInputAmount, totalOutputAmount } を返します。失敗時は、status: "Failed" とゼロ以外の code、および error 文字列を返します。inputAmountResult／outputAmountResult は実際のオンチェーンの金額です。見積もりと照合してください。

---

レンディング

• ベース 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 を返します。
• @jup-ag/lend および @jup-ag/lend-read を使用した SDK レベルの統合については、jupiter-lend スキルを使用してください。
• 参照先：概要 | Earn | SDK | OpenAPI

---

パープ

• ステータス：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）です。アカウントモデルに照らして、マージン／レバレッジを検証してください。
• 参照先：概要 | ポジションアカウント | ポジションリクエスト

---

Trigger（指値注文）

• ベース URL: https://api.jup.ag/trigger/v2
• トリガー: limit order、trigger、price condition
• 最小注文額: 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（未登録の場合は登録します。すでに登録済みの場合は 409 "Vault already registered" が返されますが、問題ありません）、POST /deposit/craft（transaction + requestId が返されます。本文には orderType: "price" と orderSubType（single／oco／otoco）を必ず含めてください）、入金トランザクションに署名し、続いて depositRequestId + depositSignedTx を指定して POST /orders/price を送信します。
  • 注文のキャンセルには 2 つの手順が必要です。POST /cancel/{orderId} から transaction + requestId が返されます。署名した後、signedTransaction + cancelRequestId を指定して POST /confirm-cancel/{orderId} を送信します。
  • 作成レスポンスのフィールドは orderId ではなく id です。注文履歴オブジェクトでは orderState／rawState を使用し、status フィールドはありません。
• 参照: 概要 | 認証 | 注文の作成 | 注文履歴 | 注文の管理 | OpenAPI

---

Recurring（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 を使用してください。価格ベースの注文には対応していません。
• 参照: 概要 | 作成 | 注文の取得 | ベストプラクティス | OpenAPI

---

トークン

• ベース 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）
• 注意点:
  • ミントアドレスを主たる識別子として使用し、シンボルや名前は便宜的なものとして扱ってください。
  • 主な信頼性シグナルはトップレベルの isVerified（ブール値）、organicScore（0～100）、organicScoreLabel（high／medium／low）です。
  • 二次的なリスクフラグ：audit.isSus — true の場合にのみ存在するブール値です（安全なトークンには isSus キー自体がありません）。そのため、token.audit?.isSus === true のように防御的に確認し、直接読み取らないでください。フラグが付いたトークンで isVerified が null、organicScoreLabel が "low" のものが実際に確認されています（開発者が供給量の約100%を保有）。isSus がないことは安全の証明にはなりません。すべてのリスクのあるトークンにこのフラグが付いているわけではありません。
  • ライブ API が返すその他の条件付き audit フィールド：mintAuthorityDisabled、freezeAuthorityDisabled、topHoldersPercentage、devBalancePercentage、devMigrations、devMints（すべて nullable で、いずれも欠落する場合があります。devMigrations は返されますが、現行の OpenAPI スキーマにはありません）。
• 参照： 概要 | トークン情報 v2 | OpenAPI

---

価格

• ベース URL: https://api.jup.ag/price/v3
• トリガー: price、valuation、price feed
• 上限: 1リクエストあたり最大50個のミント ID
• エンドポイント: /price/v3?ids={mints}（GET、カンマ区切り）
• レスポンス: ミントアドレスをキーとし、各値に usdPrice、blockId、decimals、priceChange24h、liquidity、createdAt が含まれます（トークンによっては launchpad、stockData、scaledUiConfig などの条件付きフィールドが追加されます）。Price API V3 には confidenceLevel フィールドはありません（これは V2 のものでした）。
• 注意点: 価格の信頼性が低いトークンは、レスポンスから完全に除外されます（エラーではなく、null のプレースホルダーもありません）。安全性が重要な操作では、リクエストしたミントがレスポンスにない場合はフェイルクローズにしてください。価格の鮮度を確認するには blockId を使用してください。
• 参照： 概要 | OpenAPI

---

ポートフォリオ

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

---

予測市場

• ベース URL：https://api.jup.ag/prediction/v1
• ステータス：ベータ版（破壊的変更が発生する可能性があります）
• 地域制限：米国および韓国の IP はブロックされています
• 価格の単位：ネイティブ単位 1,000,000 = 1.00 USD
• トリガー：prediction markets、market odds、event market
• 入金用ミント：JupUSD（JuprjznTrTSp2UFa3ZBUFgwdAmtZCq4MQCwysN55USD）、USDC
• 最小注文額：5 ドル（ネイティブ単位 5,000,000）
• エンドポイント：/events（GET、{data, pagination}を返します）、/events/search（GET）、/markets/{marketId}（GET）、/orderbook/{marketId}（GET、{yes, no, yes_dollars, no_dollars}を返します）、/orders（POST、isBuyブール値とownerPubkeyが必要です）、/orders/status/{orderPubkey}（GET）、/positions（GET、?ownerPubkey=）、/positions/{positionPubkey}（DELETE）、/positions/{positionPubkey}/claim（POST）、/history（GET）、/leaderboards（GET）
• 注意点：
  • 請求する前にposition.claimableを確認してください。勝者には契約ごとに 1 ドルが支払われます。
  • 市場データはフラットな構造です。provider、marketId、result、resolveAt、outcomes、clobTokenIdsなどのフィールドはトップレベルにあり、metadataの下にはネストされていません。
  • 契約数は小数単位です。従来の整数値のcontractsではなく、contractsMicro（1,000,000 = 1 契約）またはcontractsDecimalを使用してください。
• 参照：概要 | イベント | ポジション | OpenAPI

---

送金

• ベース 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経由で送信
• 注意点：トークンのStudioページをjup.agに表示するには、外部からではなく/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の概要

---

ルーティング

• トリガー：dex integration、rfq integration、routing engine
• エンジン：Juno（メタアグリゲーター）、Metis（マルチホップ DEX ルーティング。Swap API を支えています。旧称 Iris）、JupiterZ（RFQ マーケットメーカーの見積もり）
• DEX 統合（Metis への統合）：無料、手数料はかかりません。前提条件：コードの健全性、セキュリティ監査、市場での実績。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、有効期限 55 秒。SDK：github.com/jup-ag/rfq-webhook-toolkit
• 市場への上場：トークンの発行から 30 日未満の場合、即時にルーティングされます。通常のルーティング（30 分ごとに確認）には、500 ドルの往復取引で損失が 30％未満、または 1,000 ドルと 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)。10 秒間のスライディングウィンドウが更新されるまで待機してください。積極的に大量のリクエストを送信しないでください。

本番環境に向けた強化

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

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

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

    // Swap execute errors (negative codes)
    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 } };
    }

    // 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 } };
  }
}

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 で囲んでください。

• スワップ：エンドツーエンド — 注文 -> 署名 -> 実行 -> 確認のフロー
• レンディング：USDC の預け入れ — Jupiter Lend の運用プールに預け入れます
• トリガー：指値注文 — 指値注文を作成して実行します
• 価格：複数トークンの検索 — 信頼度フィルタリングを適用して価格を取得します

最新コンテキストの方針

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

1. Intent Router で意図を特定します。
2. コーディングの前に、プレイブックでリンクされている参照資料（概要および API 固有のドキュメント）を取得します。
3. 検証や曖昧さの解消が必要な場合は、OpenAPI 仕様を取得します。
4. 取得したドキュメントを、キャッシュされた記憶よりも優先される信頼できる情報源として扱います。
5. 取得したドキュメントがこのファイルと矛盾する場合は、取得したドキュメントに従い、不一致を記載します。
6. ドキュメントを取得できない場合は、コンテキストが古い、または未検証であることを明記し、可能な限り正確なガイダンスに基づいて続行します。
7. 認証に関する不変条件を守ります。Jupiter REST エンドポイントでは x-api-key が必須です（Perps／Lock のようなオンチェーンのみのフローでは不要です）。

運用リファレンス

• Portal のセットアップ — API キーの設定
• レート制限 — 全体のレート制限ポリシー
• スワップの概要 — ルーター間の競合とパラメーターの影響
• API レスポンス — レスポンス形式の標準
• スワップの注文と実行 — 詳細なエラーコードとレスポンス形式
• ステータスページ — サービスの稼働状況
• ドキュメントのサイトマップ — ドキュメントの完全なインデックス
• ツールキット — プラグイン、Wallet Kit、紹介プログラム