---
title: "POST /v2/order-bundles/prepare-return"
method: POST
path: "/v2/order-bundles/prepare-return"
---

# POST /v2/order-bundles/prepare-return

`POST /v2/order-bundles/prepare-return`

## Request

- Base URL: `https://api.arbital.xyz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.arbital.xyz/v2/order-bundles/prepare-return`
- Auth: HTTP bearer

Prepare a fresh exact-amount return quote from verified funding and, when supplied, an owned terminal order with reconciled fill receipts. No-order path requires the client checkpoint to prove no placement was attempted. Client must stop on lost/ambiguous checkpoint or any prior return attempt; API is not a replay-proof allocation ledger. Remaining amount is bounded by funding and live balance; it never sweeps the wallet.

## Request body

- OrderBundleReturnContextV2
  - `terms` OrderBundleTermsV2, required: Client checkpoint terms for Solana USDC to Base USDC to an ERC-20 limit buy. Terms are untrusted inputs, not a signed allocation or server workflow. Expiry is future UTC seconds within 30 days for preparation; return recovery may use the original expired terms.
    - `destination_chain_id` '8453', required
    - `source_budget_usdc_atomic` string, required
    - `target_asset` string, required
    - `limit_price_usd` string, required: Positive USD limit price with at most 18 integer and 18 fractional digits. Exponents and leading zeroes are rejected.
    - `expire_time` string, date-time, required: Valid future UTC timestamp at whole-second precision, at most 30 days from preparation. The server checks calendar validity and rejects expired timestamps.
  - `funding_request_id` string, required
  - `source_transaction_id` string, required
  - `order_id` string

## Response `200`

Stateless client preparation or explicit pending/manual-review state

- union
  - OrderBundleReturnReadyV2: Fresh exact-amount quote for the user to sign. Does not reserve funds, prove original bundle/order causality, or exclude a prior return attempt. The client must hold the original placement acknowledgment and stop after any return attempt or ambiguous/lost checkpoint.
    - `state` 'ready', required
    - `return_quote` EvmToSvmQuoteV2, required: Thin Relay EVM-to-Solana quote. The client signs and submits the returned approve and deposit calls. The backend does not sponsor, broadcast, or admit a gasless submission.
      - `authorization_requirement` 'interactive_client_signature', required
      - `destination_asset` 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', required
      - `destination_chain_id` 'solana', required
      - `dynamic_slippage_bps` integer, required
      - `exact_input_atomic` string, required
      - `execution_speed` 'normal', required
      - `expected_output_atomic` string, required
      - `expires_at_unix_ms` integer, required
      - `fees` ExecutionQuoteFeeV2[], required
        - `amount_atomic` string, required
        - `asset` string, required
        - `certainty` 'exact' | 'estimated', required
        - `kind` 'application', required
      - `minimum_output_atomic` string, required
      - `operation` 'evm_to_svm', required
      - `platform_fee_bps` integer, nullable, required
      - `prepared` PreparedEvmRelayQuoteV2, required: Relay approve and deposit calls. The client wraps them in an ERC-4337 UserOperation, obtains Pimlico paymaster fields through the edge bundler, submits the sponsored UserOp, and indexes the landed origin hash with Relay. The backend does not submit these calls and does not return a gasless capability.
        - `destination_address` string, required
        - `relay_status_endpoint` string, uri, required
        - `relay_swap_id` string, required
        - `transactions` PreparedEvmTransactionV2[], required
          - `data` string, required
          - `step` 'approve' | 'deposit', required
          - `to` string, required
          - `value` string, required
      - `priority_fee_lamports` unknown, required
      - `quote_id` string, required
      - `source_asset` string, required
      - `source_balance_observation` SourceBalanceObservationV2: The controlled wallet's live balance of the sold asset as the backend observed it during this quote request. It is the evidence behind the sell amount and the only balance a client may treat as sell authority. It is present on Solana/EVM same_chain_sell and evm_to_svm quotes and absent on buys.
        - `amount_atomic` string, required
        - `asset` string, required
        - `chain_id` string, required: `solana` for Solana same-chain sells; the numeric EVM chain ID for EVM limit sells or evm_to_svm.
        - `commitment` 'confirmed' | 'latest', required: How final the balance read was: `confirmed` for Solana balances read at confirmed commitment; `latest` for EVM balances read from the latest block, which can reorganize.
        - `observed_at_unix_ms` integer, required
        - `slot` string: Solana slot the balance was read at. Absent for EVM origins.
      - `source_chain_id` string, required
      - `swap_impact_bps` integer, nullable, required
    - `remaining_atomic` string, required
    - `accounting` object, required
      - `funded_atomic` string, required
      - `order_input_atomic` string, required
      - `confirmed_spent_atomic` string, required
      - `live_balance_atomic` string, required
      - `allocation` 'client_checkpoint', required
  - OrderBundleWaitV2
    - `state` 'pending' | 'needs_review', required
    - `reason` string, required
  - object
    - `state` 'not_required', required
    - `reason` 'no_remaining_usdc', required

## Other responses

- `400`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.
- `401`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.
- `403`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.
- `409`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.
- `503`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.

---

[API](https://skmtc.dev/arbital/apis/arbital-api.md) - [All operations](https://skmtc.dev/arbital/apis/arbital-api/llms.txt) - [OpenAPI document](https://skmtc.dev/arbital/apis/arbital-api/revisions/bb0185edf43a?raw)