> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raydium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 交易 API

> Raydium 的伺服器端建構交換交易端點：報價、建構、簽署、發送。想使用 Raydium 路由但不需要搭載 SDK 的應用程式的整合方案 — 它回傳什麼、與 SDK 有何差異，以及聚合器如何使用它。

<Info>
  **本頁內容由 AI 自動翻譯，所有內容以英文版本為準。**

  [查看英文版 →](/sdk-api/trade-api)
</Info>

<Info>
  **交易 API** 是在 `transaction-v1.raydium.io`（以及 `api-v3.raydium.io` 上的某些鏡像路徑）上的一套端點集合，可在一個往返中報價交換、建構已簽署的 Solana 交易，並將其返回。這是 Raydium UI 使用的相同介面。當你想使用 Raydium 路由但不需搭載 TS SDK 時使用 — 適用於後端、Blinks 處理程式、Telegram 機器人、第三方應用程式。
</Info>

## 何時使用交易 API vs SDK

| 你想要…                                              | 使用                                                       |
| ------------------------------------------------- | -------------------------------------------------------- |
| 將交換整合到無法搭載 npm 套件的後端（例如 Python 機器人、Go 服務、Rust 服務） | **交易 API**                                               |
| 在社群貼文中渲染交換 Blink                                  | **交易 API**                                               |
| 構建一個每位元組都重要的瀏覽器應用程式                               | **交易 API**                                               |
| 在另一個 Solana 程式內嵌入路由邏輯（CPI）                        | 都不用 — 使用 [`sdk-api/rust-cpi`](/zh-Hant/sdk-api/rust-cpi) |
| 構建具有自訂路由預覽、圖表疊層、優先費用啟發式的完整 DEX 類客戶端               | **TS SDK**                                               |
| 需要確定性離線報價而無需網路往返                                  | **TS SDK**（搭配本地池狀態）                                      |

SDK 功能更豐富；交易 API 更簡單。兩者都包裝相同的底層 CPMM/CLMM/AMM v4 程式，因此產生的鏈上交換是相同的。

## 三個端點

### 1. `GET /compute/swap-base-in`

給定輸入金額，選擇路由並返回報價。

```
GET https://transaction-v1.raydium.io/compute/swap-base-in
  ?inputMint=So11111111111111111111111111111111111111112
  &outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
  &amount=1000000000
  &slippageBps=50
  &txVersion=V0
```

回應：

```json theme={null}
{
  "id": "b2e4...",
  "success": true,
  "version": "V1",
  "data": {
    "swapType": "BaseIn",
    "inputMint":  "So11111111111111111111111111111111111111112",
    "inputAmount":  "1000000000",
    "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "outputAmount": "165234567",
    "otherAmountThreshold": "164408394",
    "slippageBps": 50,
    "priceImpactPct": 0.0012,
    "referrerAmount": "0",
    "routePlan": [
      { "poolId": "58oQ...", "inputMint": "So11...", "outputMint": "USDC...", "feeAmount": "2500000", "feeMint": "So11..." }
    ]
  }
}
```

`id` 欄位是傳遞給下一個端點的不透明報價控制代碼。報價在約 30 秒內穩定；超過該時間後，重新報價。

### 2. `GET /compute/swap-base-out`

反向形式：「我想精確接收 N 個輸出；報價我所需的輸入。」

```
GET /compute/swap-base-out
  ?inputMint=<MINT_IN>
  &outputMint=<MINT_OUT>
  &amount=<DESIRED_OUTPUT_AMOUNT>
  &slippageBps=50
  &txVersion=V0
```

回應形狀與 `swap-base-in` 對稱；`amount` 欄位語義互換。

### 3. `POST /transaction/swap-base-in` 和 `/transaction/swap-base-out`

從第 1 步獲取報價並返回已簽署的版本化交易：

```
POST https://transaction-v1.raydium.io/transaction/swap-base-in
Content-Type: application/json

{
  "computeUnitPriceMicroLamports": "50000",
  "swapResponse": { ... 貼上來自 swap-base-in 的 data 物件 ... },
  "txVersion": "V0",
  "wallet": "<user_pubkey>",
  "wrapSol": true,
  "unwrapSol": false,
  "inputAccount": "<optional_token_account>",
  "outputAccount": "<optional_token_account>"
}
```

回應：

```json theme={null}
{
  "id": "9f1c...",
  "success": true,
  "version": "V1",
  "data": [
    { "transaction": "<base64-encoded-versioned-transaction>" }
  ]
}
```

如果交換需要設定（例如建立 ATA、包裝 SOL），可能返回多個交易。按順序簽署並發送。

## 最小端對端範例（Python）

```python theme={null}
import base64, requests
from solders.transaction import VersionedTransaction
from solders.keypair import Keypair
from solana.rpc.api import Client

rpc = Client("https://api.mainnet-beta.solana.com")
kp = Keypair.from_bytes(bytes([...]))    # your signer

SOL  = "So11111111111111111111111111111111111111112"
USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

quote = requests.get(
    "https://transaction-v1.raydium.io/compute/swap-base-in",
    params={
        "inputMint": SOL, "outputMint": USDC,
        "amount": 1_000_000_000, "slippageBps": 50, "txVersion": "V0",
    },
).json()

built = requests.post(
    "https://transaction-v1.raydium.io/transaction/swap-base-in",
    json={
        "computeUnitPriceMicroLamports": "50000",
        "swapResponse": quote,
        "txVersion": "V0",
        "wallet": str(kp.pubkey()),
        "wrapSol": True,
        "unwrapSol": False,
    },
).json()

for entry in built["data"]:
    raw = base64.b64decode(entry["transaction"])
    tx = VersionedTransaction.from_bytes(raw)
    tx.sign([kp])
    sig = rpc.send_raw_transaction(bytes(tx)).value
    print(f"Sent: {sig}")
```

這大約 20 行。使用 TS SDK 的等效程式碼約 30 行，但可讓你獲得更豐富的控制權（自訂路由選擇、每個池的計算單位預算、詳細錯誤中繼資料）。

## 路由和池選擇

交易 API 跨越**所有** Raydium 程式（CPMM、CLMM、AMM v4）路由，並為報價的規模選擇最佳執行。特徵：

* **支援多跳。** SOL→USDC 交換可以透過 wSOL→JUP→USDC 路由，如果這樣更便宜的話。
* **不支援同一程式內的多池拆分。** 單個報價恰好經過一個路徑；如果你想跨池拆分規模，請在客戶端進行（兩個報價、兩個交易）。
* **穩定 vs 集中。** 路由器優先使用 CLMM（當應有的流動性足夠時），對於長尾交易對則退回到 CPMM。
* **AMM v4 包含。** AMM v4 池包含在路由中，但僅在提供比 CPMM/CLMM 替代方案更好的定價時選擇。

要強制透過特定池路由，請改用 SDK — 交易 API 不公開池指定參數。

## 推薦者參數

附加 `&referrer=<wallet_pubkey>` 到計算端點以在交換中獲取 1% 推薦費。請參閱 [`user-flows/referrals-and-blinks`](/zh-Hant/user-flows/referrals-and-blinks) 了解語義。當存在時：

* 報價回應中的 `referrerAmount` 是將路由到推薦者的絕對金額（以輸入 mint 計）。
* 最終交易包含到推薦者 ATA 的額外 SPL 代幣轉移。

## 優先費用

建構請求中的 `computeUnitPriceMicroLamports` 設定返回的交易的優先費用。經驗法則：

* `50_000`（0.00005 lamports/CU × 200k CU ≈ 0.00001 SOL）：最少，適合非擁塞時刻。
* `200_000`：中等擁塞。
* `1_000_000`：嚴重擁塞。

適應性調整，先在 RPC 上呼叫 `getRecentPrioritizationFees` 並傳遞中位數。請參閱 [`integration-guides/priority-fee-tuning`](/zh-Hant/integration-guides/priority-fee-tuning)。

## 交易版本

* `"V0"` 返回具有常見帳戶查詢表的版本化（`MessageV0`）交易。更小、更快。**推薦。**
* `"LEGACY"` 返回舊版交易。更大；僅當你的錢包/基礎設施不處理 V0 時使用。

## 錯誤形狀

API 返回 HTTP 200 且 `success: false` 代表邏輯錯誤，HTTP 4xx/5xx 代表傳輸/基礎設施錯誤。

常見邏輯錯誤：

* `"No route found"` — 此規模下這兩個 mint 之間無路徑。減少 `amount` 或重新考慮交易對。
* `"Insufficient liquidity"` — 路由存在但會超過 `slippageBps`。擴大滑點。
* `"Quote expired"` — `swapResponse` 超過 30 秒。重新報價。
* `"Unsupported mint"` — mint 不在 Raydium 的範圍內（未上市或在已棄用程式上）。

## 速率限制

* **報價端點：** 每個 IP 每分鐘 120 個請求。
* **建構端點：** 每個 IP 每分鐘 60 個請求（伺服器成本更高）。
* 超過限制返回 HTTP 429 且帶有 `Retry-After` 標頭。

如需更高吞吐量，請聯絡 Raydium 開發者關係；提供聚合器層級金鑰。

## 整合商的架構模式

```
┌─────────────┐   報價   ┌───────────────┐   建構   ┌───────────────┐   簽署/發送   ┌──────────┐
│ 你的前端    │──────────►│ 交易 API      │──────────►│ 交易 API      │──────────────►│ Solana   │
│             │◄──────────│ /compute/...  │◄──────────│ /transaction/ │               │   RPC    │
└─────────────┘           └───────────────┘           └───────────────┘               └──────────┘
                              （無狀態）                  （無狀態）
```

一切都無狀態 — 你需要在報價呼叫和建構呼叫之間傳遞的唯一東西是報價回應體本身。

## 下一步

* [`sdk-api/typescript-sdk`](/zh-Hant/sdk-api/typescript-sdk) — 具有相同底層程式的更豐富程式介面。
* [`sdk-api/rest-api`](/zh-Hant/sdk-api/rest-api) — 讀取端端點（池資訊、mint 資訊）以補充交易 API 的寫入端。
* [`user-flows/swap`](/zh-Hant/user-flows/swap) — 端對端 UI 交換流程。
* [`integration-guides/aggregator`](/zh-Hant/integration-guides/aggregator) — 跨許多 DEX 路由的聚合器模式。

來源：

* `transaction-v1.raydium.io` 實時端點。
* Raydium UI 網路標籤檢查（相同介面消費）。