persolator-sdk

Official TypeScript/JavaScript SDK for the Persolator permissionless perpetual futures protocol on Solana Devnet.

Overview

persolator-sdk gives you full programmatic access to the Persolator protocol from any JavaScript or TypeScript environment. Every API endpoint is covered — markets, positions, leaderboard, faucet, vault, and on-chain scan — with complete TypeScript types and zero external dependencies.

• Dual package — ESM (import) and CJS (require) outputs included
• Full TypeScript types — every request param and response shape is typed
• Zero dependencies — uses native fetch (Node.js ≥ 18)
• Error class — PersolatorError with HTTP status code
• Configurable — custom base URL and timeout

Installation

npm install persolator-sdk
# or
pnpm add persolator-sdk
# or
yarn add persolator-sdk

Requires Node.js ≥ 18 (for native fetch).

Quick Start

import { PersolatorClient } from "persolator-sdk";

const client = new PersolatorClient();

// List all active markets
const markets = await client.listMarkets({ sort: "volume" });
console.log(markets[0].symbol, markets[0].price);

// Protocol-wide stats
const stats = await client.getStats();
console.log(`24h Volume: $${stats.totalVolume24h.toLocaleString()}`);
console.log(`Active Traders: ${stats.activeTraders}`);

// Claim 1,000 devnet USDC
const claim = await client.claimFaucet("<your-wallet-address>");
console.log(`Claimed! TX: ${claim.txHash}`);

// Open a position (after sending USDC to vault on-chain)
const position = await client.openPosition({
  marketSymbol: "SOL-PERP",
  side: "long",
  collateral: 100,
  leverage: 5,
  wallet: "<your-wallet>",
  txHash: "<usdc-transfer-txhash>",
});
console.log(`Position opened: $${position.size} notional at $${position.entryPrice}`);

// Close it
const closed = await client.closePosition(position.id);
console.log(`P&L: $${closed.unrealizedPnl} | Payout TX: ${closed.payoutTx}`);

Client Options

const client = new PersolatorClient({
  baseUrl: "https://api.persolator.xyz", // default
  timeout: 10_000,                       // ms, default 10s
});

// Point to local API during development
const localClient = new PersolatorClient({
  baseUrl: "http://localhost:3001",
});

API Reference

Markets

// List all markets
client.listMarkets(options?)
// options: { sort?: "volume" | "openInterest" | "newest" | "gainers" | "losers", search?: string }
// → Promise<Market[]>

// Get a single market with detail
client.getMarket(symbol: string)
// → Promise<MarketDetail>

// Simulated order book
client.getOrderBook(symbol: string)
// → Promise<OrderBook>

// Recent trades for a market
client.getMarketTrades(symbol: string, options?)
// options: { limit?: number, offset?: number }
// → Promise<Trade[]>

// Launch a new perpetual market
client.launchMarket(params: LaunchMarketParams)
// → Promise<Market>

Stats

// Global protocol statistics
client.getStats()
// → Promise<ProtocolStats>

// Top markets by volume
client.getTrendingMarkets(options?)
// options: { limit?: number }
// → Promise<Market[]>

Positions

// List open positions (filter by wallet or market)
client.listPositions(options?)
// options: { wallet?: string, marketSymbol?: string }
// → Promise<Position[]>

// USDC balance of a wallet
client.getBalance(wallet: string)
// → Promise<WalletBalance>

// Open a position
client.openPosition(params: OpenPositionParams)
// → Promise<Position>

// Close a position by ID
client.closePosition(id: number)
// → Promise<ClosedPosition>

Note on openPosition: The protocol requires you to first send USDC to the vault on-chain as collateral. Pass the transaction hash in txHash — the API verifies the transfer before recording the position.

Faucet

// Faucet configuration
client.getFaucetInfo()
// → Promise<FaucetInfo>  { usdcPerClaim: 1000 }

// Check if wallet can claim
client.getFaucetStatus(wallet: string)
// → Promise<FaucetStatus>  { canClaim: boolean, nextClaimAt?: string }

// Claim 1,000 devnet USDC
client.claimFaucet(wallet: string)
// → Promise<FaucetClaimResult>  { txHash, explorerUrl, amount }

Vault

// Protocol vault info
client.getVault()
// → Promise<VaultInfo>  { vaultAddress, usdcMint, vaultAta, solBalance, usdcBalance }

Leaderboard

client.getLeaderboard(options?)
// options: { limit?: number }
// → Promise<LeaderboardEntry[]>
// Each entry: { rank, wallet, totalPnl, realizedPnl, winRate, totalTrades, totalVolume }

Scan (On-Chain Transactions)

// Recent protocol transactions
client.getScanTransactions(options?)
// options: { limit?: number }
// → Promise<ScanTransaction[]>

// All transactions for a wallet
client.getScanWallet(wallet: string)
// → Promise<WalletScan>

TypeScript Types

All types are exported from the package root:

import type {
  Market,
  MarketDetail,
  MarketStatus,
  OracleType,
  OrderBook,
  OrderBookLevel,
  Trade,
  Position,
  ClosedPosition,
  PositionSide,
  PositionStatus,
  ProtocolStats,
  LeaderboardEntry,
  FaucetInfo,
  FaucetStatus,
  FaucetClaimResult,
  VaultInfo,
  WalletBalance,
  ScanTransaction,
  WalletScan,
  OpenPositionParams,
  LaunchMarketParams,
  ListMarketsOptions,
  PersolatorClientOptions,
} from "persolator-sdk";

Error Handling

All methods throw PersolatorError on failure. It includes an HTTP statusCode when applicable.

import { PersolatorClient, PersolatorError } from "persolator-sdk";

const client = new PersolatorClient();

try {
  const position = await client.openPosition({ ... });
} catch (err) {
  if (err instanceof PersolatorError) {
    console.error(err.message);     // "USDC transfer not verified: ..."
    console.error(err.statusCode);  // 400
  }
}

Common status codes:

| Code | Reason | |------|--------| | 400 | Invalid params / USDC transfer not verified | | 404 | Market or position not found | | 409 | Market symbol already exists | | 503 | Vault or RPC unavailable |

Live Example

import { PersolatorClient } from "persolator-sdk";

const client = new PersolatorClient();

async function main() {
  // 1. Check available markets
  const markets = await client.listMarkets({ sort: "gainers" });
  console.log("Top gainer:", markets[0].symbol, `+${markets[0].priceChange24h.toFixed(2)}%`);

  // 2. Get leaderboard
  const board = await client.getLeaderboard({ limit: 5 });
  board.forEach(e => console.log(`#${e.rank} ${e.wallet.slice(0, 8)}... PnL: $${e.totalPnl}`));

  // 3. Check vault
  const vault = await client.getVault();
  console.log("Vault:", vault.vaultAddress);
  console.log("USDC balance:", vault.usdcBalance);
}

main();

Protocol Links

| Resource | URL | |----------|-----| | Trading App | persolator.xyz | | API | api.persolator.xyz | | Explorer | scan.persolator.xyz | | Docs | persolator.xyz/docs | | CLI | persolator-cli | | Token $PERS | 5ko233fJDq7aQa3jY7ivszY9TJ5cpwQhHEbPtqVtpump |

Network

This SDK targets Solana Devnet. No real funds are involved. All positions, trades, and payouts use a protocol-issued devnet USDC token.

License

MIT