From e38b31333a4d9c07b3c36aa7cbc15ac393c8e551 Mon Sep 17 00:00:00 2001 From: zer0dot Date: Fri, 31 Oct 2025 16:50:55 -0400 Subject: [PATCH 1/4] feat: cross chain status api docs --- .../cross-chain-swap-tokens/api.mdx | 53 -------- .../cross-chain-swap-tokens/index.mdx | 114 ++++++++++++++++++ 2 files changed, 114 insertions(+), 53 deletions(-) diff --git a/docs/pages/transactions/cross-chain-swap-tokens/api.mdx b/docs/pages/transactions/cross-chain-swap-tokens/api.mdx index 508b3e7b6e..73c8582e24 100644 --- a/docs/pages/transactions/cross-chain-swap-tokens/api.mdx +++ b/docs/pages/transactions/cross-chain-swap-tokens/api.mdx @@ -166,57 +166,4 @@ For other potential responses, [check out the API reference!](/docs/wallets/api- - - -Use the `wallet_getCallsStatus` endpoint to check the status of your cross-chain swap. Cross-chain swaps may take longer than single-chain swaps due to cross-chain messaging. - -```bash -curl -X POST https://api.g.alchemy.com/v2/{API_KEY} \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "method": "wallet_getCallsStatus", - "params": [ - [ - "{CALL_ID_FROM_STEP_2_OR_STEP_4}" - ] - ], - "id": 1 - }' -``` - -This returns: - -```json -{ - "id": "1", - "jsonrpc": "2.0", - "result": { - "id": "CALL_ID", - "chainId": "SOURCE_CHAIN_ID", - "atomic": true, - "status": 200, - "receipts": [...] - } -} -``` - -Cross-chain swaps have additional status codes to reflect the cross-chain nature of the transaction: - -| Code | Title | -| ---- | ----------------------- | -| 100 | Pending | -| 120 | Cross-Chain In Progress | -| 200 | Confirmed | -| 400 | Offchain Failure | -| 410 | Cross-chain Refund | -| 500 | Onchain Failure | -| 600 | Partial Onchain Failure | - -To get your transaction hash, you can access `result.receipts[0].transactionHash`. - -For more details, check out [the API reference!](/docs/wallets/api-reference/smart-wallets/wallet-api-endpoints/wallet-api-endpoints/wallet-get-calls-status) - - - diff --git a/docs/pages/transactions/cross-chain-swap-tokens/index.mdx b/docs/pages/transactions/cross-chain-swap-tokens/index.mdx index f924356481..776a7860db 100644 --- a/docs/pages/transactions/cross-chain-swap-tokens/index.mdx +++ b/docs/pages/transactions/cross-chain-swap-tokens/index.mdx @@ -69,6 +69,120 @@ Before you begin, ensure you have: +# Tracking a cross-chain swap + +After sending your cross-chain swap, you can track its progress using the `wallet_getCrossChainStatus_v0` endpoint. This endpoint provides detailed status information for both the origin and destination transactions. + + + **Note**: The `wallet_getCrossChainStatus_v0` endpoint is currently available + via API only. SDK support coming soon. + + +## Use the status endpoint + +Pass the `callId` from your swap request to check the current status: + +```bash +curl -X POST https://api.g.alchemy.com/v2/{API_KEY} \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "method": "wallet_getCrossChainStatus_v0", + "params": [ + "{CALL_ID}" + ], + "id": 1 + }' +``` + +## Response format + +The response type depends on whether your transaction is same-chain or cross-chain. + +### Cross-chain response + +For cross-chain swaps, the response includes both origin and destination transaction details: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "type": "cross-chain", + "id": "0x...", + "status": 120, + "originTransaction": { + "chainId": "0xa4b1", + "status": 200, + "receipt": { + "status": "0x1", + "blockHash": "0x...", + "blockNumber": "0x...", + "gasUsed": "0x...", + "transactionHash": "0x...", + "logs": [] + } + }, + "destinationTransaction": { + "chainId": "0x1", + "status": 100 + } + } +} +``` + +### Same-chain response + +For same-chain transactions, the response includes origin transaction details only: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "type": "same-chain", + "id": "0x...", + "status": 200, + "originTransaction": { + "chainId": "0x1", + "status": 200, + "receipt": { + "status": "0x1", + "blockHash": "0x...", + "blockNumber": "0x...", + "gasUsed": "0x...", + "transactionHash": "0x...", + "logs": [] + } + } + } +} +``` + +## Status codes + +The `status` field indicates the current state of your transaction: + +| Code | Status | Description | +| ---- | ------------------------------------ | ------------------------------------------------------------- | +| 100 | Pending | Transaction received but not confirmed onchain | +| 110 | Preconfirmed | Transaction preconfirmed onchain | +| 115 | Preconfirmed Onchain Failure | Transaction reverted completely in preconfirmation | +| 116 | Preconfirmed Partial Onchain Failure | Transaction reverted partially in preconfirmation | +| 120 | Cross-Chain In Progress | Origin transaction confirmed, destination transaction pending | +| 200 | Confirmed | Transaction confirmed onchain without reverts | +| 400 | Offchain Failure | Transaction failed offchain and will not be retried | +| 410 | Cross-Chain Refunded | Cross-chain transaction failed and was refunded | +| 500 | Onchain Failure | Transaction reverted completely onchain | +| 600 | Partial Onchain Failure | Transaction reverted partially onchain | + +## Get transaction hashes + +To access transaction hashes from the response: + +- **Origin transaction hash**: `result.originTransaction.receipt.transactionHash` +- **Destination transaction hash**: `result.destinationTransaction.receipt.transactionHash` (when available) + # FAQs ## What chains are supported for cross-chain swaps? From c450ee42b28b16577e61a7a39d91e6daf7e91a6a Mon Sep 17 00:00:00 2001 From: zer0dot Date: Fri, 31 Oct 2025 17:40:30 -0400 Subject: [PATCH 2/4] feat: update docs to clarify usage of getCallsStatus versus getCrossChainStatus --- .../cross-chain-swap-tokens/api.mdx | 48 +++++++++++++++++++ .../cross-chain-swap-tokens/client.mdx | 4 ++ .../cross-chain-swap-tokens/index.mdx | 22 +++++++-- .../cross-chain-swap-tokens/react.mdx | 16 ++----- 4 files changed, 73 insertions(+), 17 deletions(-) diff --git a/docs/pages/transactions/cross-chain-swap-tokens/api.mdx b/docs/pages/transactions/cross-chain-swap-tokens/api.mdx index 73c8582e24..90e2bc766c 100644 --- a/docs/pages/transactions/cross-chain-swap-tokens/api.mdx +++ b/docs/pages/transactions/cross-chain-swap-tokens/api.mdx @@ -166,4 +166,52 @@ For other potential responses, [check out the API reference!](/docs/wallets/api- + + + + We recommend using `wallet_getCrossChainStatus_v0` for richer data including + separate origin and destination transaction details. [See the tracking + documentation](/wallets/transactions/cross-chain-swap-tokens#tracking-a-cross-chain-swap) + for more details. + + +You can use the `wallet_getCallsStatus` endpoint to check the status of your cross-chain swap. Cross-chain swaps may take longer than single-chain swaps due to cross-chain messaging. + +```bash +curl -X POST https://api.g.alchemy.com/v2/{API_KEY} \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "method": "wallet_getCallsStatus", + "params": [ + [ + "{CALL_ID_FROM_STEP_2_OR_STEP_4}" + ] + ], + "id": 1 + }' +``` + +This returns: + +```json +{ + "id": "1", + "jsonrpc": "2.0", + "result": { + "id": "CALL_ID", + "chainId": "SOURCE_CHAIN_ID", + "atomic": true, + "status": 200, + "receipts": [...] + } +} +``` + +To get your transaction hash, you can access `result.receipts[0].transactionHash`. + +For status codes and more details on tracking cross-chain swaps, see the [tracking documentation](/wallets/transactions/cross-chain-swap-tokens#tracking-a-cross-chain-swap). + + + diff --git a/docs/pages/transactions/cross-chain-swap-tokens/client.mdx b/docs/pages/transactions/cross-chain-swap-tokens/client.mdx index d45ff3763c..67d6247057 100644 --- a/docs/pages/transactions/cross-chain-swap-tokens/client.mdx +++ b/docs/pages/transactions/cross-chain-swap-tokens/client.mdx @@ -106,3 +106,7 @@ export const client = createSmartWalletClient({ ``` + +## Status codes + +For status codes and more details on tracking cross-chain swaps, see the [tracking documentation](/wallets/transactions/cross-chain-swap-tokens#tracking-a-cross-chain-swap). diff --git a/docs/pages/transactions/cross-chain-swap-tokens/index.mdx b/docs/pages/transactions/cross-chain-swap-tokens/index.mdx index 776a7860db..5b041ba6eb 100644 --- a/docs/pages/transactions/cross-chain-swap-tokens/index.mdx +++ b/docs/pages/transactions/cross-chain-swap-tokens/index.mdx @@ -78,6 +78,12 @@ After sending your cross-chain swap, you can track its progress using the `walle via API only. SDK support coming soon. + + The `wallet_getCrossChainStatus_v0` endpoint is in beta. Note that there may + be changes in the future to simplify the endpoint. We will let you know + if/when that happens. + + ## Use the status endpoint Pass the `callId` from your swap request to check the current status: @@ -210,11 +216,19 @@ The expiry is an informational indicator of when you can expect to be able to pr ## What are the different status codes for cross-chain swaps? -Cross-chain swaps may have additional status codes beyond standard transaction statuses to reflect the cross-chain nature of the transaction. These are: +Cross-chain swaps support comprehensive status tracking. See the [tracking documentation](/wallets/transactions/cross-chain-swap-tokens#status-codes) for a complete list of status codes including: -- 120: Cross-chain in progress -- 410: Cross-chain refund +- 100: Pending +- 110: Preconfirmed +- 115: Preconfirmed Onchain Failure +- 116: Preconfirmed Partial Onchain Failure +- 120: Cross-Chain In Progress +- 200: Confirmed +- 400: Offchain Failure +- 410: Cross-Chain Refunded +- 500: Onchain Failure +- 600: Partial Onchain Failure ## When is a CallId returned from `wallet_requestQuote_v0`? -Any time you’re requesting a cross-chain quote via `wallet_requestQuote_v0` , a `callId` is returned. This `callId` includes important data for cross-chain tracking. You can use this just like any other `callId` in `wallet_getCallsStatus`! +Any time you're requesting a cross-chain quote via `wallet_requestQuote_v0` , a `callId` is returned. This `callId` includes important data for cross-chain tracking. You can use this just like any other `callId` in `wallet_getCallsStatus` or `wallet_getCrossChainStatus_v0`! diff --git a/docs/pages/transactions/cross-chain-swap-tokens/react.mdx b/docs/pages/transactions/cross-chain-swap-tokens/react.mdx index 7db2430a21..779a39ae99 100644 --- a/docs/pages/transactions/cross-chain-swap-tokens/react.mdx +++ b/docs/pages/transactions/cross-chain-swap-tokens/react.mdx @@ -135,19 +135,9 @@ export default function CrossChainSwap() { Cross-chain swaps take longer than single-chain swaps due to cross-chain messaging and confirmation requirements. -## Cross-chain status codes - -Cross-chain swaps have additional status codes to reflect the cross-chain nature: - -| Code | Status | -| ------- | --------------------------- | -| 100 | Pending | -| **120** | **Cross-Chain In Progress** | -| 200 | Confirmed | -| 400 | Offchain Failure | -| **410** | **Cross-chain Refund** | -| 500 | Onchain Failure | -| 600 | Partial Onchain Failure | +## Status codes + +For status codes and more details on tracking cross-chain swaps, see the [tracking documentation](/wallets/transactions/cross-chain-swap-tokens#tracking-a-cross-chain-swap). ## Swap options From 14881c5909f2c1c34ef51760176c167f39806861 Mon Sep 17 00:00:00 2001 From: zer0dot Date: Fri, 31 Oct 2025 17:41:24 -0400 Subject: [PATCH 3/4] fix: dedupe status codes --- docs/pages/transactions/cross-chain-swap-tokens/index.mdx | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/pages/transactions/cross-chain-swap-tokens/index.mdx b/docs/pages/transactions/cross-chain-swap-tokens/index.mdx index 5b041ba6eb..0105ea1af0 100644 --- a/docs/pages/transactions/cross-chain-swap-tokens/index.mdx +++ b/docs/pages/transactions/cross-chain-swap-tokens/index.mdx @@ -218,16 +218,9 @@ The expiry is an informational indicator of when you can expect to be able to pr Cross-chain swaps support comprehensive status tracking. See the [tracking documentation](/wallets/transactions/cross-chain-swap-tokens#status-codes) for a complete list of status codes including: -- 100: Pending -- 110: Preconfirmed -- 115: Preconfirmed Onchain Failure -- 116: Preconfirmed Partial Onchain Failure - 120: Cross-Chain In Progress -- 200: Confirmed - 400: Offchain Failure - 410: Cross-Chain Refunded -- 500: Onchain Failure -- 600: Partial Onchain Failure ## When is a CallId returned from `wallet_requestQuote_v0`? From 365784cdca6398613c25d45d3383602b4d389ce5 Mon Sep 17 00:00:00 2001 From: zer0dot Date: Tue, 4 Nov 2025 16:32:17 -0500 Subject: [PATCH 4/4] fix: remove obsolete info block --- docs-site | 2 +- docs/pages/transactions/cross-chain-swap-tokens/index.mdx | 5 ----- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/docs-site b/docs-site index ea92715994..053b12a9cb 160000 --- a/docs-site +++ b/docs-site @@ -1 +1 @@ -Subproject commit ea927159948bdc2cdfadd91253160e7250b83e63 +Subproject commit 053b12a9cb4c6b34eec128f0717908d7965a5458 diff --git a/docs/pages/transactions/cross-chain-swap-tokens/index.mdx b/docs/pages/transactions/cross-chain-swap-tokens/index.mdx index 0105ea1af0..b37bcda16d 100644 --- a/docs/pages/transactions/cross-chain-swap-tokens/index.mdx +++ b/docs/pages/transactions/cross-chain-swap-tokens/index.mdx @@ -52,11 +52,6 @@ Before you begin, ensure you have: - **Important**: You'll need to send these tokens to your smart wallet address to be able to swap! - A signer to own the account and sign messages - - Note that Cross-chain Swaps are currently supported via direct APIs and the - SDK. React support coming soon! - -