diff --git a/docs/base-chain/builder-codes/builder-codes-faq.mdx b/docs/base-chain/builder-codes/builder-codes-faq.mdx
new file mode 100644
index 000000000..8e36f6242
--- /dev/null
+++ b/docs/base-chain/builder-codes/builder-codes-faq.mdx
@@ -0,0 +1,104 @@
+---
+title: "Builder Codes FAQ"
+description: "Common questions about Builder Codes, ERC-8021 transaction attribution, gas costs, and SDK support on Base." 
+---
+
+### What is a "Builder Code" and where do I get one?
+
+A **Builder Code** is an ASCII string (like `"baseapp"` or `"bc_xyz456"`) that identifies your application in the ERC-8021 attribution system. When your app's transactions include this code, protocols can identify and reward you.
+
+<Tip>
+  Obtain your Builder Code [here](/base-chain/builder-codes/builder-codes).
+</Tip>
+
+### What are the benefits of supporting Builder Codes?
+
+- **Rewards:** If your app drives transactions, Builder Codes let Base automatically attribute that usage back to you, unlocking rewards as our program expands.  
+- **Analytics:** Developers can reliably track onchain usage, user acquisition, and conversion metrics in Base.dev.  
+- **Visibility:** Apps with Builder Codes can show up in discovery surfaces like our App Leaderboards, Base App store, and ecosystem spotlights.
+
+### Do I need to modify my smart contracts to use ERC-8021?
+
+**No.** The attribution suffix is appended to the end of transaction calldata. Smart contracts execute normally and ignore the extra data. Attribution is extracted by offchain indexers after the fact.
+
+This means:
+
+- Any existing smart contract automatically supports ERC-8021  
+- No upgrades or redeployments required  
+- Zero impact on contract execution
+
+### How much additional gas do Builder Codes cost?
+
+The ERC-8021 suffix adds a negligible amount of gas to each transaction at 16 gas per non-zero byte. 
+
+### Will Builder Codes expose my identity?
+
+**No.** Builder Codes only associate transactions with your application—they don't expose any wallet information that isn't already public onchain.
+
+### Can I use ERC-8021 with Externally Owned Accounts (EOAs)?
+
+**Yes.** ERC-8021 works with both EOAs and smart contract wallets.
+
+### How do I verify that my transaction was properly attributed?
+
+**1. Check base.dev**
+
+- Visit [base.dev](https://base.dev) 
+- Select **Onchain** from the transaction type dropdown 
+- Under the Total Transactions section, attribution counts increment when transactions with your code are processed
+
+**2. Use a Block Explorer (Basescan, Etherscan, etc.)**
+
+- Find your transaction hash  
+- View the input data field  
+- Verify the last 16 bytes are the `8021` repeating.  
+- Decode the suffix to confirm your Builder Code is present
+
+**3. Open Source Tools**
+
+- Use the [Builder Code Validation](https://builder-code-checker.vercel.app/) tool
+- Select transaction type
+- Enter the transaction or UserOperation hash 
+- Click the **Check Attribution** button
+
+
+### What wallets and SDKs currently support ERC-8021?
+
+**EOAs:**
+
+All EOA wallets support `dataSuffix` by default. 
+
+**SDKs:**
+
+- **viem/wagmi** - TypeScript SDK with native `dataSuffix` parameter support for server-side and client-side transactions
+
+<Note>
+This requires `viem@2.45.0` or higher
+</Note>
+
+**Embedded Wallets:**
+
+- **Privy** - Embedded wallet solution with ERC-8021 capability  
+- **Turnkey** - Infrastructure for programmatic wallets
+
+**Smart Wallets:** 
+
+Wallets supporting ERC-5792 can use the `DataSuffixCapability` for clean suffix appending:
+
+```javascript
+await wallet.sendCalls({
+  calls: [...],
+  capabilities: {
+    dataSuffix: {
+      value: "0x07626173656170700080218021802180218021802180218021"
+      optional: true
+    }
+  }
+});
+```
+
+## Additional Resources
+
+- [Official ERC-8021 Proposal ](https://eip.tools/eip/8021)  
+- [Builder Code Docs](/base-chain/builder-codes/builder-codes)  
+- [Builder Code Validation tool](https://builder-code-checker.vercel.app/)
diff --git a/docs/base-chain/quickstart/builder-codes.mdx b/docs/base-chain/builder-codes/builder-codes.mdx
similarity index 100%
rename from docs/base-chain/quickstart/builder-codes.mdx
rename to docs/base-chain/builder-codes/builder-codes.mdx
diff --git a/docs/docs.json b/docs/docs.json
index 9c7dc9052..ba57d38b1 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -85,8 +85,7 @@
               "base-chain/quickstart/deploy-on-base",
               "base-chain/quickstart/connecting-to-base",
               "base-chain/quickstart/bridge-token",
-              "base-chain/quickstart/base-solana-bridge",
-              "base-chain/quickstart/builder-codes"
+              "base-chain/quickstart/base-solana-bridge"
             ]
           },
           {
@@ -119,6 +118,13 @@
               "base-chain/node-operators/troubleshooting"
             ]
           },
+          {
+            "group": "Builder Codes",
+            "pages": [
+              "base-chain/builder-codes/builder-codes",
+              "base-chain/builder-codes/builder-codes-faq"
+            ]
+          },
           {
             "group": "Tools",
             "pages": [