Quickstart
1) Install package
yarn add @tanstack/react-query@"^5.64.2" @chakra-ui/react@"^2.8.2" @vechain/dapp-kit-react@"1.4.1" @vechain/vechain-kit
// or
npm i @tanstack/react-query@"^5.64.2" @chakra-ui/react@"^2.8.2" @vechain/dapp-kit-react@"1.4.1" @vechain/vechain-kit
Only supported on React and Next.js
React query, chakra and dapp-kit are peer dependencies.
2) Define Provider
'use client';
import {VeChainKitProvider} from "@vechain/vechain-kit";
export function VeChainKitProviderWrapper({children}: any) {
return (
<VeChainKitProvider
feeDelegation={{
delegatorUrl: "https://sponsor-testnet.vechain.energy/by/441",
// set to false if you want to delegate ONLY social login transactions
// social login transactions sponsorship is currently mandatory
delegateAllTransactions: false,
}}
loginMethods={[
{method: "vechain", gridColumn: 4},
{method: "dappkit", gridColumn: 4},
]}
dappKit={{
allowedWallets: ["veworld", "wallet-connect", "sync2"],
walletConnectOptions: {
projectId:
// Get this on https://cloud.reown.com/sign-in
process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
metadata: {
name: "React Dapp Template",
description: "This is the description of your app visible in VeWorld upon connection request.",
url: typeof window !== "undefined" ? window.location.origin : "",
icons: ["https://path-to-logo.png"],
},
},
}}
darkMode={false}
language="en"
network={{
type: "test",
}}
>
{children}
</VeChainKitProvider>
);
}
On Next.js you will need to dynamically load the import
import dynamic from 'next/dynamic';
const VeChainKitProvider = dynamic(
async () =>
(await import('@vechain/vechain-kit')).VeChainKitProvider,
{
ssr: false,
},
);
Login Methods
The modal implements a dynamic grid layout system that can be customized through the loginMethods
configuration.
The modal can be configured through the VeChainKitProvider
props.
<VeChainKitProvider
loginModalUI={{
logo: '/your-logo.png',
description: 'Custom login description',
}}
loginMethods={[
{ method: 'vechain', gridColumn: 4 },
{ method: 'dappkit', gridColumn: 4 }, // VeChain wallets, always available
{ method: 'ecosystem', gridColumn: 4 }, // Mugshot, Cleanify, Greencart, ...
{ method: 'email', gridColumn: 2 }, // only available with your own Privy
{ method: 'passkey', gridColumn: 2 }, // only available with your own Privy
{ method: 'google', gridColumn: 4 }, // only available with your own Privy
{ method: 'more', gridColumn: 2 }, // will open your own Privy login, only available with your own Privy
]}
allowCustomTokens={false} // allow the user to manage custom tokens
>
{children}
</VeChainKitProvider>
Login methods selection:
vechain, dappkit, and ecosystem are always available options
The Privy-dependent methods (email, google, passkey, more) are only available when the privy prop is defined
TypeScript will show an error if someone tries to use a Privy-dependent method when privy is not configured
// This will show a type error
const invalidConfig: VechainKitProviderProps = {
// no privy prop specified
loginMethods: [
{ method: 'email' } // ❌ Type error: 'email' is not assignable to type 'never'
],
// ... other required props
};
// This is valid
const validConfig1: VechainKitProviderProps = {
// no privy prop
loginMethods: [
{ method: 'vechain' }, // ✅ OK
{ method: 'dappkit' }, // ✅ OK
{ method: 'ecosystem' } // ✅ OK
],
// ... other required props
};
// This is also valid
const validConfig2: VechainKitProviderProps = {
privy: {
appId: 'xxx',
clientId: 'yyy',
// ... other privy props
},
loginMethods: [
{ method: 'email' }, // ✅ OK because privy is configured
{ method: 'google' }, // ✅ OK because privy is configured
{ method: 'vechain' }, // ✅ OK (always allowed)
{ method: 'ecosystem' } // ✅ OK (always allowed)
],
// ... other required props
};
3) Setup Fee Delegation (mandatory if allowing social login)
Fee delegation is mandatory if you want to use this kit with social login. Learn how to setup fee delegation in the following guide:
Fee Delegation4) Setup Privy (optional)
If you have your own Privy app, you can pass an additional prop with your settings.
import { VechainKitProvider } from '@vechain/vechain-kit';
export default function App({ Component, pageProps }: AppProps) {
return (
<VechainKitProvider
privy={{
appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID!,
clientId: process.env.NEXT_PUBLIC_PRIVY_CLIENT_ID!,
loginMethods: ['google', 'twitter', 'sms', 'email'],
appearance: {
walletList: ['metamask', 'rainbow'],
accentColor: '#696FFD',
loginMessage: 'Select a social media profile',
logo: 'https://i.ibb.co/ZHGmq3y/image-21.png',
},
embeddedWallets: {
createOnLogin: 'all-users',
},
allowPasskeyLinking: true,
}}
...
//other props
>
{children}
</VechainKitProvider>
);
}
Go to privy.io and create an app. You will find the APP ID and the CLIENT ID in the App Settings tab.
For further information on how to implement Privy SDK please refer to their docs: https://docs.privy.io/
This project uses:
@privy-io/react-auth for Privy connection type
@privy-io/cross-app-connect for ecosystem cross app connection
You can import privy from the kit as
import { usePrivy } from "@vechain/vechain-kit";
const { user } = usePrivy();
If you setup your own Privy be sure to go over the recommended security settings provided by Privy: https://docs.privy.io/guide/security/implementation/ and https://docs.privy.io/guide/security/implementation/csp
5) Setup Legal Documents (optional)
To prompt users to review and accept your policies, like Terms and Conditions, Privacy Policy, or Cookie Policy, VeChainKit offers a simple plug-and-play solution.
You can avoid building your own if you haven't already.
By enabling also the tracking consent, you will allow VeChainKit to prompt your users to collect data to improve the kit.
When the legalDocuments
option is configured, the users will see:
Left: A modal prompt when connecting their wallet, requiring them to review and accept required and optional legal documents.
Right: A summary view under
Settings > General > Terms and Policies
, showing which policies they’ve accepted and when.


