Authentication - Helius Docs

Helius API Authentication

Helius API uses API keys to authenticate requests. Every API request must include your API key to verify your identity and permissions.

Your API key is sensitive information that grants access to your Helius account. Never expose it in client-side code, public repositories, or browser-accessible areas.

Getting Started

1. Create Your API Key

  1. Sign up or log in
    Create an account on the Helius Dashboard or log in to your existing account.

  2. Navigate to API Keys
    Go to the API Keys section in your dashboard sidebar.

  3. Generate a new key
    Click Create New API Key and provide a descriptive name for your project (e.g., “Production App”, “Development Environment”).

  4. Copy and secure your key
    Copy your API key immediately and store it securely. You won’t be able to see it again once you navigate away.

2. Using Your API Key

Include your API key as a query parameter in all requests:

cURL

curl "https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getAccountInfo","params":["ACCOUNT_ADDRESS"]}'

JavaScript

const url = `https://mainnet.helius-rpc.com/?api-key=${YOUR_API_KEY}`;
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'getAccountInfo',
    params: ['ACCOUNT_ADDRESS']
  })
});

Python

import requests

url = f"https://mainnet.helius-rpc.com/?api-key={YOUR_API_KEY}"
payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getAccountInfo",
    "params": ["ACCOUNT_ADDRESS"]
}
response = requests.post(url, json=payload)

Getting Started (For Agents)

Agents can programmatically sign up for Helius accounts, create projects, and generate API keys using the Helius CLI. For complete instructions, read: https://dashboard.helius.dev/agents.md

Install the Helius CLI

npm install -g helius-cli

Generate a Keypair

helius keygen

Fund the Generated Wallet (Autopay only)

Skip this step if paying via the hosted payment link (--pay / --resume). For autopay, send 1 USDC and 0.001 SOL to the wallet address provided in Step 2.

Signup and Get API Key

helius signup --email you@example.com --first-name Jane --last-name Doe --json

Security Best Practices

Environment Variables

Store your API key in environment variables, not in your source code.

export HELIUS_API_KEY="YOUR_API_KEY"

IP Restrictions

Set up IP restrictions for your API keys in the dashboard to limit access to specific IP addresses or ranges.

Separate Keys

Use different API keys for development, staging, and production environments to isolate usage and improve security.

Monitor Usage

Regularly check your API usage in the dashboard to detect unusual patterns or potential security issues.

Secret Management

// Use environment variables
const apiKey = process.env.HELIUS_API_KEY;

// Or use a secrets manager
const { SecretManagerServiceClient } = require('@google-cloud/secret-manager');
const client = new SecretManagerServiceClient();

async function getApiKey() {
  const [version] = await client.accessSecretVersion({
    name: 'projects/PROJECT_ID/secrets/helius-api-key/versions/latest',
  });
  return version.payload.data.toString();
}

import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()
api_key = os.getenv('HELIUS_API_KEY')

# Or use AWS Secrets Manager
import boto3

def get_secret():
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId='helius-api-key')
    return response['SecretString']

# In your Dockerfile
ENV HELIUS_API_KEY=""

# Or use Docker secrets
RUN --mount=type=secret,id=helius_key \
    cat /run/secrets/helius_key > /app/api_key.txt

Rate Limits & Usage

Rate limits vary by subscription plan. Monitor your usage in the Helius Dashboard to ensure you stay within your allocated limits.

Understanding Rate Limits

Handling Rate Limits

JavaScript

async function makeRequest(url, data) {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });

if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      console.log(`Rate limited. Retry after ${retryAfter} seconds`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return makeRequest(url, data); // Retry
    }

return response.json();
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

Python

import time
import requests

def make_request(url, data):
    try:
        response = requests.post(url, json=data)

if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after} seconds...")
            time.sleep(retry_after)
            return make_request(url, data)  # Retry

response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        raise

Troubleshooting

Invalid API Key Error

Symptoms: 401 Unauthorized or "Invalid API Key" errors

Solutions:

Rate Limit Exceeded

Symptoms: 429 Too Many Requests errors

Solutions:

Forbidden Access

Symptoms: 403 Forbidden errors

Solutions:

Next Steps

Quickstart Guide
Start making your first API calls with Helius

API Reference
Explore all available endpoints and methods

Rate Limits
Understand rate limits and upgrade options

Dashboard
Monitor your API usage and manage keys

Support

Need help with authentication or have questions about API keys?

Discord Community
Join our Discord for real-time help and community support

Email Support
Contact our support team directly