Skip to content

SDK Installation

Complete installation guide for the Grapevine SDK.

Package Installation

Using Bun (Recommended)

bun add @pinata/grapevine-sdk

Using npm

npm install @pinata/grapevine-sdk

Using pnpm

pnpm add @pinata/grapevine-sdk

Using Yarn

yarn add @pinata/grapevine-sdk

Requirements

  • Node.js 18+ or Bun 1.0+
  • TypeScript 5.0+ (optional but recommended)
  • Wallet with ETH for gas fees
  • USDC for payments (testnet or mainnet)

Project Setup

Choose your setup based on your use case:

Backend/Script Setup

For server-side applications, CLI tools, or scripts using private keys.

1. Initialize Your Project

# Using Bun
bun init
 
# Using npm
npm init -y

2. Install Dependencies

bun add @pinata/grapevine-sdk dotenv
# or
npm install @pinata/grapevine-sdk dotenv

3. Configure Environment

Create a .env file:

PRIVATE_KEY=0x_your_private_key_here

Security Note: Never commit your .env file! Add it to .gitignore:

echo ".env" >> .gitignore

4. Create Your First Script

Create index.ts:

import { GrapevineClient } from '@pinata/grapevine-sdk';
import dotenv from 'dotenv';
 
dotenv.config();
 
const grapevine = new GrapevineClient({
  network: 'testnet',
  privateKey: process.env.PRIVATE_KEY
});
 
// Your code here
const feed = await grapevine.feeds.create({
  name: 'My First Feed'
});
 
console.log('Feed created:', feed.id);

5. Run Your Script

# Using Bun
bun run index.ts
 
# Using Node with tsx
npx tsx index.ts

React/Frontend Setup

For dApps where users connect their own wallets.

1. Create React App

# Using Vite (recommended)
npm create vite@latest my-grapevine-app -- --template react-ts
cd my-grapevine-app

2. Install Dependencies

npm install @pinata/grapevine-sdk wagmi viem @tanstack/react-query

3. Configure Wagmi

Create src/wagmi.config.ts:

import { createConfig, http } from 'wagmi';
import { base, baseSepolia } from 'wagmi/chains';
import { injected, walletConnect } from 'wagmi/connectors';
 
const projectId = 'YOUR_WALLETCONNECT_PROJECT_ID'; // Get from https://cloud.walletconnect.com
 
export const config = createConfig({
  chains: [base, baseSepolia],
  connectors: [
    injected(),
    walletConnect({ projectId }),
  ],
  transports: {
    [base.id]: http(),
    [baseSepolia.id]: http(),
  },
});

4. Setup App Provider

Update src/main.tsx:

import React from 'react';
import ReactDOM from 'react-dom/client';
import { WagmiProvider } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { config } from './wagmi.config';
import App from './App';
import './index.css';
 
const queryClient = new QueryClient();
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <App />
      </QueryClientProvider>
    </WagmiProvider>
  </React.StrictMode>
);

5. Use Grapevine with Wagmi

Update src/App.tsx:

import { useGrapevine } from '@pinata/grapevine-sdk/react';
import { useWalletClient, useAccount, useConnect } from 'wagmi';
import { injected } from 'wagmi/connectors';
 
function App() {
  const { address, isConnected } = useAccount();
  const { data: walletClient } = useWalletClient();
  const { connect } = useConnect();
  
  const grapevine = useGrapevine({
    walletClient,
    address,
    network: 'testnet'
  });
  
  const createFeed = async () => {
    if (!grapevine) return;
    const feed = await grapevine.feeds.create({
      name: 'My First Feed'
    });
    console.log('Created:', feed);
  };
  
  if (!isConnected) {
    return (
      <button onClick={() => connect({ connector: injected() })}>
        Connect Wallet
      </button>
    );
  }
  
  return (
    <div>
      <p>Connected: {address}</p>
      {grapevine && <button onClick={createFeed}>Create Feed</button>}
    </div>
  );
}
 
export default App;

6. Run Your App

npm run dev

TypeScript Configuration

For TypeScript projects, create/update tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Command Line Interface (CLI)

For command-line usage, install the separate CLI package:

npm install -g @pinata/grapevine-cli

Verify installation:

grapevine --version
grapevine --help

For more details, see CLI Installation.

Getting Test Tokens

Base Sepolia ETH

Get test ETH from: Alchemy Faucet

Test USDC

Options for getting test USDC:

  1. Bridge from Ethereum Sepolia
  2. Use a test token faucet
  3. Contact Grapevine support

Verification

Test your installation:

import { GrapevineClient } from '@pinata/grapevine-sdk';
 
const grapevine = new GrapevineClient({
  network: 'testnet',
  privateKey: process.env.PRIVATE_KEY,
  debug: true
});
 
// Should log client info
console.log('SDK initialized successfully');

Troubleshooting

Module not found

If you get "Cannot find module '@pinata/grapevine-sdk'":

# Clear cache and reinstall
rm -rf node_modules
rm package-lock.json  # or bun.lock
bun install  # or npm install

TypeScript errors

Install type definitions:

bun add -D @types/node typescript

Private key errors

Ensure your private key:

  • Starts with 0x
  • Is 66 characters long
  • Is from a funded wallet

Next Steps