import { VechainKitProvider } from '@vechain/vechain-kit';
export default function App({ Component, pageProps }: AppProps) {
return (
<VechainKitProvider
legalDocuments={{
allowAnalytics: true, // Enables optional consent for VeChainKit tracking
cookiePolicy: [
{
displayName: 'MyApp Policy', // (Optional) Custom display label
url: 'https://www.myapp.com/cookie-policy',
version: 1, // Increment to re-prompt users
required: false, // Optional: User sees a checkbox to opt in
},
],
privacyPolicy: [
{
url: 'https://www.myapp.com/privacy-policy',
version: 1, // Increment to re-prompt users
required: false, // Optional: can be skipped or rejected
},
],
termsAndConditions: [
{
displayName: 'MyApp T&C',
url: 'https://www.myapp.com/terms-and-conditions',
version: 1, // Increment to re-prompt users
required: true, // Required: must be accepted to proceed
},
],
}}
// ... other props
>
{children}
</VechainKitProvider>
);
}
Key Options
allowAnalytics
boolean
No
If true
, prompts users with an optional tracking policy.
cookiePolicy
array
No
One or more cookie policy versions.
privacyPolicy
array
No
One or more privacy policy versions.
termsAndConditions
array
No
One or more T&C versions.
6) Show the login button
Once you set up the kit provider, you are good to go, and you can allow your users to login, customizing the login experience based on your needs. You can choose between many options, leaving you complete freedom on your design.
When your app is opened inside VeWorld mobile wallet, VeWorld is always enforced as a login choice.
Support for devs
Are you having issues using the kit? Join our discord server to receive support from our devs or open an issue on our Github!
Check our Troubleshooting section.
Contact us on Discord: https://discord.gg/wGkQnPpRVq
Open an issue on Github: https://github.com/vechain/vechain-kit/issues
Last updated
Was this helpful?