send transaction docs

Author: moe-dev

category/code-examples.mdx

@@ -44,6 +44,9 @@ mode: wide
   <Card title="Signing transactions" href="/embedded-wallets/code-examples/signing-transactions" icon="file-lines" iconType="solid"  horizontal>
     Signing transactions
   </Card>
+  <Card title="Signing & Sending transactions" href="/embedded-wallets/code-examples/signing-and-sending-transactions" icon="file-lines" iconType="solid"  horizontal>
+    Signing transactions
+  </Card>
   <Card title="Import wallet or private key" href="/embedded-wallets/code-examples/import" icon="file-lines" iconType="solid"  horizontal>
     Import wallet or private key
   </Card>

docs.json

@@ -141,6 +141,7 @@
                       "embedded-wallets/code-examples/create-sub-org-passkey",
                       "embedded-wallets/code-examples/authenticate-user-passkey",
                       "embedded-wallets/code-examples/create-passkey-session",
+                      "embedded-wallets/code-examples/signing-and-sending-transactions",
                       "embedded-wallets/code-examples/create-user-email",
                       "embedded-wallets/code-examples/authenticate-user-email",
                       "embedded-wallets/code-examples/add-credential",

embedded-wallets/code-examples/signing-and-sending-transactions.mdx

@@ -0,0 +1,344 @@
+---
+title: "Signing & Sending Transactions"
+description: "Guide for signing and sending Ethereum transactions using Turnkey’s `signAndSendTransaction` API from `@turnkey/sdk-core`, with and without the React handler from `@turnkey/sdk-react-wallet-kit`."
+---
+
+## Overview
+
+Turnkey provides two primary ways to sign and broadcast transactions:
+
+1. **Using the React handler (`handleSendTransaction`) from `@turnkey/sdk-react-wallet-kit`**  
+   This gives you:
+   - modals  
+   - spinner + chain logo  
+   - success screen  
+   - explorer link  
+   - built-in polling  
+
+2. **Using low-level functions in `@turnkey/sdk-core`**  
+   You manually call:
+   - `signAndSendTransaction` → submit  
+   - `pollTransactionStatus` → wait for inclusion  
+
+This page shows both flows with full code included.
+
+---
+
+# 1. Using `handleSendTransaction` (React)
+
+This handler wraps everything: intent creation, signing, Turnkey submission, polling, modal UX, and final success UI.
+
+## Step 1 — Configure the Provider
+
+```ts
+import { TurnkeyProvider } from "@turnkey/sdk-react-wallet-kit";
+
+const turnkeyConfig = {
+  apiBaseUrl: "https://api.turnkey.com",
+  defaultOrganizationId: process.env.NEXT_PUBLIC_TURNKEY_ORG_ID,
+  rpId: window.location.hostname,
+  iframeUrl: "https://auth.turnkey.com",
+};
+
+export default function App({ children }) {
+  return (
+    <TurnkeyProvider config={turnkeyConfig}>
+      {children}
+    </TurnkeyProvider>
+  );
+}
+```
+
+---
+
+## Step 2 — Use `handleSendTransaction` inside your UI
+
+```ts
+const { handleSendTransaction, wallets } = useTurnkey();
+
+const walletAccount = wallets[0].accounts[0];
+
+await handleSendTransaction({
+  organizationId: "<org-id>",
+  from: walletAccount.address,
+  to: "0xRecipient",
+  value: "1000000000000000",
+  data: "0x",
+  caip2: "eip155:8453",
+  sponsor: true,
+});
+```
+
+This automatically:
+- opens Turnkey modal  
+- shows chain logo  
+- polls until INCLUDED 
+- displays success page + explorer link  
+
+---
+
+# 2. Using `@turnkey/sdk-core` directly (non-React)
+
+For custom frameworks, Node.js servers, or full manual control.
+
+You will call:
+
+### `signAndSendTransaction(params)`
+→ returns `{ sendTransactionStatusId }`
+
+### `pollTransactionStatus(params)`
+→ returns `{ txHash, status }`
+
+## Step 1 — Create a client
+
+```ts
+import { Turnkey } from "@turnkey/sdk-core";
+
+const client = new Turnkey({
+  apiBaseUrl: "https://api.turnkey.com",
+  defaultOrganizationId: process.env.TURNKEY_ORG_ID,
+});
+```
+
+---
+
+## Step 2 — Submit the transaction
+
+```ts
+const { sendTransactionStatusId } = await client.signAndSendTransaction({
+  walletAccount,
+  organizationId: "<org-id>",
+  from: walletAccount.address,
+  to: "0xRecipient",
+  caip2: "eip155:8453",
+  sponsor: true,
+  value: "0",
+  data: "0x",
+  nonce: "0",
+});
+```
+
+---
+
+## Step 3 — Poll for inclusion
+
+```ts
+const { txHash, status } = await client.pollTransactionStatus({
+  sendTransactionStatusId,
+});
+
+console.log("Mined:", txHash);
+```
+
+---
+
+# 3. Core Code (full implementations)
+
+## `signAndSendTransaction` — from `@turnkey/sdk-core`
+
+```ts
+/**
+ * Signs and submits an Ethereum transaction using Turnkey.
+ *
+ * Behavior:
+ * - Constructs transaction intent (sponsored or EIP-1559)
+ * - Submits via Turnkey
+ * - Returns { sendTransactionStatusId }
+ *
+ * Does NOT poll — caller must poll via pollTransactionStatus.
+ */
+signAndSendTransaction = async (
+  params: SignAndSendTransactionParams
+): Promise<SignAndSendResult> => {
+  const {
+    organizationId,
+    from,
+    to,
+    caip2,
+    sponsor,
+    value,
+    data,
+    nonce,
+    gasLimit,
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+    walletAccount,
+  } = params;
+
+  return withTurnkeyErrorHandling(
+    async () => {
+      const intent = {
+        from,
+        to,
+        caip2,
+        ...(value ? { value } : {}),
+        ...(data ? { data } : {}),
+      };
+
+      if (sponsor) {
+        intent["sponsor"] = true;
+      } else {
+        if (nonce) intent["nonce"] = nonce;
+        if (gasLimit) intent["gasLimit"] = gasLimit;
+        if (maxFeePerGas) intent["maxFeePerGas"] = maxFeePerGas;
+        if (maxPriorityFeePerGas)
+          intent["maxPriorityFeePerGas"] = maxPriorityFeePerGas;
+      }
+
+      const resp = await this.httpClient.ethSendTransaction({
+        ...intent,
+        ...(organizationId && { organizationId }),
+      });
+
+      return { sendTransactionStatusId: resp.sendTransactionStatusId };
+    },
+    {
+      errorMessage: "Failed to submit transaction",
+      errorCode: TurnkeyErrorCodes.SIGN_AND_SEND_TRANSACTION_ERROR,
+    }
+  );
+};
+```
+
+---
+
+## `pollTransactionStatus` — from `@turnkey/sdk-core`
+
+```ts
+/**
+ * Polls Turnkey until a transaction reaches a terminal state.
+ *
+ * Terminal states:
+ * - COMPLETED / INCLUDED → resolves { txHash, status }
+ * - FAILED / CANCELLED → rejects
+ */
+pollTransactionStatus({
+  httpClient,
+  organizationId,
+  sendTransactionStatusId,
+}: PollTransactionStatusParams): Promise<{
+  txHash: string;
+  status: string;
+}> {
+  return withTurnkeyErrorHandling(
+    async () => {
+      return new Promise((resolve, reject) => {
+        const ref = setInterval(async () => {
+          try {
+            const resp = await httpClient.getSendTransactionStatus({
+              organizationId,
+              sendTransactionStatusId,
+            });
+
+            const status = resp?.txStatus;
+            const txHash = resp?.eth?.txHash;
+            const txError = resp?.txError;
+
+            if (!status) return;
+
+            if (txError || status === "FAILED" || status === "CANCELLED") {
+              clearInterval(ref);
+              reject(txError || `Transaction ${status}`);
+              return;
+            }
+
+            if (status === "COMPLETED" || status === "INCLUDED") {
+              clearInterval(ref);
+              resolve({ txHash: txHash!, status });
+            }
+          } catch (e) {
+            console.warn("polling error:", e);
+          }
+        }, 500);
+      });
+    },
+    {
+      errorMessage: "Failed to poll transaction status",
+      errorCode: TurnkeyErrorCodes.SIGN_AND_SEND_TRANSACTION_ERROR,
+    }
+  );
+}
+```
+
+# 4. Full React Handler (uses the above two functions)
+
+```ts
+const handleSendTransaction = useCallback(
+  async (params: HandleSendTransactionParams): Promise<void> => {
+    const s = await getSession();
+    const organizationId = params.organizationId || s?.organizationId;
+
+    const {
+      from,
+      to,
+      value,
+      data,
+      caip2,
+      sponsor,
+      gasLimit,
+      maxFeePerGas,
+      maxPriorityFeePerGas,
+      nonce: providedNonce,
+      successPageDuration = 2000,
+    } = params;
+
+    const { nonce } = await generateNonces({
+      from: from,
+      rpcUrl: DEFAULT_RPC_BY_CHAIN[caip2],
+      providedNonce,
+    });
+
+    return new Promise((resolve, reject) => {
+      const SendTxContainer = () => {
+        const cleanedData =
+          data && data !== "0x" && data !== "" ? data : undefined;
+
+        const action = async () => {
+          const { sendTransactionStatusId } =
+            await client.signAndSendTransaction({
+              walletAccount,
+              organizationId,
+              from,
+              to,
+              caip2,
+              sponsor: !!sponsor,
+              value,
+              data: cleanedData,
+              nonce,
+              gasLimit,
+              maxFeePerGas,
+              maxPriorityFeePerGas,
+            });
+
+          const { txHash } = await client.pollTransactionStatus({
+            httpClient: client.httpClient,
+            organizationId,
+            sendTransactionStatusId,
+          });
+
+          return { txHash };
+        };
+
+        return (
+          <SendTransactionPage
+            icon={<img src={getChainLogo(caip2)} className="h-10 w-10" />}
+            action={action}
+            caip2={caip2}
+            successPageDuration={successPageDuration}
+            onSuccess={() => resolve()}
+            onError={(err) => reject(err)}
+          />
+        );
+      };
+
+      pushPage({
+        key: "Send Transaction",
+        content: <SendTxContainer />,
+        preventBack: true,
+        showTitle: false,
+      });
+    });
+  },
+  [pushPage, client]
+);
+```