Exact Output 兌換¶

Exact Output 從接收者必須收到的金額出發計算報價。當前流程使用錢包資金和固定輸入扣款，要求 gas_mode="pay_more"、funding_policy="wallet_fixed_exact_output"，不使用已有 Vault 餘額支付這筆兌換。整數取整後，成功到賬金額可能高於目標；實際結果以確認金額爲準。

可用性取決於目標部署。臨時 503 不能證明執行失敗，請保留請求身份並遵循下方重試規則。

請求報價¶

POST /api/v1/swap/exact-output/quote

身份驗證： 無。

請求體¶

{
  "quote_uuid": "client-quote-001",
  "from_token": "0x1111111111111111111111111111111111111111",
  "to_token": "0x2222222222222222222222222222222222222222",
  "to_amount": "1000000",
  "max_from_amount": "1200000",
  "owner_address": "0x3333333333333333333333333333333333333333",
  "recipient": "0x3333333333333333333333333333333333333333",
  "expiration": 1800000000,
  "gas_mode": "pay_more",
  "funding_policy": "wallet_fixed_exact_output"
}

以上地址僅爲佔位示例，請選擇已註冊代幣。使用 GET /api/v1/system/time 設置未來截止時間，並預留報價、簽名和執行時間。

欄位	必填	說明
`quote_uuid`	否	1–64 個不含空格的可見 ASCII 字符；省略時生成 UUID。建議自行提供並保存，以便識別報價重試
`from_token`、`to_token`	是	不同、非零、嚴格小寫的 `0x` EVM 地址
`owner_address`、`recipient`	是	非零小寫簽名/付款錢包與接收錢包
`to_amount`	是	目標輸出金額，正 uint256 十進制 raw 字串
`max_from_amount`	否	包含報價 gas 費用的最大錢包輸入扣款，正 raw 字串
`expiration`	是	Unix 秒數整數，`0 < expiration < 2**48`；報價後必須留有執行時間
`gas_mode`	是	`pay_more`
`funding_policy`	是	`wallet_fixed_exact_output`

額外欄位、浮點金額和非規範 raw 字串會被拒絕。報價有效期最長 30 秒，且至少早於路由截止時間 30 秒結束；請始終使用回傳的 expires_at。

回應¶

欄位	說明
`quote_uuid`	執行和狀態查詢使用的標識符
`execution_flow`	`exact_output_fok_v1`
`status`	`quoted`
`expires_at`	報價過期的 Unix 秒數
`funding_policy`、`gas_mode`	已接受的資金與 gas 選項
`route_params`	必須原樣簽名的 EIP-712 Intent 欄位；其中 `uuid` 是簽名 uint256，不是 `quote_uuid`
`signing_domain`	本次報價應使用的 EIP-712 域
`permit`	資金授權元數據，沿用 Swap 的 permit/approve 分支
`fee_breakdown.quoted_gas_fee_input_raw`	以輸入代幣 raw 單位計價的 gas 費
`fee_breakdown.wallet_debit_raw`	固定的錢包總扣款
`fee_breakdown.expected_recipient_output_raw`	預期輸出，不低於 `to_amount`
`fee_breakdown.confirmed_recipient_output_raw`	報價時爲 `null`
`fee_breakdown.gas_fee_usd`	gas 的美元成本，十進制字串

route_params.maxInputAmount 和 initialDepositAmount 均等於固定錢包扣款。minOutputAmount 是請求的目標金額。使用 Intent 類型和本次報價的 signing_domain，原樣簽署所有回傳欄位。

執行¶

POST /api/v1/swap/exact-output

身份驗證： EIP-712 Intent 簽名。如攜帶 API Key，必須屬於報價所有者。

請求體¶

{
  "quote_uuid": "client-quote-001",
  "signature": "0x...",
  "permit_signature": "0x...",
  "permit_deadline": 1800000000
}

quote_uuid 和 signature 必填。只有已存報價要求且支援 EIP-2612 permit 時，才提交 permit_signature / permit_deadline。否則完成 approve 流程並省略這兩個欄位；多餘的 permit 欄位會被拒絕。

待確認執行回傳 HTTP 202；其他正常 HTTP 回應使用 200。HTTP 200 本身不表示交易成功，必須檢查 status。

查詢狀態¶

GET /api/v1/swap/exact-output/{quote_uuid}
GET /api/v1/swap/exact-output?quote_uuid=client-quote-001

身份驗證： 需要 API Key，結果僅對報價所有者可見。自訂或不透明 ID 優先使用查詢參數形式，並由 HTTP 客戶端編碼參數。路徑形式僅適用於單路徑段 ID：合法的 a/b 即使編碼為 a%2Fb 也可能因路由解碼回傳 404，不能據此認定報價不存在。

狀態	含義
`quoted`	報價存在且仍有效，尚無確認的執行結果
`expired`	未執行報價已失效
`pending`	執行結果尚未確定
`succeeded`	成功結算已確認
`failed`	執行已進入終態失敗

報價/過期回應包含 quote_uuid、execution_flow、status。執行記錄持久化後，還包含 order_id、route_uuid、intent_hash、transaction_hash、error_code、confirmed_recipient_output_raw、confirmed_actual_input_cost_raw；待確認時相關確認欄位可能爲 null。最終記賬應使用確認欄位，不能使用報價估計值。

重試與錯誤¶

報價重試使用同一 quote_uuid 和完全相同的報價欄位。相同 ID 綁定不同請求會回傳 409；過期身份不能作爲新報價複用。
發送前保存完整執行請求體。超時、503 或 pending 後查詢原 ID，必要時重試完全相同的簽名請求。改變簽名字節或 permit 內容會與已認領執行衝突；編碼說明見下文。
執行結果未知時，不要創建新報價 ID 替代原執行。關閉新報價/執行准入時，狀態讀取仍保留。

pending 可能包含服務在確認尚未廣播交易後，對臨時提交失敗進行的自動重試，也可能表示提交或鏈上恢復結果尚不確定。這兩種情況都不要求客戶端創建新報價或重新簽署替代 Intent；應持續查詢原 quote_uuid，直到得到終態結果。

HTTP	含義 / 處理
400	Intent/permit 簽名無效、多餘 permit 或資金預檢失敗
401	狀態查詢缺少或使用無效 API Key
404	報價不存在
409	報價/執行身份衝突；部分准入前 permit nonce 衝突需重新報價
410	計劃或報價過期
422	請求無效、超出輸入上限或類型化報價拒絕
429	限流；存在 `Retry-After` 時遵循該值
503	臨時不可用或關閉新准入；保留 ID 並查詢狀態

類型化 4xx 使用 detail.code，例如 EXACT_OUTPUT_QUOTE_CONFLICT、EXACT_OUTPUT_EXECUTION_CONFLICT、EXACT_OUTPUT_PLAN_EXPIRED、EXACT_OUTPUT_INPUT_CAP_EXCEEDED。共用的 Swap 預檢錯誤也可能使用 detail.error_code 或字串。5xx 通常回傳通用 503 回應，不能依賴內部 EXACT_OUTPUT_* 碼一定出現在該回應中。

Intent 與 permit 長度限制見簽名編碼。為保持相容，應保存並原樣重試簽名請求：新執行認領將等價的十六進位編碼正規化為簽名字節，但改變簽名字節或簽名內容會改變執行身分；歷史認領仍可能使用原字串指紋。同時遵守整體請求體上限。