Skip to content

Commit 8b32459

Browse files
gregfromstlgregfromstl
authored
Feature: Update UB Docs for latest SDK and Guides (#7265)
1 parent 5ebb754 commit 8b32459

File tree

11 files changed

+1472
-753
lines changed

11 files changed

+1472
-753
lines changed

‎apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/connect/universal-bridge/layout.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ export default async function Layout(props: {
3333
tokens via cross-chain routing.{" "}
3434
<UnderlineLink
3535
target="_blank"
36-
href="https://portal.thirdweb.com/connect/pay/overview"
36+
href="https://portal.thirdweb.com/pay"
3737
>
3838
Learn more
3939
</UnderlineLink>

‎apps/portal/src/app/pay/get-started/page.mdx

Lines changed: 233 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -5,31 +5,32 @@ import {
55
Steps,
66
Step,
77
InstallTabs,
8+
Tabs,
9+
TabsList,
10+
TabsTrigger,
11+
TabsContent,
812
} from "@doc";
9-
import GetStartedSend from "../assets/get-started-send.png";
10-
import GetStartedEmbed from "../assets/get-started-embed.png";
13+
1114
export const metadata = createMetadata({
1215
image: {
1316
title: "thirdweb Universal Bridge - Get Started",
1417
icon: "thirdweb",
1518
},
1619
title: "Universal Bridge Implementation Guide — thirdweb docs",
1720
description:
18-
"Learn how to implement all-in-one web3 payment solution, Universal bridge: the technical step-by-step process",
21+
"Learn how to implement cross-chain payments, bridging, and onramps with the Universal Bridge SDK",
1922
});
2023

2124
# Get Started
2225

23-
Learn how to add onramps and crypto purchases to your application. To see which integration is right for you, refer to our [integrations overview](/connect/pay/overview#integration-options).
24-
25-
The following guide uses our React SDK. You can also learn how to integrate Universal Bridge with our [Unity SDK](https://portal.thirdweb.com/unity/pay/getbuywithcryptoquote).
26+
Learn how to integrate Universal Bridge into your application for cross-chain payments, bridging, swapping, and fiat onramps. This guide covers the core SDK modules and practical implementation examples.
2627

2728
---
2829

2930
## Installation
3031

3132
<Steps>
32-
<Step title="Install the Connect SDK">
33+
<Step title="Install the SDK">
3334
<InstallTabs
3435
npm="npm i thirdweb"
3536
yarn="yarn add thirdweb"
@@ -38,95 +39,260 @@ The following guide uses our React SDK. You can also learn how to integrate Univ
3839
</Step>
3940
<Step title="Get Your Client ID">
4041

41-
Log in to [the thirdweb dashboard](https://thirdweb.com/team). Navigate to the **Settings** page and create an API key to get your **Client ID**. You'll need your Client ID to interact with the Connect SDK.
42+
Log in to [the thirdweb dashboard](https://thirdweb.com/team). Navigate to the **Settings** page and create an API key to get your **Client ID**. You'll need your Client ID to interact with the Universal Bridge.
43+
44+
</Step>
45+
<Step title="Initialize the Client">
46+
47+
```typescript
48+
import { createThirdwebClient } from "thirdweb";
49+
50+
const client = createThirdwebClient({
51+
clientId: "your_client_id"
52+
});
53+
```
54+
55+
</Step>
56+
<Step title="Prepare a Swap">
57+
58+
Get a quote and prepare your first cross-chain swap:
59+
60+
```typescript
61+
import { Bridge, NATIVE_TOKEN_ADDRESS, toWei } from "thirdweb";
62+
63+
const prepared = await Bridge.Buy.prepare({
64+
originChainId: 1,
65+
originTokenAddress: NATIVE_TOKEN_ADDRESS,
66+
destinationChainId: 137,
67+
destinationTokenAddress: NATIVE_TOKEN_ADDRESS,
68+
amount: toWei("0.1"),
69+
sender: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
70+
receiver: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
71+
client,
72+
});
73+
```
4274

4375
</Step>
4476
</Steps>
77+
4578
---
4679

47-
## Option 1: ConnectButton
80+
## Recipes
4881

49-
Universal Bridge is available by default with our `ConnectButton` component. When users log in with Connect, they'll be able to onramp and purchase crypto directly from the logged in Connect interface. You can read more about `ConnectButton` [in this guide](/connect/sign-in/ConnectButton).
82+
<Tabs defaultValue="buy">
83+
<TabsList className="grid w-full grid-cols-4">
84+
<TabsTrigger value="buy">Bridge & Swap</TabsTrigger>
85+
<TabsTrigger value="transfer">Transfers</TabsTrigger>
86+
<TabsTrigger value="onramp">Fiat Onramps</TabsTrigger>
87+
<TabsTrigger value="routes">Route Discovery</TabsTrigger>
88+
</TabsList>
5089

51-
```tsx
52-
import { ThirdwebProvider, ConnectButton } from "thirdweb/react";
90+
<TabsContent value="buy">
5391

54-
const client = createThirdwebClient({ clientId: your_client_id });
92+
Use the `Buy` module to purchase tokens on any supported chain using tokens from another chain:
5593

56-
export default function App() {
57-
return (
58-
<ThirdwebProvider>
59-
<ConnectButton client={client} />
60-
</ThirdwebProvider>
61-
);
94+
```typescript
95+
import { Bridge, NATIVE_TOKEN_ADDRESS, toWei } from "thirdweb";
96+
97+
// Step 1: Get a quote for the purchase
98+
const quote = await Bridge.Buy.quote({
99+
originChainId: 1, // Ethereum
100+
originTokenAddress: NATIVE_TOKEN_ADDRESS, // ETH
101+
destinationChainId: 137, // Polygon
102+
destinationTokenAddress: NATIVE_TOKEN_ADDRESS, // MATIC
103+
amount: toWei("0.1"), // 0.1 MATIC
104+
client,
105+
});
106+
107+
console.log(`Need ${quote.originAmount} origin tokens`);
108+
109+
// Step 2: Prepare a Swap
110+
const prepared = await Bridge.Buy.prepare({
111+
originChainId: 1,
112+
originTokenAddress: NATIVE_TOKEN_ADDRESS,
113+
destinationChainId: 137,
114+
destinationTokenAddress: NATIVE_TOKEN_ADDRESS,
115+
amount: toWei("0.1"),
116+
sender: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
117+
receiver: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
118+
client,
119+
});
120+
121+
// Step 3: Execute transactions
122+
for (const step of prepared.steps) {
123+
for (const transaction of step.transactions) {
124+
const result = await sendTransaction({
125+
transaction,
126+
account: wallet.account,
127+
});
128+
console.log("Transaction sent:", result.transactionHash);
129+
}
62130
}
63131
```
64132

65-
Our `ConnectButton` has a number of [customization options](/connect/pay/customization/connectbutton) so you can tailor it to your experience.
133+
**Best for:** NFT purchases, token swaps across chains, DeFi interactions
66134

67-
---
135+
</TabsContent>
68136

69-
## Option 2: Embed
137+
<TabsContent value="transfer">
70138

71-
The `PayEmbed` allows users to onramp and purchase crypto directly from your application interface.
139+
Use the `Transfer` module for same-chain or cross-chain token transfers:
72140

73-
```tsx
74-
import { ThirdwebProvider, PayEmbed } from "thirdweb/react";
141+
```typescript
142+
import { Bridge, NATIVE_TOKEN_ADDRESS, toWei } from "thirdweb";
75143

76-
const client = createThirdwebClient({ clientId: your_client_id });
144+
// Prepare transfer
145+
const transfer = await Bridge.Transfer.prepare({
146+
chainId: 1, // Ethereum
147+
tokenAddress: NATIVE_TOKEN_ADDRESS,
148+
amount: toWei("0.05"), // 0.05 ETH
149+
sender: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
150+
receiver: "0x742d35Cc6634C0532925a3b8D400A1B5000d3ae5",
151+
client,
152+
});
77153

78-
export default function App() {
79-
return (
80-
<ThirdwebProvider>
81-
<PayEmbed client={client} />
82-
</ThirdwebProvider>
83-
);
154+
// Execute transfer transactions
155+
for (const step of transfer.steps) {
156+
for (const transaction of step.transactions) {
157+
const result = await sendTransaction({
158+
transaction,
159+
account: wallet.account,
160+
});
161+
}
84162
}
85163
```
86164

87-
The embedded component will be displayed like so in your application interface:
165+
**Best for:** P2P payments, payroll, direct transfers
88166

89-
<DocImage src={GetStartedEmbed} />
167+
</TabsContent>
90168

91-
And voila! Your users can now onramp and convert crypto directly from your application.
169+
<TabsContent value="onramp">
92170

93-
Our `PayEmbed` has a number of [customization options](/connect/pay/customization/payembed) so you can tailor it to your experience.
171+
Use the `Onramp` module to convert fiat currency to crypto via supported providers:
172+
173+
```typescript
174+
import { Bridge, NATIVE_TOKEN_ADDRESS, toWei } from "thirdweb";
175+
176+
// Prepare onramp session
177+
const onramp = await Bridge.Onramp.prepare({
178+
client,
179+
onramp: "stripe", // or "coinbase", "transak"
180+
chainId: 1,
181+
tokenAddress: NATIVE_TOKEN_ADDRESS,
182+
receiver: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
183+
amount: toWei("0.1"), // 0.1 ETH
184+
country: "US",
185+
});
186+
187+
console.log(`Cost: $${onramp.currencyAmount} ${onramp.currency}`);
188+
189+
// Redirect user to complete purchase
190+
window.location.href = onramp.link;
191+
```
192+
193+
**Best for:** New users entering crypto, applications requiring fiat payments
194+
195+
</TabsContent>
196+
197+
<TabsContent value="routes">
198+
199+
Use the `routes` function to discover available bridging paths:
200+
201+
```typescript
202+
import { Bridge, NATIVE_TOKEN_ADDRESS } from "thirdweb";
203+
204+
// Find all routes from Ethereum ETH
205+
const allRoutes = await Bridge.routes({
206+
originChainId: 1,
207+
originTokenAddress: NATIVE_TOKEN_ADDRESS,
208+
client,
209+
});
210+
211+
// Find specific routes with pagination
212+
const filteredRoutes = await Bridge.routes({
213+
originChainId: 1,
214+
originTokenAddress: NATIVE_TOKEN_ADDRESS,
215+
destinationChainId: 137,
216+
limit: 10,
217+
sortBy: "popularity",
218+
client,
219+
});
220+
221+
console.log(`Found ${filteredRoutes.length} routes`);
222+
```
223+
224+
**Best for:** Building route selectors, showing available options to users
225+
226+
</TabsContent>
227+
228+
</Tabs>
94229

95230
---
96231

97-
## Option 3: Send a Transaction with Pay
98-
99-
Universal Bridge is enabled by default for any contract call sent with `sendTransaction`. It will automatically be invoked when a user does not have enough funds to complete the transaction.
100-
101-
<Callout variant="info">
102-
ℹ️ `sendTransaction` is available in [Connect SDK v5](/typescript/v5) or
103-
above.
104-
</Callout>
105-
106-
```tsx
107-
import { useSendTransaction } from "thirdweb/react";
108-
import { mintTo } from "thirdweb/extensions/erc721";
109-
110-
const { mutate: sendTx, data: transactionResult } = useSendTransaction();
111-
112-
const onClick = () => {
113-
const transaction = mintTo({
114-
contract,
115-
to: "0x...",
116-
nft: {
117-
name: "NFT Name",
118-
description: "NFT Description",
119-
image: "https://example.com/image.png",
120-
},
121-
});
122-
sendTx(transaction);
123-
};
232+
## Transaction Status Tracking
233+
234+
Monitor the progress of your Universal Bridge transactions:
235+
236+
```typescript
237+
import { Bridge } from "thirdweb";
238+
239+
// Check transaction status
240+
const status = await Bridge.status({
241+
transactionHash: "0x5959b9321ec581640db531b80bac53cbd968f3d34fc6cb1d5f4ea75f26df2ad7",
242+
chainId: 137,
243+
client,
244+
});
245+
246+
switch (status.status) {
247+
case "COMPLETED":
248+
console.log("Bridge completed!");
249+
console.log("Final amount:", status.destinationAmount);
250+
break;
251+
case "PENDING":
252+
console.log("Still processing...");
253+
break;
254+
case "FAILED":
255+
console.log("Transaction failed");
256+
break;
257+
case "NOT_FOUND":
258+
console.log("Transaction not found");
259+
break;
260+
}
124261
```
125262

126-
When a user clicks this button, Universal Bridge will perform gas estimation to determine if the user has a sufficient balance. If their balance is sufficient, the transaction will execute normally. If their balance is not sufficient, the following modal will pop up asking them to either onramp funds or convert crypto to the required amount:
263+
---
264+
265+
## Error Handling
266+
267+
Universal Bridge functions throw `ApiError` for failed requests:
268+
269+
```typescript
270+
import { Bridge, ApiError } from "thirdweb";
271+
272+
try {
273+
const quote = await Bridge.Buy.quote({
274+
originChainId: 1,
275+
originTokenAddress: NATIVE_TOKEN_ADDRESS,
276+
destinationChainId: 999999, // Invalid chain
277+
destinationTokenAddress: NATIVE_TOKEN_ADDRESS,
278+
amount: toWei("0.1"),
279+
client,
280+
});
281+
} catch (error) {
282+
if (error instanceof ApiError) {
283+
console.log("API Error:", error.message);
284+
console.log("Status Code:", error.statusCode);
285+
console.log("Correlation ID:", error.correlationId);
286+
}
287+
}
288+
```
127289

128-
<DocImage src={GetStartedSend} />
290+
---
129291

130-
Once a user onramps or converts their funds to the required token, the user will be prompted once more to confirm the transaction. The transaction will then execute as expected.
292+
## Next Steps
131293

132-
For deeper customization of the Universal Bridge transaction modal, you can refer to our [sendTransaction customization guide](/connect/pay/customization/send-transaction).
294+
- **[API Reference](https://bridge.thirdweb.com/reference)** - Complete REST API documentation
295+
- **[SDK Reference](/typescript/v5/buy/quote)** - TypeScript SDK function reference
296+
- **[Webhooks](/pay/webhooks)** - Set up real-time notifications
297+
- **[Customization Guides](/pay/customization)** - Advanced configuration options
298+
- **[Playground](https://playground.thirdweb.com/connect/pay)** - Interactive testing environment

0 commit comments

Comments
 (0)