From 35cc78391c2b4d6815e84f5c161fb8cb80888f9d Mon Sep 17 00:00:00 2001 From: Richard Dang Date: Tue, 24 Feb 2026 10:56:48 -0500 Subject: [PATCH 1/2] docs(wallets): add Debug transactions page for Transaction Lifecycle Dashboard Introduce developer-facing documentation for the TLD feature, covering the transaction lifecycle view, AI error explanations, filtering, and transaction statuses. Marked as early access with contact-support CTA. --- content/docs.yml | 2 + .../transactions/debug-transactions/index.mdx | 138 ++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 content/wallets/pages/transactions/debug-transactions/index.mdx diff --git a/content/docs.yml b/content/docs.yml index fa6313562..995104be8 100644 --- a/content/docs.yml +++ b/content/docs.yml @@ -920,6 +920,8 @@ navigation: path: wallets/pages/transactions/send-batch-transactions/index.mdx - page: Parallel transactions path: wallets/pages/transactions/send-parallel-transactions/index.mdx + - page: Debug transactions + path: wallets/pages/transactions/debug-transactions/index.mdx - page: How EIP-7702 works path: wallets/pages/transactions/using-eip-7702/index.mdx - section: Sponsor gas diff --git a/content/wallets/pages/transactions/debug-transactions/index.mdx b/content/wallets/pages/transactions/debug-transactions/index.mdx new file mode 100644 index 000000000..691f71f54 --- /dev/null +++ b/content/wallets/pages/transactions/debug-transactions/index.mdx @@ -0,0 +1,138 @@ +--- +title: Debug transactions +description: Inspect transaction lifecycles and debug failed Wallet API calls with AI-powered error explanations +slug: wallets/transactions/debug-transactions +--- + + + The Transaction Lifecycle Dashboard is in **early access**. [Request early access!](mailto:wallets@alchemy.com?subject=Transaction%20Lifecycle%20Dashboard%20%E2%80%93%20Early%20Access%20Request&body=Hi%20team%2C%0A%0AI%E2%80%99d%20like%20to%20request%20early%20access%20to%20the%20Transaction%20Lifecycle%20Dashboard.%0A%0ATeam%20name%3A%20%0AUse%20case%3A%20%0A%0AThanks!) + + +The Transaction Lifecycle Dashboard gives you full visibility into every step of a Wallet API transaction from preparation to confirmation and helps you debug failures with AI-powered error explanations. + +## Why use it + +When you send a transaction through the Wallet API, it goes through multiple steps: + +1. **Prepare** — [`wallet_prepareCalls`](/wallets/api-reference/smart-wallets/wallet-api-endpoints/wallet-api-endpoints/wallet-prepare-calls) prepares the transaction for submission +2. **Send** — [`wallet_sendPreparedCalls`](/wallets/api-reference/smart-wallets/wallet-api-endpoints/wallet-api-endpoints/wallet-send-prepared-calls) submits the prepared transaction onchain +3. **Track** — [`wallet_getCallsStatus`](/wallets/api-reference/smart-wallets/wallet-api-endpoints/wallet-api-endpoints/wallet-get-calls-status) polls for confirmation or failure + +A failure at any step can be difficult to diagnose from raw logs alone. The Transaction Lifecycle Dashboard groups all steps by Call ID so you can see exactly where things went wrong — and why. + +Transaction Lifecycle Dashboard overview + +## Key features + + + + See every step of a Wallet API call grouped by Call ID, with status, duration, and full request/response payloads + + + + Get plain-language explanations of why a transaction failed, along with specific remediation steps + + + + Filter by status, app, network, and time range to find the exact transactions you're looking for + + + + Inspect full JSON request and response bodies for each step, with copy support + + + +## Access the dashboard + +1. Open the [Alchemy dashboard](https://dashboard.alchemy.com) +2. In the left sidebar, navigate to **Tools > Logs** +3. Click the **Wallet API Logs** tab + +Direct link: [dashboard.alchemy.com/logs/wallet-api](https://dashboard.alchemy.com/logs/wallet-api) + +You can also access logs scoped to a specific app by navigating to **Apps > \[Your App] > Logs > Wallet API Logs**. + +## View transaction details + +Select any row in the log table to open the **Transaction Details** panel on the right. It shows: + +* **Call ID** — The unique identifier linking all steps of the transaction +* **Status** — Current state of the transaction (e.g., Confirmed, Pending, Prepare Failed) +* **App & Network** — Which app and network the call was made on +* **Step timeline** — Each Wallet API method call shown as an expandable card with status, duration, and full request/response JSON + +Transaction details panel with step timeline + +Click on any step to expand it and inspect the full request and response payloads. + +### Transaction statuses + +| Status | Description | +| --- | --- | +| **Confirmed** | Transaction successfully included onchain | +| **Pending** | Transaction submitted and awaiting confirmation | +| **Preconfirmed** | Transaction detected but not yet finalized | +| **Prepared** | Transaction prepared but not yet sent | +| **Sent** | Transaction sent and awaiting status | +| **Cross Chain Pending** | Cross-chain transaction in progress | +| **Prepare Failed** | Transaction failed during preparation (e.g., validation error) | +| **Send Failed** | Transaction failed during submission | +| **Status Failed** | Failed to retrieve transaction status | +| **Offchain Failure** | Transaction failed offchain before reaching the network | +| **Onchain Failure** | Transaction was included onchain but reverted | +| **Partial Failure** | Some calls in the batch succeeded while others failed | +| **Cross Chain Refunded** | Cross-chain transaction was refunded | +| **Unknown** | Transaction status could not be determined | + +## Debug errors with AI + +When a transaction step fails, the detail panel displays the error message and an **Explain this error** button. + +AI error explanation with category, explanation, and remediation steps + +Clicking the button sends the error context to an AI model that analyzes the failure and returns: + +* **Error category** — A classification such as Validation Error, Sponsorship Failure, Session Key Error, Signing Error, or Contract Error +* **What happened** — A plain-language description of the root cause +* **How to fix** — Specific steps to resolve the issue + + + AI-generated explanations are provided as guidance and may not always be accurate. Always verify the details independently before making changes to your integration. + + +### Common error categories + + + The transaction failed input validation before reaching the network. Common causes include malformed addresses, invalid calldata encoding, or missing required fields. Check your `wallet_prepareCalls` request payload against the [API reference](/wallets/api/smart-wallets/wallet-api-endpoints/wallet-api-endpoints/wallet-prepare-calls). + + + + Gas sponsorship was rejected by the gas manager policy. Verify that your [gas policy](https://dashboard.alchemy.com/gas-manager) is active, has sufficient balance, and that the transaction meets your sponsorship rules. + + + + The session key used to sign the transaction is invalid, expired, or does not have permission for the requested action. Review your [session key configuration](/wallets/reference/wallet-apis-session-keys/api). + + + + The transaction signature was rejected or could not be produced. This can happen when the signer is not authorized for the account, the signing method is incompatible, or the signer service is unavailable. + + + + The target contract reverted the transaction. This typically indicates an issue with the contract call itself — check the calldata, function parameters, and contract state. + + +## Filter and search + +Use the filter bar above the log table to narrow results: + +* **Time range** — Choose from presets or set a custom range. +* **Statuses** — Multi-select filter to show only specific transaction states (e.g., failures only) +* **Apps** — Filter by a specific app when viewing across all apps +* **Networks** — Filter by blockchain network + +## Next steps + +* [Send transactions](/wallets/transactions/send-transactions) — Learn how to send Wallet API transactions +* [Sponsor gas](/wallets/transactions/sponsor-gas) — Eliminate gas fees for your users +* [Common errors](/wallets/resources/faqs#common-errors) — Reference for frequently encountered issues From 588dd2758415bedd913812aa3fcbb998278d1df6 Mon Sep 17 00:00:00 2001 From: Richard Dang Date: Tue, 24 Feb 2026 13:05:49 -0500 Subject: [PATCH 2/2] docs(wallets): update AI error explanation screenshot --- content/wallets/pages/transactions/debug-transactions/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/wallets/pages/transactions/debug-transactions/index.mdx b/content/wallets/pages/transactions/debug-transactions/index.mdx index 691f71f54..2f5d6be50 100644 --- a/content/wallets/pages/transactions/debug-transactions/index.mdx +++ b/content/wallets/pages/transactions/debug-transactions/index.mdx @@ -88,7 +88,7 @@ Click on any step to expand it and inspect the full request and response payload When a transaction step fails, the detail panel displays the error message and an **Explain this error** button. -AI error explanation with category, explanation, and remediation steps +AI error explanation with category, explanation, and remediation steps Clicking the button sends the error context to an AI model that analyzes the failure and returns: