Quickstart - Grid

Grid Accounts make it simple to build modern fintech applications with email-based onboarding, programmable spending limits, and sub-penny transaction costs. This guide will get you up and running in minutes.

Grid Accounts currently support any Solana token and are compatible with Solana-based programs, providing a powerful base for composability.

Get API Keys

Before you can start building, you’ll need API credentials from the Grid dashboard.

Get API Keys

Visit the Grid dashboard to generate your sandbox and production API keys

Keep your API keys secure and never expose them in client-side code. Always use environment variables or secure key management systems.

Prerequisites

Before integrating Grid Accounts, ensure you have:

Node.js 18+ or another runtime environment
API credentials from the Grid dashboard
Basic understanding of REST APIs and async/await patterns

SDK Installation

Install the official Grid SDK to get started quickly:

npm install @sqds/grid

The Grid SDK provides TypeScript support out of the box and handles authentication, error handling, and API communication automatically.

Grid SDK Documentation

View complete SDK documentation, API reference, and additional examples on NPM

Migrating from grid-sdk? The new @sqds/grid package provides enhanced features including multi-provider support and React Native compatibility. View our migration guide.

SDK Initialization

Set up your Grid client using the official SDK:

import { GridClient } from "@sqds/grid";

// Initialize the Grid client
const gridClient = new GridClient({
  environment: "sandbox", // Use 'production' for live applications
  apiKey: process.env.GRID_API_KEY!, // Your API key from the dashboard
  baseUrl: "https://grid.squads.xyz", // Base URL of the Grid API
});

// Verify the connection
console.log("Grid client initialized successfully");

// .env file
GRID_API_KEY = your_sandbox_api_key_here;

// For production:
// GRID_API_KEY=your_production_api_key_here
// GRID_ENVIRONMENT=production

// gridClient.ts
import { GridClient } from "@sqds/grid";

if (!process.env.GRID_API_KEY) {
  throw new Error("GRID_API_KEY environment variable is required");
}

export const gridClient = new GridClient({
  environment:
    process.env.GRID_ENVIRONMENT === "production" ? "production" : "sandbox",
  apiKey: process.env.GRID_API_KEY,
  baseUrl: "https://grid.squads.xyz",
});

The Grid SDK automatically handles API authentication, request retries, and error formatting. You don’t need to build your own HTTP client.

Complete Integration Example

SDK Integration
LLM Integration Prompts

Complete workflow from account creation through transaction execution:

Initialize Grid Client

Set up your Grid SDK client with API credentials:

import { GridClient } from '@sqds/grid';

const gridClient = new GridClient({
  environment: 'sandbox', // Use 'production' for live applications
  apiKey: process.env.GRID_API_KEY!,
  baseUrl: "https://grid.squads.xyz",
});

Generate Session Secrets

Create cryptographic keypairs that will authorize all future transactions:

const sessionSecrets = await gridClient.generateSessionSecrets();
console.log('Session secrets generated - these contain private keys needed for signing!');

Session secrets contain private keys that enable transaction signing. Store them encrypted and never expose them in client-side code.

Create Email Account

Create a new Grid account using email-based onboarding:

Grid accounts do not have the same address in sandbox and production. DO NOT send funds to the same address in both environments. Create unique accounts for each environment and ensure you use the correct address for your environment.

const user = await gridClient.createAccount({
  email: 'user@example.com',
});
console.log('Account creation initiated for:', user.email);
console.log('OTP sent to email for verification');

Verify Account with OTP

Complete account verification using the OTP sent to the user’s email:

const verifiedAccount = await gridClient.completeAuthAndCreateAccount({
  user: user,
  otpCode: '123456', // User receives this via email
  sessionSecrets: sessionSecrets,
});
console.log('Account created successfully');

Authenticate Existing Account (Alternative)

For users who already have a Grid account, use the authentication flow:

// Generate fresh session secrets for authentication
const authSessionSecrets = await gridClient.generateSessionSecrets();

// Initialize authentication for existing account
const authUser = await gridClient.initAuth({
  email: 'existing@example.com',
});
console.log('Authentication initiated for:', authUser.email);
console.log('OTP sent to email for verification');

// Complete authentication with OTP
const authenticatedAccount = await gridClient.completeAuth({
  user: authUser,
  otpCode: '123456', // User receives this via email
  sessionSecrets: authSessionSecrets,
});
console.log('Account authenticated successfully');

Use initAuth and completeAuth for existing accounts, or createAccount and completeAuthAndCreateAccount for new account creation. Always generate fresh session secrets for each authentication flow.

Prepare Transaction

Before executing, prepare the transaction payload using the SDK:

const rawTransactionPayload = {
  transaction: "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDArc20SI/X2z8FPQhKgWWbWfXOTI3TDjuQQB8JfpF+1e4u3shfDGrJc7jvYd11DguvNKYg2PsUz7b7GZKwcAjMBoCAAECAAkDAAAAAMOhGsIAAAAA", // Your Solana transaction
  transaction_signers: [verifiedAccount.address] // Optional: only needed when signing with local signers
};

// Prepare the transaction payload
const transactionPayload = await gridClient.prepareArbitraryTransaction(
  verifiedAccount.address,
  rawTransactionPayload
);
console.log('Transaction prepared successfully');

The transaction_signers field is optional and only required when you need to sign the transaction with additional local signers alongside Grid’s signing.

Execute Transactions

Use the signAndSend method to execute the prepared transaction:

const executedTx = await gridClient.signAndSend({
  sessionSecrets, // Private keys for cryptographic signing
  session: verifiedAccount, // Authenticated account session
  transactionPayload, // Prepared transaction payload
  address: verifiedAccount.address
});
console.log('Transaction executed:', executedTx.signature);

The signAndSend method handles both cryptographic signing and network submission in a single call, simplifying transaction execution.

For production applications, implement proper error handling, retry logic, and secure secret management around each of these steps.

Comprehensive LLM prompts that provide complete implementation guidance for Grid Accounts integration:

Step 1: Initialize Grid Client Setup