[Docs] Update API endpoints and add frontend/backend examples

Author: joaquim-verges

apps/portal/src/app/Header.tsx

@@ -119,6 +119,10 @@ export const connectLinks: Array<{
 ] as const;
 
 const apisLinks = [
+  {
+    href: "https://api.thirdweb.com/reference",
+    name: "HTTP API",
+  },
   {
     href: "https://insight.thirdweb.com/reference",
     name: "Insight",
@@ -281,6 +285,22 @@ export function Header() {
         </nav>
 
         <div className="flex items-center gap-3">
+          <div className="px-1">
+            <DropdownLinks
+              category="AI"
+              links={[
+                {
+                  href: "/ai/mcp",
+                  name: "MCP",
+                },
+                {
+                  href: "/ai/llms-txt",
+                  name: "LLMs.txt",
+                },
+              ]}
+              onLinkClick={() => setShowBurgerMenu(false)}
+            />
+          </div>
           <div className="px-1">
             <DropdownLinks
               category="SDKs"

apps/portal/src/app/ai/layout.tsx

@@ -0,0 +1,33 @@
+import { createMetadata } from "@doc";
+import { BookIcon, ZapIcon } from "lucide-react";
+import { DocLayout } from "@/components/Layouts/DocLayout";
+
+export default async function Layout(props: { children: React.ReactNode }) {
+  return (
+    <DocLayout
+      editPageButton={true}
+      sideBar={{
+        links: [
+          {
+            name: "MCP Server",
+            icon: <ZapIcon />,
+            href: "/ai/mcp",
+          },
+          {
+            name: "llms.txt",
+            icon: <BookIcon />,
+            href: "/ai/llm-txt",
+          },
+        ],
+        name: "AI",
+      }}
+    >
+      <div>{props.children}</div>
+    </DocLayout>
+  );
+}
+
+export const metadata = createMetadata({
+  description: "AI tools for agents and LLM clients.",
+  title: "thirdweb AI",
+});

apps/portal/src/app/ai/llm-txt/page.mdx

@@ -0,0 +1,21 @@
+# llms.txt
+
+Use these llms.txt files to instruct your LLM on how to use the thirdweb API.
+
+### thirdweb API reference
+
+The [thirdweb HTTP API reference](https://api.thirdweb.com/reference) as markdown. 
+
+Available at: https://api.thirdweb.com/llms.txt
+
+### Typescript SDK quick reference
+
+Contains a table of contents for the thirdweb Typescript SDK documentation.
+
+Available at: https://portal.thirdweb.com/llms.txt
+
+### Typescript SDK full documentation
+
+Contains the entire thirdweb Typescript SDK documentation as markdown. Requires large context windows.
+
+Available at: https://portal.thirdweb.com/llms-full.txt

apps/portal/src/app/ai/mcp/page.mdx

@@ -0,0 +1,62 @@
+# MCP server
+
+You can use the thirdweb MCP server to interact with the thirdweb API from your agents or LLM client.
+
+### Remote MCP endpoint
+
+You can access the MCP server at the following url, with your project secret key.
+
+```http
+# endpoint
+POST https://api.thirdweb.com/mcp
+
+# auth header (required)
+x-secret-key <your-project-secret-key>
+```
+
+### Usage with agents
+
+Use your favorite agent framework to plug in the MCP server as a collection of tools for your agent.  Refer to your agent framework's documentation for more information.
+
+#### Example usage with langchain:
+
+```python
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langgraph.prebuilt import create_react_agent
+
+client = MultiServerMCPClient(
+    {
+        "thirdweb-api": {
+            "transport": "streamable_http",
+            "url": "https://api.thirdweb-dev.com/mcp",
+            "headers": {
+                "x-secret-key": "<your-project-secret-key>"
+            },
+        }
+    }
+)
+tools = await client.get_tools()
+agent = create_react_agent("openai:gpt-4.1", tools)
+response = await agent.ainvoke({"messages": "create a server wallet called 'my-wallet'"})
+```
+
+### Usage with LLM clients
+
+You can also use the MCP server on your own LLM client, like cursor, claude code and more. Refer to your LLM client's documentation for more information.
+
+#### Example usage with Cursor:
+
+Add the following to your `.cursor/mcp.json` file:
+
+```json
+{
+  "mcpServers": {
+    "thirdweb-api": {
+      "url": "https://api.thirdweb-dev.com/mcp",
+      "headers": {
+        "x-secret-key": "<your-project-secret-key>"
+      }
+    }
+  }
+}
+```

apps/portal/src/app/contracts/page.mdx

@@ -34,8 +34,6 @@ export const metadata = createMetadata({
 
 Read, write, and deploy smart contracts on any EVM compatible blockchain.
 
----
-
 <Tabs defaultValue="http">
   <TabsList>
     <TabsTrigger value="http" className="flex items-center gap-2 [&>p]:mb-0">
@@ -71,19 +69,16 @@ Read, write, and deploy smart contracts on any EVM compatible blockchain.
   <TabsContent value="http">
     ### Read a Contract
 
-    You can read contract data efficiently using the [contract read API](https://engine.thirdweb.com/reference).
+    You can read contract data efficiently using the [contract read API](https://api.thirdweb.com/reference#tag/contracts/post/v1/contracts/read).
 
     ```http
-    GET /v1/contract/read
+    GET https://api.thirdweb.com/v1/contracts/read
     Content-Type: application/json
-    x-secret-key: <your-project-secret-key>
+    x-client-id: <your-project-client-id>
 
     {
-        "readOptions": {
-          "chainId": "1" // your chain id
-		  "from": "0x...", // optional, if you want to read from a specific address
-        },
-        "params": [{
+        "chainId": "1" // your chain id
+        "calls": [{
           "contractAddress": "0x...",
           "method": "function allowance(address owner, address spender)",
           "params": ["0x...", "0x..."],
@@ -93,33 +88,65 @@ Read, write, and deploy smart contracts on any EVM compatible blockchain.
 
 	You can batch multiple contract reads in a single request, and the response will be an array of results or errors.
 
+  Authentication requires either `x-secret-key` (backend) or `x-client-id` (frontend) to be set in the request headers.
+
 	### Write to a Contract
 
-	You can write to a contract using the [contract write API](https://engine.thirdweb.com/reference).
-
-	```http
-	POST /v1/contract/write
-	Content-Type: application/json
-	x-secret-key: <your-project-secret-key>
-
-	{
-		"executionOptions": {
-			"from": "0x...", // your server wallet address
-			"chainId": "1" // your chain id
-		},
-		"params": [{
-			"contractAddress": "0x...",
-			"method": "function transfer(address to, uint256 amount)",
-			"params": ["0x...", "1000000000000000000"],
-		}]
-	}
-	```
+	You can write to a contract using the [contract write API](https://api.thirdweb.com/reference#tag/contracts/post/v1/contracts/write).
 
-	You can batch multiple contract writes in a single request, and the transactions will be batched atomically onchain.
+<Tabs defaultValue="frontend">
+      <TabsList>
+        <TabsTrigger value="frontend">Frontend</TabsTrigger>
+        <TabsTrigger value="backend">Backend</TabsTrigger>
+      </TabsList>
 
-	### Deploy a Contract
+      <TabsContent value="frontend">
+
+      On the frontend, use your project client ID and the users's auth token to send a transaction on their behalf.
+
+      ```http
+      POST https://api.thirdweb.com/v1/contracts/write
+      Content-Type: application/json
+      x-client-id: <your-project-client-id>
+      Authorization: Bearer <user-auth-token>
+
+      {
+        "from": "0x...", // the user wallet address
+        "chainId": "1" // the chain id
+        "calls": [{
+          "contractAddress": "0x...",
+          "method": "function transfer(address to, uint256 amount)",
+          "params": ["0x...", "1000000000000000000"],
+        }],
+      }
+      ```
+
+      </TabsContent>
 
-	You can deploy a contract using the [contract deploy API](https://engine.thirdweb.com/reference).
+      <TabsContent value="backend">
+
+      On the backend, use your project secret key to send a transaction from any of your server wallets.
+
+      ```http
+    POST https://api.thirdweb.com/v1/contracts/write
+    Content-Type: application/json
+    x-secret-key: <your-project-secret-key>
+
+    {
+        "from": "0x...", // your server wallet address
+        "chainId": "1" // your chain id
+        "calls": [{
+          "contractAddress": "0x...",
+          "method": "function transfer(address to, uint256 amount)",
+          "params": ["0x...", "1000000000000000000"],
+        }],
+    }
+    ```
+
+      </TabsContent>
+    </Tabs>
+
+	You can batch multiple contract writes in a single request, and the transactions will be batched atomically onchain.
 
   </TabsContent>
 

apps/portal/src/app/contracts/sidebar.tsx

@@ -1,4 +1,4 @@
-import { ZapIcon } from "lucide-react";
+import { ExternalLinkIcon, ZapIcon } from "lucide-react";
 import type { SideBar } from "@/components/Layouts/DocLayout";
 import {
   DotNetIcon,
@@ -18,6 +18,11 @@ export const sidebar: SideBar = {
       name: "Get Started",
       icon: <ZapIcon />,
     },
+    {
+      href: "https://playground.thirdweb.com/",
+      icon: <ExternalLinkIcon />,
+      name: "Playground",
+    },
     { separator: true },
     {
       isCollapsible: false,

apps/portal/src/app/page.tsx

@@ -112,6 +112,11 @@ function ReferenceSection() {
       <section>
         <SectionTitle anchorId="backend" title="Backend APIs" />
         <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+          <SDKCard
+            href="https://api.thirdweb.com/reference"
+            icon={ConnectIcon}
+            title="HTTP API"
+          />
           <SDKCard
             href="https://engine.thirdweb.com/reference"
             icon={EngineIcon}
@@ -127,11 +132,6 @@ function ReferenceSection() {
             icon={BridgeIcon}
             title="Payments"
           />
-          <SDKCard
-            href="/wallets/get-users"
-            icon={ConnectIcon} // TODO: actual openAPI docs
-            title="Wallets"
-          />
           <SDKCard
             href="/bundler"
             icon={ConnectIcon} // TODO: actual openAPI docs

apps/portal/src/app/payments/fees/assets/fee-dash.png

@@ -0,0 +1,55 @@
+import {DocImage} from "@doc";
+import FeeShare from './assets/fee-dash.png';
+
+
+# Understanding fees
+
+Understand how protocol, developer, and onramp fees work with Payments. 
+
+### Developer Fee
+
+To monetize applications or games, you are able to set a developer fee on each crypto-to-crypto or swap transaction. You may set this percentage
+through Project > Payments > Settings.
+
+<DocImage src={FeeShare} alt="Developer fee share" />
+
+### Protocol Fee
+
+Our protocol fee is a flat 30 basis points (0.30%) applied on the source token amount.
+This fee is independent of network gas fees and does not fluctuate.
+
+#### Setting fees using buy or sell
+
+You can configure who pays the protocol fee for buy or sell transactions by specifying the input amount `sell` or `buy`.
+
+See full reference for [`buy`](https://portal.thirdweb.com/references/typescript/v5/buy/prepare) and [`sell`](https://portal.thirdweb.com/references/typescript/v5/sell/prepare). 
+
+#### Setting fees on transfers or purchase mode
+
+You can configure who pays the protocol fee for transfers or purchase mode using the `feePayer` setting. This affects the 
+total amount paid by the user and the amount received by the destination (e.g., a seller, app, or partner).
+
+feePayer=buyer (Default) i.e. the user covers the protocol fee.
+
+Example: If the source token is 10 USDC, the user pays 10.30 USDC.
+
+- thirdweb receives: 0.30 USDC
+
+- Receiver receives: 10.00 USDC
+
+feePayer=receiver i.e. the receiver covers the protocol fee.
+
+Example: The user pays 10.00 USDC.
+
+- thirdweb receives: 0.30 USDC
+
+- Receiver receives: 9.70 USDC
+
+[See full reference.](https://bridge.thirdweb.com/reference#tag/transfer/POST/v1/transfer/prepare)
+
+### Onramp Fee
+
+When onramping to crypto using the Payments, a fee is charged by the third-party provider. This fee is determined by the provider and is typically a percentage 
+of the amount being onramped. This fee may vary based on the provider and payment method used.
+
+There are no protocol fees on onramp transactions.