Exact Output Swaps¶

Exact Output quotes start with the amount the recipient must receive. The current flow uses wallet funding with a fixed input debit, gas_mode="pay_more" and funding_policy="wallet_fixed_exact_output". It does not draw an existing Vault balance to fund the swap. Successful output can exceed the target after integer rounding; read the confirmed amount for the actual result.

Availability depends on the target deployment. A temporary 503 does not establish whether an execution failed; preserve its identity and follow the retry rules below.

Request a Quote¶

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

Authentication: None.

Request Body¶

{
  "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"
}

Extra fields, floating-point amounts and noncanonical raw strings are rejected. Quote validity is at most 30 seconds and ends at least 30 seconds before the route expiration; always use returned expires_at.

Response¶

route_params.maxInputAmount and initialDepositAmount equal the fixed wallet debit. minOutputAmount is the requested target. Sign all returned Intent fields unchanged using the Intent type and this quote's signing_domain.

Execute¶

POST /api/v1/swap/exact-output

Authentication: EIP-712 Intent signature. If supplied, the API key must belong to the quote owner.

Request Body¶

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

A pending execution returns HTTP 202; other successful HTTP responses use 200. HTTP 200 alone does not mean the trade succeeded: inspect status.

Query Status¶

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

Authentication: API Key required; results are private to the quote owner. Prefer the query form for opaque/custom IDs and let your HTTP client encode the parameter. The path form only works for IDs suitable for one path segment: a valid ID such as a/b can return 404 even as a%2Fb, because the slash is decoded for routing. Such a 404 does not establish that the quote is absent.

Quoted/expired responses contain quote_uuid, execution_flow and status. Once a durable execution exists, responses additionally include order_id, route_uuid, intent_hash, transaction_hash, error_code, confirmed_recipient_output_raw and confirmed_actual_input_cost_raw; confirmation fields may be null while pending. Use the confirmed fields, not quote estimates, for final accounting.

Retries and Errors¶

• Retry a quote using the same quote_uuid and unchanged quote fields. A changed request bound to the same ID returns 409; an expired identity is not a new quote.
• Persist the exact execution body before sending it. After a timeout, 503 or pending result, query that ID and retry the identical signed body if needed. Changing signature bytes or permit content conflicts with an already claimed execution; see the encoding note below.
• Do not create a new quote ID to replace an execution whose outcome is unknown. Status reads remain available when new quote/execution admission is disabled.

A pending result can include automatic retry of a temporary submission failure when the service has established that no transaction was broadcast. It can also mean submission or chain recovery is still unresolved. Neither case asks the client to create a new quote or sign a replacement Intent; keep polling the original quote_uuid until a terminal result.

Typed 4xx errors use detail.code, including EXACT_OUTPUT_QUOTE_CONFLICT, EXACT_OUTPUT_EXECUTION_CONFLICT, EXACT_OUTPUT_PLAN_EXPIRED and EXACT_OUTPUT_INPUT_CAP_EXCEEDED. Shared Swap preflight errors can instead use detail.error_code or a string. 5xx failures normally use the generic 503 response; do not depend on an internal EXACT_OUTPUT_* code surviving that response.

Intent and permit length limits are listed under signature encoding. Preserve and retry the original signed body for compatibility: new execution claims normalize equivalent hex encodings to signature bytes, but changing the signature bytes or signed content changes the execution identity; historical claims can still use the original string fingerprint. The whole-body limit also applies.