Track Swap Status

​

Lifecycle model

• 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. Terminal. Same-chain FAILED comes from the origin send-transaction only. Cross-chain FAILED can appear before refund fields exist.

​

Query get_swap_status

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": "<ORGANIZATION_ID>",
    "swapRequestId": "<SWAP_REQUEST_ID>"
  }'

const status = await client.request("/public/v1/query/get_swap_status", {
  organizationId: "<ORGANIZATION_ID>",
  swapRequestId: "<SWAP_REQUEST_ID>",
});

{
  "status": "PENDING | COMPLETED | FAILED",
  "swapKind": "SAME_CHAIN | CROSS_CHAIN",
  "provider": "<PROVIDER>",
  "inputToken": "<CAIP-19>",
  "outputToken": "<CAIP-19>",
  "inputAmount": "<RAW_AMOUNT>",
  "originTxHash": "<ORIGIN_TX_HASH>",
  "destinationTxHashes": ["<TX_HASH_ON_COMPLETED_CROSS_CHAIN_ONLY>"],
  "outputAmount": "<ACTUAL_OUTPUT_ON_COMPLETED>",
  "refund": {
    "asset": "<CAIP-19_ON_FAILED>",
    "amount": "<RAW_AMOUNT_ON_FAILED>",
    "txHash": "<TX_HASH_ON_FAILED>"
  },
  "error": {
    "reason": "<ORIGIN_TRANSACTION_FAILED | PROVIDER_FILL_FAILED>",
    "message": "<HUMAN_READABLE_DETAIL>",
    "originTxError": {
      "message": "<REVERT_MESSAGE>",
      "revertChain": [],
      "eth": {},
      "solana": {}
    },
    "providerReason": "<PROVIDER_SPECIFIC_REASON>"
  },
  "destinationAddress": "<OUTPUT_RECIPIENT>",
  "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. Always present.
• 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.
• destinationTxHashes: array of destination-chain transaction hashes on COMPLETED. Cross-chain only.
• destinationAddress: address that receives the output asset. For EVM ↔ SVM this is the destinationAddress you set on quote and execute. For same-protocol routes it is the swapping wallet.
• outputAmount: actual amount received, on COMPLETED. May lag the status transition by seconds while the monitor fetches the final settled amount.
• refund: present on cross-chain FAILED when funds moved and came back. Contains asset (CAIP-19), amount (raw onchain units), and optional txHash. Omitted for origin failures and same-chain swaps. See What FAILED means.
• error: present on FAILED. Contains reason (ORIGIN_TRANSACTION_FAILED or PROVIDER_FILL_FAILED), message (human-readable detail), originTxError (decoded revert detail, origin failures only), and providerReason (provider-specific detail, fill failures only). See What FAILED means.
• updatedAt: last observed state change, as a Unix timestamp in milliseconds (stringified).

​

Same-chain vs. cross-chain differences

• Timing. Same-chain swaps reach a terminal state within roughly one block time of the origin chain. Cross-chain swaps can take tens of seconds to several minutes depending on the route. Each quote’s estimatedTimeSeconds is the per-swap estimate.
• Field population. destinationTxHashes is populated only for cross-chain COMPLETED swaps. Same-chain outcomes are fully described by originTxHash: on COMPLETED, that transaction delivered the output; on FAILED, either the transaction reverted or — if originTxHash is absent — the swap failed before broadcast and nothing moved onchain. Same-chain FAILED never includes refund or PROVIDER_FILL_FAILED.

​

What FAILED means

• Same-chain. FAILED comes from the origin send-transaction only. error.reason is ORIGIN_TRANSACTION_FAILED. The response never includes refund or PROVIDER_FILL_FAILED.
• Cross-chain. FAILED can come from the origin send-transaction (ORIGIN_TRANSACTION_FAILED) or from a provider fill failure after origin success (PROVIDER_FILL_FAILED). FAILED can appear before refund fields exist. Keep polling if you need refund. PENDING means the destination leg can still fill — it does not mean a refund is in flight.

• error.reason — why it failed: ORIGIN_TRANSACTION_FAILED (the origin transaction failed pre-flight simulation or reverted onchain) or PROVIDER_FILL_FAILED (the origin transaction succeeded but the provider could not fill). error.message and, for origin failures, error.originTxError carry the decoded detail, including the full revert chain.
• refund — present on cross-chain FAILED when funds moved and came back: refund.asset (CAIP-19), refund.amount (raw onchain units), and optional refund.txHash. The refunded asset can differ from the original input if the route included an origin-side swap, and it lands on the origin chain.

• A refund is reduced by refund gas and any origin-side swap losses; it will not equal the original input.
• A re-swap is a new swap: new quote, new fees, new slippage.
• If the original destination was another chain, the re-swap is again cross-chain.

​

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.

​

Next steps

• End-to-end example: full flow from enable to confirmation.
• Execute a swap: request semantics that generate the poll handle.