Skip to content

updating docs to include session token more explicitly #664

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 19, 2025
Merged

updating docs to include session token more explicitly #664

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
300 changes: 138 additions & 162 deletions docs/onchainkit/fund/fund-button.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,250 +1,226 @@
---
title: <FundButton /> · OnchainKit
title: <FundButton />
sidebarTitle: <FundButton />
description: The `<FundButton />` component provides a way for users to onramp from fiat to crypto from within your app.
description: The `<FundButton />` component provides a way for users to fund their wallet without leaving your app.
---

# FundButton

The `<FundButton />` component provides a way for users to fund their wallet without leaving your app. It automatically
detects the user's wallet type (EOA vs Smart Wallet) and directs them to the appropriate funding URL.

If your user connects a Coinbase Smart Wallet, it provides an easy way to access the Coinbase Smart Wallet
[Fund](https://keys.coinbase.com/fund) flow. Users will be able to buy and receive crypto, or use their Coinbase
If your user connects a Coinbase Smart Wallet, it provides an easy way to access the Coinbase Smart Wallet
[Fund](https://keys.coinbase.com/fund) flow. Users will be able to buy and receive crypto, or use their Coinbase
balances onchain with [Magic Spend](https://www.smartwallet.dev/guides/magic-spend).

If your user connects any other EOA wallet, it provides an easy way to access [Coinbase Onramp](https://docs.cdp.coinbase.com/onramp/docs/welcome/)
where your users will also be able to buy crypto using a fiat payment method, or transfer existing crypto from their
Coinbase account.

Before using it, ensure you've completed all [Getting Started steps](/onchainkit/getting-started).

## Walkthrough

<Steps>
<Step title="Get your Project ID">
1. Get your Project ID from the [Coinbase Developer Platform Dashboard](https://portal.cdp.coinbase.com/).
1. Get your Project ID from the [Coinbase Developer Platform Dashboard](https://portal.cdp.coinbase.com/).

<Frame>
<img alt="OnchainKit copy Project Id" src="/images/onchainkit/copy-project-id.png" />
</Frame>
<Frame>
<img alt="OnchainKit copy Project Id" src="https://mintcdn.com/base-a060aa97/-q4fo0uzIfxlH3Wn/images/onchainkit/copy-project-id.png?fit=max&auto=format&n=-q4fo0uzIfxlH3Wn&q=85&s=a252ce9520dc3909df614eaa3739a09d" data-og-width="1247" width="1247" data-og-height="466" height="466" data-path="images/onchainkit/copy-project-id.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/base-a060aa97/-q4fo0uzIfxlH3Wn/images/onchainkit/copy-project-id.png?w=280&fit=max&auto=format&n=-q4fo0uzIfxlH3Wn&q=85&s=f5bed02ce1fa668ee0915e149fd208e2 280w, https://mintcdn.com/base-a060aa97/-q4fo0uzIfxlH3Wn/images/onchainkit/copy-project-id.png?w=560&fit=max&auto=format&n=-q4fo0uzIfxlH3Wn&q=85&s=3353683c600c3d6406473bd9d96b6c3e 560w, https://mintcdn.com/base-a060aa97/-q4fo0uzIfxlH3Wn/images/onchainkit/copy-project-id.png?w=840&fit=max&auto=format&n=-q4fo0uzIfxlH3Wn&q=85&s=fc1ea92d8d5ea02b932ed38b3c5f7933 840w, https://mintcdn.com/base-a060aa97/-q4fo0uzIfxlH3Wn/images/onchainkit/copy-project-id.png?w=1100&fit=max&auto=format&n=-q4fo0uzIfxlH3Wn&q=85&s=4f1b3d6cdb5aecce2bfdef9c679286c1 1100w, https://mintcdn.com/base-a060aa97/-q4fo0uzIfxlH3Wn/images/onchainkit/copy-project-id.png?w=1650&fit=max&auto=format&n=-q4fo0uzIfxlH3Wn&q=85&s=aab84604e4c4ea446cac4d5c93daa659 1650w, https://mintcdn.com/base-a060aa97/-q4fo0uzIfxlH3Wn/images/onchainkit/copy-project-id.png?w=2500&fit=max&auto=format&n=-q4fo0uzIfxlH3Wn&q=85&s=8a9febaf3ca315cb4ffed4be7de2e2f3 2500w" />
</Frame>

2. Add your Project ID to your `.env` file.
2. Add your Project ID to your `.env` file.

```tsx .env theme={null}
NEXT_PUBLIC_ONCHAINKIT_API_KEY=YOUR_PUBLIC_API_KEY
NEXT_PUBLIC_CDP_PROJECT_ID=YOUR_CDP_PROJECT_ID // [!code ++]
```

```tsx .env
// @noErrors
NEXT_PUBLIC_ONCHAINKIT_API_KEY=YOUR_PUBLIC_API_KEY
NEXT_PUBLIC_CDP_PROJECT_ID=YOUR_CDP_PROJECT_ID // [!code ++]
```
</Step>
<Step title="Add Project ID to OnchainKitProvider">
```tsx
// @noErrors

<Step title="Add Project ID to OnchainKitProvider">
```tsx theme={null}
<OnchainKitProvider
apiKey={process.env.NEXT_PUBLIC_ONCHAINKIT_API_KEY}
apiKey={process.env.NEXT_PUBLIC_ONCHAINKIT_API_KEY}
projectId={process.env.NEXT_PUBLIC_CDP_PROJECT_ID} // [!code ++]
chain={base}
>
{props.children}
</OnchainKitProvider>
```
</Step>
<Step title="Drop in the<FundButton /> component">
```tsx
import { FundButton } from '@coinbase/onchainkit/fund';

<FundButton />
```
</Step>

<Step title="Get a session token">
[Getting session
token](https://docs.cdp.coinbase.com/onramp-&-offramp/session-token-authentication)
</Step>

<Step title="Drop in the <FundButton /> component">
```tsx theme={null}
import { FundButton } from '@coinbase/onchainkit/fund';

const sessionToken = "YOUR_SESSION_TOKEN";

// can use EITHER sessionToken or fundingUrl
<FundButton sessionToken={sessionToken} />
```

{/* <App>
<FundWrapper>
{({ address }) => {
if (address) {
return (
<FundButton sessionToken={sessionToken} />
)
}
return <>
<Wallet>
<ConnectWallet>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
</Wallet>
</>;
}}
</FundWrapper>
</App> */}

<App>
<FundWrapper>
{({ address }) => {
if (address) {
return (
<FundButton />
)
}
return <>
<Wallet>
<ConnectWallet>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
</Wallet>
</>;
}}
</FundWrapper>
</App>
</Step>
</Steps>


<Tip>
**Troubleshooting**

If you see a "something went wrong" error message when navigating to pay.coinbase.com, make sure you have "enforce
secure initialization" disabled on the [Onramp config page in Coinbase Developer Platform Dashboard](https://portal.cdp.coinbase.com/products/onramp).

<Frame>
<img alt="OnchainKit require secure init" src="/images/onchainkit/onramp-secure-init.png" />
</Frame>

</Tip>


## Customizing the funding experience

You can customize the Coinbase Onramp experience by bringing your own Onramp URL and passing it to the ```<FundButton />```
You can customize the Coinbase Onramp experience by bringing your own Onramp URL and passing it to the `<FundButton />`
component. We provide the [`getOnrampBuyUrl`](/onchainkit/fund/get-onramp-buy-url) utility to help you generate a Coinbase Onramp
URL tailored to your use case.

```tsx
import { FundButton, getOnrampBuyUrl } from '@coinbase/onchainkit/fund';
import { useAccount } from 'wagmi';
```tsx theme={null}
import { FundButton, getOnrampBuyUrl } from "@coinbase/onchainkit/fund";
import { useAccount } from "wagmi";

const projectId = 'YOUR_CDP_PROJECT_ID';
const projectId = "YOUR_CDP_PROJECT_ID";
const { address } = useAccount();

const onrampBuyUrl = getOnrampBuyUrl({
projectId,
addresses: { [address]: ['base'] },
assets: ['USDC'],
sessionToken: "YOUR_SESSION_TOKEN",
presetFiatAmount: 20,
fiatCurrency: 'USD'
fiatCurrency: "USD",
});

<FundButton fundingUrl={onrampBuyUrl} />
<FundButton fundingUrl={onrampBuyUrl} />;
```

<iframe
src="https://684b5e62b1ff46bc5bf83966-aijszlfakk.chromatic.com/iframe.html?args=&id=onchainkit-fund-button--with-funding-url&viewMode=story&dark=true&hero=true"
width="100%"
height="auto"
/>
{/* <App>
<FundWrapper>
{({ address, projectId }) => {
if (address && projectId) {
const onrampBuyUrl = getOnrampBuyUrl({
projectId,
addresses: { [address]: ['base'] },
assets: ['USDC'],
presetFiatAmount: 20,
fiatCurrency: 'USD'
});
return (
<FundButton fundingUrl={onrampBuyUrl} />
)
}
return <>
<Wallet>
<ConnectWallet>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
</Wallet>
</>;
}}
</FundWrapper>
</App> */}

You can choose to have the funding URL open in a popup or a new tab using the `openIn` prop.

```tsx
<FundButton openIn={"tab"} />
```tsx theme={null}
<FundButton openIn={"tab"} sessionToken={sessionToken} />
```

<iframe
src="https://684b5e62b1ff46bc5bf83966-aijszlfakk.chromatic.com/iframe.html?args=&id=onchainkit-fund-button--open-in-tab&viewMode=story&dark=true&hero=true"
width="100%"
height="auto"
/>
{/* <App>
<FundWrapper>
{({ address }) => {
if (address) {
return (
<FundButton openIn={"tab"} />
)
}
return <>
<Wallet>
<ConnectWallet>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
</Wallet>
</>;
}}
</FundWrapper>
</App> */}

## Customizing the fund button

You can override the text on the fund button using the `text` prop, and hide the icon with the `hideIcon` prop.

```tsx
<FundButton text={"Onramp"} hideIcon={true} />
```tsx theme={null}
<FundButton text={"Onramp"} hideIcon={true} sessionToken={sessionToken} />
```

<iframe
src="https://684b5e62b1ff46bc5bf83966-aijszlfakk.chromatic.com/iframe.html?args=&id=onchainkit-fund-button--custom-text-and-hide-icon&viewMode=story&dark=true&hero=true"
width="100%"
height="auto"
/>
{/* <App>
<FundWrapper>
{({ address }) => {
if (address) {
return (
<FundButton text={"Onramp"} hideIcon={true} />
)
}
return <>
<Wallet>
<ConnectWallet>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
</Wallet>
</>;
}}
</FundWrapper>
</App> */}

You can hide the text with the `hideText` prop.

```tsx
<FundButton hideText={true} />
```tsx theme={null}
<FundButton hideText={true} sessionToken={sessionToken} />
```

<iframe
src="https://684b5e62b1ff46bc5bf83966-aijszlfakk.chromatic.com/iframe.html?args=&id=onchainkit-fund-button--hide-text&viewMode=story&dark=true&hero=true"
width="100%"
height="auto"
/>
{/* <App>
<FundWrapper>
{({ address }) => {
if (address) {
return (
<>
<FundButton hideText={true} />
</>
)
}
return <>
<Wallet>
<ConnectWallet>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
</Wallet>
</>;
}}
</FundWrapper>
</App> */}

See [`FundButtonReact`](/onchainkit/fund/types#fundbuttonreact) for the full list of customization options.

## Props
- [`FundButtonReact`](/onchainkit/fund/types#fundbuttonreact)

[`FundButtonProps`](#fundbuttonprops)

```ts theme={null}
export type FundButtonProps = FundButtonBaseProps &
FundButtonSourceProps &
FundButtonRenderProps;

type FundButtonBaseProps = {
/* An optional CSS class name for styling the button component */
className?: string;
/* A optional prop to disable the fund button */
disabled?: boolean;
/* The state of the button component */
state?: FundButtonState;
/* Whether to open the funding flow in a tab or a popup window */
openIn?: "popup" | "tab";
/**
* Size of the popup window if `openIn` is set to `popup`
* Note: popupSize will be ignored when using a Coinbase Onramp URL (i.e. https://pay.coinbase.com/*) as it requires
* a fixed popup size.
*/
popupSize?: "sm" | "md" | "lg";
/* Where to open the target if `openIn` is set to tab */
target?: string;
/* The currency code of the fiat amount provided in the presetFiatAmount param e.g. USD, CAD, EUR. */
fiatCurrency?: string;
/* A callback function that will be called when the popup window is closed */
onPopupClose?: () => void;
/* A callback function that will be called when the button is clicked */
onClick?: () => void;
};

// Require exactly one funding source for FundButton (not both)
type FundButtonSourceProps =
| { fundingUrl: string; sessionToken?: string }
| { sessionToken: string; fundingUrl?: string };

type FundButtonRenderProps =
| {
render?: (props: FundButtonRenderParams) => React.ReactNode;
/* An optional React node to be displayed in the button component */
children?: never;
}
| {
render?: never;
/* An optional React node to be displayed in the button component */
children?: ReactNode;
};

export type FundButtonRenderParams = {
/* The state of the button component, only relevant when using FundCardSubmitButton */
status: FundButtonState;
/* A callback function that will be called when the button is clicked */
onClick: (e: React.MouseEvent) => void;
/* Whether the button is disabled */
isDisabled: boolean;
};
```

<Note>
**Note:** `FundButton` requires either `sessionToken` or `fundingUrl` to be
provided. If neither is provided, the component will throw an error before
compiling.
</Note>

## Related Components

- [`<FundCard />`](/onchainkit/fund/fund-card)
Loading