axova-aggregator

Lightweight TypeScript client for the Axova Solana DEX Aggregator API. Zero runtime dependencies — uses native fetch (Node 18+, browsers, Deno, Bun).

Install

npm install axova-aggregator

Quick Start

import { AxovaSDK } from 'axova-aggregator';

const axova = new AxovaSDK({ apiKey: 'axova_...' });

// Get a quote
const quote = await axova.getQuote({
  inputMint: 'So11111111111111111111111111111111111111112',   // SOL
  outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  amount: 1_000_000_000, // 1 SOL in lamports
});
console.log(quote.amountOut, quote.hops);

// Build a swap transaction
const { tx } = await axova.buildSwap({
  route: quote.route,
  amountIn: 1_000_000_000,
  userPublicKey: 'YourWalletPublicKey...',
});
// Sign `tx` with your wallet, then broadcast to Solana

// Check rate limit after any call
console.log(axova.rateLimit);
// { limit: 600, remaining: 599, reset: 58 }

Configuration

const axova = new AxovaSDK({
  apiKey: 'axova_...',                           // optional — free tier if omitted
  baseUrl: 'https://axovabackend.axova.xyz',     // default
  timeout: 30000,                                 // ms, default 30s
});

API Methods

Health & Tokens

| Method | Returns | |--------|---------| | getHealth() | HealthStatus | | getTokens() | TokenMetadata[] |

Quotes & Routing

| Method | Returns | |--------|---------| | getQuote({ inputMint, outputMint, amount }) | RouteResult | | getRoutes({ inputMint, outputMint, amount, slippage? }) | RouteResult[] |

Swap

| Method | Returns | |--------|---------| | buildSwap({ route, amountIn, userPublicKey, slippage?, affiliate? }) | SwapResult | | simulate({ inputMint, outputMint, amountIn, slippage?, userPubkey? }) | SimulateResult |

Analytics

| Method | Returns | |--------|---------| | getTrendingTokens({ count?, windowMs?, byVolume? }) | TrendingToken[] | | getTrendingPairs({ count?, windowMs?, byVolume? }) | TrendingPair[] | | getTimeseries({ windowMs?, bucketMs? }) | TimeseriesBucket[] | | getTrendingByDex({ count?, windowMs?, byVolume? }) | DexStats[] |

Tiers & API Keys

| Method | Auth | Returns | |--------|------|---------| | getTiers() | None | TierInfo[] | | createApiKey(authToken, { tier? }) | JWT | ApiKeyInfo | | listApiKeys(authToken) | JWT | ApiKeyInfo[] | | revokeApiKey(authToken, apiKey) | JWT | { success: boolean } | | upgradeApiKey(authToken, apiKey, tier) | JWT | ApiKeyInfo & { upgraded } |

User Stats

| Method | Auth | Returns | |--------|------|---------| | getUsage(authToken) | JWT | UsageStats | | getUserTier(authToken) | JWT | UserTierInfo |

Authentication

API key (set once in constructor) is sent as x-api-key on every request:

const axova = new AxovaSDK({ apiKey: 'axova_abc123' });

JWT auth token is passed per-call for user-scoped endpoints (keys, usage, tier). Tokens expire every 15 minutes — refresh them via the /auth/refresh endpoint.

const keys = await axova.listApiKeys('eyJhbG...');

Error Handling

All API errors throw AxovaError:

import { AxovaSDK, AxovaError } from 'axova-aggregator';

try {
  await axova.getQuote({ inputMint: '', outputMint: '', amount: 0 });
} catch (err) {
  if (err instanceof AxovaError) {
    console.log(err.message); // "Missing inputMint"
    console.log(err.status);  // 400
    console.log(err.code);    // undefined or "TOKEN_EXPIRED", "RATE_LIMITED", etc.
  }
}

Timeouts throw AxovaError with code: 'TIMEOUT' and status: 0.

Rate Limiting

After every API call, axova.rateLimit is updated with the latest values:

await axova.getQuote({ ... });
console.log(axova.rateLimit);
// { limit: 600, remaining: 598, reset: 42 }

Tiers:

• free — 60 req/min
• premium — 600 req/min
• partner — 2,000 req/min
• superuser — unlimited

Affiliate Fees

Pass an affiliate config to earn referral fees on swaps:

await axova.buildSwap({
  route: quote.route,
  amountIn: 1_000_000_000,
  userPublicKey: 'User...',
  affiliate: {
    address: 'YourWallet...',
    feeBps: 25, // 0.25%
  },
});

Maximum affiliate fee: 30 bps (0.30%). Platform fee: 20 bps (0.20%).

TypeScript

All types are exported:

import type {
  RouteResult,
  TokenMetadata,
  TrendingToken,
  AxovaSDKConfig,
  RateLimitInfo,
} from 'axova-aggregator';

License

MIT