Documentation

Everything you need to integrate Sovalium AI intelligence into your Solana applications.

Quick Start

Get up and running in 5 minutes with our step-by-step guide.

API Reference

Complete reference for all endpoints, parameters, and responses.

Examples

Real-world code examples and integration patterns.

Contents

Getting Started

Installation

Install the Sovalium SDK via npm or yarn:

npm install @sovalium/sdk

Or using yarn:

yarn add @sovalium/sdk

Basic Setup

Initialize the client with your API key:

import { Sovalium } from '@sovalium/sdk'

const client = new Sovalium({
  apiKey: process.env.SOVALIUM_API_KEY,
  network: 'mainnet-beta' // or 'devnet'
})

// Now you're ready to use the API
const tokens = await client.tokens.list()
console.log(tokens)

Authentication

API Keys

All API requests require authentication using an API key. Include your key in the request headers:

curl https://api.sovalium.com/v1/tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Security: Never expose your API key in client-side code. Always use environment variables and server-side requests.

REST API

Base URL

https://api.sovalium.com/v1

Endpoints

GET/tokens

List all tracked Solana tokens

GET/tokens/:address

Get detailed token information

GET/wallets/:address

Analyze wallet holdings and activity

GET/ai/insights/:address

Get AI-generated market insights

POST/alerts

Create custom price or volume alerts

Example Request

// Get token details
const response = await fetch(
  'https://api.sovalium.com/v1/tokens/So11111111111111111111111111111111111111112',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
)

const token = await response.json()
console.log(token)

WebSocket Streams

Real-Time Updates

Connect to WebSocket streams for live price updates, whale alerts, and market events:

import { Sovalium } from '@sovalium/sdk'

const client = new Sovalium({ apiKey: 'YOUR_API_KEY' })

// Subscribe to token price updates
client.stream.subscribeToPrices(['SOL', 'USDC'], (update) => {
  console.log(`${update.symbol}: $${update.price}`)
})

// Subscribe to whale movements
client.stream.subscribeToWhaleAlerts((alert) => {
  console.log('Whale detected:', alert)
})

// Subscribe to AI insights
client.stream.subscribeToAIInsights((insight) => {
  console.log('New insight:', insight.summary)
})

TypeScript SDK

Full Featured SDK

The TypeScript SDK provides a complete interface to all Sovalium features:

import { Sovalium } from '@sovalium/sdk'

const client = new Sovalium({ apiKey: 'YOUR_API_KEY' })

// Token operations
const tokens = await client.tokens.list()
const token = await client.tokens.get('SOL')
const trending = await client.tokens.trending()

// Wallet analysis
const wallet = await client.wallets.analyze('ADDRESS')
const holdings = await client.wallets.holdings('ADDRESS')

// AI insights
const insights = await client.ai.analyze('SOL')
const summary = await client.ai.summarize(['SOL', 'USDC'])

// Alerts
await client.alerts.create({
  type: 'price',
  token: 'SOL',
  condition: 'above',
  value: 100
})

// Analytics
const analytics = await client.analytics.tokenMetrics('SOL')
const liquidity = await client.analytics.liquidityFlow('SOL')

Rate Limits

Request Limits

Free Tier

100

requests/hour

Pro Tier

1,000

requests/hour

Enterprise

Custom

unlimited

Rate limit headers are included in every response. Monitor your usage to avoid throttling.

Error Handling

HTTP Status Codes

200

Request successful

400

Bad Request

Invalid parameters or malformed request

401

Unauthorized

Missing or invalid API key

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Something went wrong on our end

Error Response Format

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Token address is invalid or not found",
    "details": {
      "address": "invalid_address"
    }
  }
}