diff --git a/docs/api-reference/relayer/get-a-transaction-by-id.md b/docs/api-reference/relayer/get-a-transaction-by-id.md
index 94531e1..4ab7487 100644
--- a/docs/api-reference/relayer/get-a-transaction-by-id.md
+++ b/docs/api-reference/relayer/get-a-transaction-by-id.md
@@ -6,6 +6,8 @@
 
 > Gets a transaction submitted to the Relayer. Takes in a required transaction ID as a query parameter.
 
+Poll this endpoint with the `transactionID` returned from `POST /submit` to retrieve the onchain `transactionHash` once the transaction has been broadcast.
+
 
 
 
@@ -50,6 +52,11 @@ paths:
       description: >
         Gets a transaction submitted to the Relayer. Takes in a required
         transaction ID as a query parameter.
+
+
+        Poll this endpoint with the `transactionID` returned from `POST /submit`
+        to retrieve the onchain `transactionHash` once the transaction has been
+        broadcast.
       parameters:
         - name: id
           in: query
diff --git a/docs/api-reference/relayer/submit-a-transaction.md b/docs/api-reference/relayer/submit-a-transaction.md
index 77e6b30..a06a98d 100644
--- a/docs/api-reference/relayer/submit-a-transaction.md
+++ b/docs/api-reference/relayer/submit-a-transaction.md
@@ -6,6 +6,8 @@
 
 > Submit a transaction request to the Relayer. Authenticated using Builder API Keys or Relayer API Keys.
 
+Returns immediately with the `transactionID` and a `state` of `STATE_NEW`. The onchain transaction hash is **not** included in this response — poll `GET /transaction` with the returned `transactionID` to retrieve the `transactionHash` once the transaction has been broadcast.
+
 **Builder API Key auth headers:**
 - `POLY_BUILDER_API_KEY`
 - `POLY_BUILDER_TIMESTAMP`
@@ -62,6 +64,12 @@ paths:
         API Keys or Relayer API Keys.
 
 
+        Returns immediately with the `transactionID` and a `state` of
+        `STATE_NEW`. The onchain transaction hash is **not** included in this
+        response — poll `GET /transaction` with the returned `transactionID` to
+        retrieve the `transactionHash` once the transaction has been broadcast.
+
+
         **Builder API Key auth headers:**
 
         - `POLY_BUILDER_API_KEY`
@@ -146,7 +154,6 @@ paths:
                 $ref: '#/components/schemas/SubmitResponse'
               example:
                 transactionID: 0190b317-a1d3-7bec-9b91-eeb6dcd3a620
-                transactionHash: ''
                 state: STATE_NEW
         '400':
           description: Bad Request - Invalid transaction payload, fields, or signature
@@ -247,10 +254,6 @@ components:
           type: string
           description: Unique identifier for the submitted transaction
           example: 0190b317-a1d3-7bec-9b91-eeb6dcd3a620
-        transactionHash:
-          type: string
-          description: Onchain transaction hash (empty on initial submission)
-          example: ''
         state:
           type: string
           description: Current state of the transaction
diff --git a/docs/v2-migration.md b/docs/v2-migration.md
index 713590b..ba40cba 100644
--- a/docs/v2-migration.md
+++ b/docs/v2-migration.md
@@ -387,6 +387,10 @@ V2 replaces the old builder authentication flow (HMAC headers + separate signing
   `BuilderConfig` still exists, but its shape changed. In V1 it wrapped HMAC credentials from `@polymarket/builder-signing-sdk`. In V2 it's just `{ builderCode: string }`.
 </Note>
 
+<Note>
+  **Your builder API key isn't retired.** The HMAC-based builder API key is still used to authenticate with the [Relayer](/trading/gasless) for gasless transactions. Only the order-signing flow moves to the `builderCode` field — your relayer integration keeps the same credentials.
+</Note>
+
 <CodeGroup>
   ```typescript Before (V1) theme={null}
   import { BuilderConfig, BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk";