chore: Add Buy docs (#1777)

Co-authored-by: Alissa Crane <alissa.crane@coinbase.com>
Co-authored-by: fakepixels <tinaxhe@gmail.com>

site/docs/components/BuyWrapper.tsx

@@ -0,0 +1,37 @@
+'use client';
+import type { SwapError } from '@coinbase/onchainkit/swap';
+import type { Token } from '@coinbase/onchainkit/token';
+import { type ReactNode, useCallback } from 'react';
+
+type BuyComponentsChildren = {
+  toToken: Token;
+  onError: (e: SwapError) => void;
+};
+
+type BuyComponentsReact = {
+  children: (props: BuyComponentsChildren) => ReactNode;
+};
+
+export default function BuyComponents({ children }: BuyComponentsReact) {
+  const degenToken: Token = {
+    name: 'DEGEN',
+    address: '0x4ed4e862860bed51a9570b96d89af5e1b0efefed',
+    symbol: 'DEGEN',
+    decimals: 18,
+    image:
+      'https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/3b/bf/3bbf118b5e6dc2f9e7fc607a6e7526647b4ba8f0bea87125f971446d57b296d2-MDNmNjY0MmEtNGFiZi00N2I0LWIwMTItMDUyMzg2ZDZhMWNm',
+    chainId: 8453,
+  };
+
+  const onError = useCallback((error: SwapError) => {
+    console.log('OnchainKit Docs Buy Error', error);
+  }, []);
+
+  return (
+    <main className="flex flex-col">
+      <div className="flex h-36 w-full flex-col items-center justify-center gap-4 rounded-xl px-2 py-4 md:grow">
+        {children({ toToken: degenToken, onError })}
+      </div>
+    </main>
+  );
+}

site/docs/components/landing/BuyDemo.tsx

@@ -0,0 +1,39 @@
+import { Buy } from '@coinbase/onchainkit/buy';
+import AppDemo from '../AppDemo.tsx';
+import BuyWrapper from '../BuyWrapper.tsx';
+
+export const buyDemoCode = `
+  import { Buy } from '@coinbase/onchainkit/buy';
+  import type { Token } from '@coinbase/onchainkit/token';
+
+  function BuyDemo() {
+    const degenToken: Token = {
+      name: 'DEGEN',
+      address: '0x4ed4e862860bed51a9570b96d89af5e1b0efefed',
+      symbol: 'DEGEN',
+      decimals: 18,
+      image: 'https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/3b/bf/3bbf118b5e6dc2f9e7fc607a6e7526647b4ba8f0bea87125f971446d57b296d2-MDNmNjY0MmEtNGFiZi00N2I0LWIwMTItMDUyMzg2ZDZhMWNm',
+      chainId: 8453,
+    };
+
+    return (
+      <Buy toToken={degenToken} />
+    );
+  }
+  `;
+
+function BuyDemo() {
+  return (
+    <div className="mx-auto flex flex-col items-center justify-center">
+      <AppDemo>
+        <BuyWrapper>
+          {({ toToken, onError }) => {
+            return <Buy toToken={toToken} onError={onError} />;
+          }}
+        </BuyWrapper>
+      </AppDemo>
+    </div>
+  );
+}
+
+export default BuyDemo;

site/docs/components/landing/ComponentPreview.tsx

@@ -7,6 +7,7 @@ import CheckIcon from '../svg/checkSvg.js';
 import { getHighlightedCode } from './getHighlightedCode.tsx';
 
 // Demo components and code snippets
+import BuyDemo, { buyDemoCode } from './BuyDemo.tsx';
 import CheckoutDemo, { checkoutDemoCode } from './CheckoutDemo.tsx';
 import FundDemo, { fundDemoCode } from './FundDemo.tsx';
 import IdentityCardDemo, { identityCardDemoCode } from './IdentityCardDemo.tsx';
@@ -35,6 +36,12 @@ const components: Component[] = [
     code: swapDemoCode,
     description: 'Enable swaps between different cryptocurrencies.',
   },
+  {
+    name: 'Buy',
+    component: BuyDemo,
+    code: buyDemoCode,
+    description: 'Enable token purchases.',
+  },
   {
     name: 'Mint',
     component: NftMintCardDemo,

site/docs/components/landing/LandingFooter.tsx

@@ -25,6 +25,7 @@ const LandingFooter: React.FC = () => {
     {
       title: 'Components',
       links: [
+        { text: 'Buy', href: 'https://onchainkit.xyz/buy/buy' },
         { text: 'Wallet', href: 'https://onchainkit.xyz/wallet/wallet' },
         { text: 'Swap', href: 'https://onchainkit.xyz/swap/swap' },
         {

site/docs/pages/buy/buy.mdx

@@ -0,0 +1,108 @@
+---
+title: <Buy /> · OnchainKit
+description: Buy components & utilities
+---
+
+import { Avatar, Name } from '@coinbase/onchainkit/identity';
+import { Swap, SwapAmountInput, SwapButton, SwapDefault, SwapMessage, SwapToggleButton, SwapToast } from '@coinbase/onchainkit/swap';
+import { Buy } from '@coinbase/onchainkit/buy';
+import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';
+import App from '../../components/App';
+import SwapWrapper from '../../components/SwapWrapper';
+import BuyWrapper from '../../components/BuyWrapper';
+
+# `<Buy />`
+
+<img alt="Buy"
+  src="https://onchainkit.xyz/assets/buy.gif"
+  height="364"/>
+
+The `Buy` components provide a comprehensive interface for users to purchase [Tokens](/token/types#token).
+
+The `Buy` component supports token swaps from USDC and ETH by default with the option to provide an additional token of choice using the `fromToken` prop. In addition, users are able to purchase tokens using their Coinbase account, Apple Pay, or debit card.
+
+Before using, ensure you've completed all [Getting Started steps](/getting-started).
+
+:::info
+Note: this component requires a `projectId` to be set in the `OnchainKitProvider`. You can find your `projectId` on [Coinbase Developer Platform](https://portal.cdp.coinbase.com/products/onchainkit).
+:::
+
+## Usage
+
+Example using `@coinbase/onchainkit/buy`.
+
+```tsx twoslash
+import { Buy } from '@coinbase/onchainkit/buy'; // [!code focus]
+import type { Token } from '@coinbase/onchainkit/token';
+
+export default function BuyComponents() { // [!code focus]
+  const degenToken: Token = {
+    name: 'DEGEN',
+    address: '0x4ed4e862860bed51a9570b96d89af5e1b0efefed',
+    symbol: 'DEGEN',
+    decimals: 18,
+    image:
+    'https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/3b/bf/3bbf118b5e6dc2f9e7fc607a6e7526647b4ba8f0bea87125f971446d57b296d2-MDNmNjY0MmEtNGFiZi00N2I0LWIwMTItMDUyMzg2ZDZhMWNm',
+    chainId: 8453,
+  };
+
+  return ( // [!code focus]
+    <Buy toToken={degenToken} /> // [!code focus]
+  ) // [!code focus]
+} // [!code focus]
+
+```
+
+<App>
+  <BuyWrapper>
+    {({ address, toToken }) => {
+      return (
+        <Buy toToken={toToken} />
+      )
+    }}
+  </BuyWrapper>
+</App>
+
+:::danger
+**Note: This interface is for demonstration purposes only.**
+
+Swap and Onramp flows will execute and work out of the box when you implement the component in your own app.
+:::
+
+### Sponsor gas with Paymaster
+
+To sponsor swap transactions for your users, toggle the Paymaster using the `isSponsored` prop.
+
+By default, this will use the [Coinbase Developer Platform](https://portal.cdp.coinbase.com/products/bundler-and-paymaster) Paymaster.
+
+You can configure sponsorship settings on the [Paymaster](https://portal.cdp.coinbase.com/products/bundler-and-paymaster) page.
+For security reasons, we recommend setting up a contract allowlist in the Portal. Without a contract allowlist defined, your Paymaster will only be able to sponsor up to $1.
+
+The contract used in our Swap API is Uniswap's [Universal Router](https://basescan.org/address/0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD), which is deployed on Base at `0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD`.
+
+Note that gas sponsorship will only work for Smart Wallets.
+
+```tsx twoslash
+import { Buy } from '@coinbase/onchainkit/buy'; // [!code focus]
+import type { Token } from '@coinbase/onchainkit/token';
+
+export default function BuyComponents() { // [!code focus]
+  const degenToken: Token = {
+    name: 'DEGEN',
+    address: '0x4ed4e862860bed51a9570b96d89af5e1b0efefed',
+    symbol: 'DEGEN',
+    decimals: 18,
+    image:
+    'https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/3b/bf/3bbf118b5e6dc2f9e7fc607a6e7526647b4ba8f0bea87125f971446d57b296d2-MDNmNjY0MmEtNGFiZi00N2I0LWIwMTItMDUyMzg2ZDZhMWNm',
+    chainId: 8453,
+  };
+
+  return ( // [!code focus]
+    <Buy toToken={degenToken} isSponsored /> // [!code focus]
+  ) // [!code focus]
+} // [!code focus]
+```
+
+## Props
+
+- [`BuyReact`](/buy/types#buyreact)

site/docs/pages/buy/types.mdx

@@ -0,0 +1,26 @@
+---
+title: Buy components & utilities Types
+description: Glossary of Types in Buy components & utilities.
+---
+
+# Types [Glossary of Types in Buy components & utilities.]
+
+## `BuyReact`
+
+```ts
+type BuyReact = {
+  className?: string; // Optional className override for top div element.
+  config?: {
+    maxSlippage: number; // Maximum acceptable slippage for a swap (e.g., 3 for 3%). This is a percentage, not basis points.
+  };
+  experimental?: {
+    useAggregator: boolean; // Whether to use a DEX aggregator. (default: true)
+  };
+  isSponsored?: boolean; // An optional setting to sponsor swaps with a Paymaster. (default: false)
+  onError?: (error: SwapError) => void; // An optional callback function that handles errors within the provider.
+  onStatus?: (lifecycleStatus: LifecycleStatus) => void; // An optional callback function that exposes the component lifecycle state.
+  onSuccess?: (transactionReceipt?: TransactionReceipt) => void; // An optional callback function that exposes the transaction receipt.
+  fromToken?: Token; // An optional token to swap from. (USDC and ETH supported by default)
+  toToken: Token; // The token to purchase.
+};
+```

site/docs/pages/swap/swap.mdx

@@ -56,7 +56,7 @@ const usdc: Token = {
     {({ address, swappableTokens }) => {
       if (address) {
         return (
-          <SwapDefault from={swappableTokens} to={swappableTokens.slice().reverse()} />
+          <SwapDefault from={swappableTokens} to={swappableTokens.slice().reverse()} disabled />
         )
       }
       return <>

site/sidebar.ts

@@ -81,6 +81,15 @@ export const sidebar = [
   {
     text: 'Components',
     items: [
+      {
+        text: 'Buy',
+        items: [
+          {
+            text: 'Buy',
+            link: '/buy/buy',
+          },
+        ],
+      },
       {
         text: 'Checkout',
         items: [