> ## Documentation Index
> Fetch the complete documentation index at: https://turnkey-0e7c1f5b-swaps-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Swap Status

> Poll swap lifecycle from broadcast to settlement using get_swap_status. Same-chain and cross-chain operations normalize to a single PENDING/COMPLETED/FAILED model.

`execute_swap` returns a poll handle. Query `get_swap_status` with that handle to observe the full lifecycle. Same-chain and cross-chain swaps share the same endpoint and the same response shape. The endpoint normalizes provider-specific state machines to three states: `PENDING`, `COMPLETED`, `FAILED`.

## Lifecycle model

Turnkey normalizes swap lifecycle to three states across same-chain and cross-chain routes:

* **PENDING**: still in flight. Broadcast pending, origin transaction not yet included, or (cross-chain) destination-side execution not yet settled.
* **COMPLETED**: the user received the destination asset. Terminal, happy path.
* **FAILED**: the swap will not fill as intended. Reported only when Turnkey knows what the user holds. Terminal.

Intermediate provider states (`bridge_pending`, `delayed`, `submitted`, and so on) collapse into `PENDING` on purpose. Every state maps to exactly one customer action: `PENDING` means wait, `COMPLETED` means you got the output, `FAILED` means look at what you hold and consider re-swapping.

## Query get\_swap\_status

<ParamField body="organizationId" type="string" required>
  Unique identifier of the sub-organization that executed the swap.
</ParamField>

<ParamField body="sendTransactionStatusId" type="string" required>
  The poll handle returned from `execute_swap`.
</ParamField>

```bash title="cURL" theme={"system"}
curl --request POST \
  --url https://api.turnkey.com/public/v1/query/get_swap_status \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <string> (see Stamps)" \
  --data '{
    "organizationId": "<SUB_ORGANIZATION_ID>",
    "sendTransactionStatusId": "<SEND_TRANSACTION_STATUS_ID>"
  }'
```

```javascript title="JavaScript" theme={"system"}
const status = await client.request("/public/v1/query/get_swap_status", {
  organizationId: "<SUB_ORGANIZATION_ID>",
  sendTransactionStatusId: "<SEND_TRANSACTION_STATUS_ID>",
});
```

Response:

```json theme={"system"}
{
  "status": "PENDING | COMPLETED | FAILED",
  "swapKind": "SAME_CHAIN | CROSS_CHAIN",
  "provider": "<PROVIDER>",
  "inputToken": "<CAIP-19>",
  "outputToken": "<CAIP-19>",
  "inputAmount": "<RAW_AMOUNT>",
  "originTxHash": "<ORIGIN_TX_HASH>",
  "destinationTxHash": "<TX_HASH_ON_COMPLETED_CROSS_CHAIN_ONLY>",
  "outputAmount": "<ACTUAL_OUTPUT_ON_COMPLETED>",
  "settledAsset": "<CAIP-19_ON_FAILED>",
  "settledAmount": "<RAW_AMOUNT_ON_FAILED>",
  "settlementTxHash": "<TX_HASH_ON_FAILED>",
  "providerStatus": "<RAW_PROVIDER_STATUS_CROSS_CHAIN_ONLY>",
  "updatedAt": "<UNIX_MS_TIMESTAMP>"
}
```

### Response fields

* `status`: normalized state. `PENDING`, `COMPLETED`, or `FAILED`.
* `swapKind`: `SAME_CHAIN` or `CROSS_CHAIN`. Set at execute time; does not change.
* `provider`: the provider that executed the swap. Present when known.
* `inputToken`, `outputToken`, `inputAmount`: echoed from the execute intent.
* `originTxHash`: origin-chain transaction hash. Present once the swap is broadcast, for both same-chain and cross-chain routes.
* `destinationTxHash`: destination-chain transaction on `COMPLETED`. Cross-chain only.
* `outputAmount`: actual amount received, on `COMPLETED`. May lag the `status` transition by seconds while the monitor fetches the final settled amount.
* `settledAsset`, `settledAmount`, `settlementTxHash`: on `FAILED`. See [What FAILED means](#what-failed-means).
* `providerStatus`: raw provider status passthrough for UI use. Cross-chain only. Not normative.
* `updatedAt`: last observed state change, as a Unix timestamp in milliseconds (stringified).

## Same-chain vs. cross-chain differences

The response shape is identical. Only two behaviors differ in practice:

* **Timing.** Same-chain reaches a terminal state within one block time. Cross-chain can take tens of seconds to several minutes depending on the route and bridge.
* **Field population.** `destinationTxHash` and `providerStatus` are cross-chain only. On same-chain `FAILED`, the settled triple derives directly from the origin transaction: `settledAsset = inputToken`, `settledAmount = inputAmount`, `settlementTxHash = <revert hash>` (nothing moved on-chain in a swap sense).

Use `swapKind` in the response to branch client-side handling only when it matters.

## What FAILED means

`FAILED` is reported only when Turnkey knows what the user holds. A bridge failure with a refund still in flight stays `PENDING` until the refund lands (or is confirmed impossible).

On `FAILED`, three fields describe the outcome:

* `settledAsset` (CAIP-19): the asset the user ended up with.
* `settledAmount`: raw on-chain amount of that asset.
* `settlementTxHash`: the on-chain transaction that settled the funds.

Provider-specific recovery scenarios normalize to this triple:

* **Provider refunded on the origin chain**: `settledAsset` is the origin-chain refund token. It may differ from the original input token if the route included an origin-side swap.
* **Funds never left the user** (e.g., origin transaction reverted): `settledAsset` equals `inputToken`, `settledAmount` equals `inputAmount`, `settlementTxHash` is the origin transaction hash.
* **Nothing was recoverable**: `settledAsset` is `null`. Internal alerts fire on this state.

If `settledAsset` is non-null, you can call [`execute_swap`](/features/transaction-management/swap/execute-swap) again with the settled asset as the new input to re-attempt. Caveats worth surfacing to end users:

* The refunded amount is reduced by refund gas and any origin-side swap losses.
* A re-swap pays its own fees and slippage.
* If the refund landed on the origin chain and the original destination was on a different chain, the re-swap is again cross-chain.

<Warning>
  `FAILED` with `settledAsset: null` means Turnkey could not recover funds through the provider's automated flows. Contact support if you encounter this state.
</Warning>

## Polling cadence

* **Same-chain**: poll every \~1 second while `PENDING`. Typically settles within one block time.
* **Cross-chain**: poll every 5 to 10 seconds while `PENDING`. Settlement can take from tens of seconds to several minutes depending on route.

Websocket and event-driven updates are on the roadmap and will replace polling for cross-chain lifecycles.

## Next steps

* [End-to-end example](/features/transaction-management/swap/end-to-end-example): full flow from enable to confirmation.
* [Execute a swap](/features/transaction-management/swap/execute-swap): request semantics that generate the poll handle.