PinPet SDK

A JavaScript/TypeScript SDK for interacting with the SpinPet protocol on the Solana blockchain. Supports both Node.js and browser environments, providing modular functionality for trading, token management, order management, and more.

Features

• =� Spot Trading: Direct buy and sell operations for tokens
• =� Margin Trading: Leverage trading with long/short positions
• = Dual Data Sources: Fast API and reliable on-chain data access
• =� Token Creation: Create and launch new tokens on the protocol
• <� Trade Simulation: Pre-calculate slippage and costs before execution
• =� Comprehensive Tooling: Order management, AMM calculations, and utilities
• < Cross-Platform: Works in Node.js and modern browsers
• =� Modular Design: Clean, intuitive API with separate functional modules

Installation

npm install pinpet-sdk @solana/web3.js @coral-xyz/anchor

or with Yarn:

yarn add pinpet-sdk @solana/web3.js @coral-xyz/anchor

Quick Start

const { PinPetSdk, getDefaultOptions, SPINPET_PROGRAM_ID } = require('pinpet-sdk');
const { Connection } = require('@solana/web3.js');
const anchor = require('@coral-xyz/anchor');

// 1. Get network configuration
const options = getDefaultOptions('MAINNET'); // or 'DEVNET', 'LOCALNET'

// 2. Create connection
const connection = new Connection(options.solanaEndpoint, 'confirmed');

// 3. Initialize SDK
const sdk = new PinPetSdk(connection, SPINPET_PROGRAM_ID, options);

// 4. Example: Buy tokens
const result = await sdk.trading.buy({
  mintAccount: "TOKEN_ADDRESS",
  buyTokenAmount: new anchor.BN('1000000'), // 1 token (6 decimals)
  maxSolAmount: new anchor.BN('2000000000'), // 2 SOL (9 decimals)
  payer: wallet.publicKey
});

// 5. Sign and send transaction
result.transaction.feePayer = wallet.publicKey;
result.transaction.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
result.transaction.sign(wallet);

const signature = await connection.sendRawTransaction(result.transaction.serialize());
await connection.confirmTransaction(signature);

console.log('Transaction successful!', signature);

SDK Architecture

The SDK is organized into functional modules, all accessible through the main PinPetSdk class:

const sdk = new PinPetSdk(connection, SPINPET_PROGRAM_ID, options);

// Trading operations
await sdk.trading.buy({...});
await sdk.trading.sell({...});
await sdk.trading.long({...});
await sdk.trading.short({...});

// Data access (unified interface)
const orders = await sdk.data.orders(mint, { type: 'down_orders' });
const price = await sdk.data.price(mint);

// Token creation
await sdk.token.create({...});

// Trade simulation
const simulation = await sdk.simulator.simulateTokenBuy(mint, amount);

// Utility tools
await sdk.tools.approveTrade({...});

Module Overview

| Module | Purpose | Key Methods | |--------|---------|-------------| | TradingModule | Execute trades | buy, sell, long, short, closeLong, closeShort | | FastModule | API data access | mints, mint_info, orders, price, user_orders | | ChainModule | On-chain data | getCurveAccount, orders, price, user_orders | | TokenModule | Token creation | create, createAndBuy | | ParamModule | Parameter management | createParams, getParams, getAdmin | | SimulatorModule | Trade simulation | simulateTokenBuy, simulateTokenSell, simulateLongStopLoss | | ToolsModule | Utility functions | approveTrade, closeTradeCooldown, validateCooldown | | CurveAMM | AMM calculations | u128ToDecimal, buyFromPriceToPrice, sellFromPriceToPrice |

Documentation

Quick Reference

• =� Quick Start Guide - Get up and running quickly
• <� SDK Main Class - Core initialization and configuration
• =� Complete Documentation Index - Full documentation table of contents

Core Modules

• Trading Module - Spot and margin trading operations (Translation in progress)
• Fast Module - API-based data access (Translation in progress)
• Chain Module - On-chain data reading (Translation in progress)
• Token Module - Token creation and management
• Param Module - Partner parameter management
• Simulator Module - Trade simulation and calculations (Translation in progress)

Utilities

• CurveAMM Utility - AMM curve calculations (Translation in progress)
• Constants & Helpers - Configuration and helper functions
• Tools Module - Trading utilities and cooldown management
• Position Tab Guide - UI integration guide for positions

Language Options

• <�<� English Documentation: ./doc/ (Current)
• <�<� -��c: ./doc_cn/

Network Configuration

The SDK supports three network environments:

// Mainnet (Production)
const mainnetOptions = getDefaultOptions('MAINNET');

// Devnet (Testing)
const devnetOptions = getDefaultOptions('DEVNET');

// Localnet (Local Development)
const localnetOptions = getDefaultOptions('LOCALNET');

Data Source Options

Choose between fast API access or reliable on-chain reading:

// Fast API (default) - Quick responses, slight latency
const sdk = new PinPetSdk(connection, SPINPET_PROGRAM_ID, {
  ...options,
  defaultDataSource: 'fast'
});

// On-chain direct reading - More reliable, slower
const sdk = new PinPetSdk(connection, SPINPET_PROGRAM_ID, {
  ...options,
  defaultDataSource: 'chain'
});

// Or switch temporarily per call
const orders = await sdk.data.orders(mint, {
  type: 'down_orders',
  dataSource: 'chain' // Override default
});

Key Concepts

Precision Handling

• SOL: 9 decimal places (lamports) - 1 SOL = 1,000,000,000 lamports
• Tokens: 6 decimal places - 1 Token = 1,000,000 units
• Price: u128 format with 28-digit precision

// SOL amounts
const oneSol = new anchor.BN('1000000000'); // 1 SOL

// Token amounts
const oneToken = new anchor.BN('1000000'); // 1 Token

// Price conversion
const { CurveAMM } = require('pinpet-sdk');
const decimalPrice = CurveAMM.u128ToDecimal(priceU128);
const priceU128 = CurveAMM.decimalToU128(decimalPrice);

Transaction Signing

The SDK returns unsigned transactions for security and wallet compatibility:

// SDK builds the transaction
const result = await sdk.trading.buy({...});

// You control the signing
result.transaction.feePayer = wallet.publicKey;
result.transaction.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;

// Sign with your wallet
const signature = await wallet.sendTransaction(result.transaction, connection);

Example Use Cases

Spot Trading

// Buy tokens
const buyResult = await sdk.trading.buy({
  mintAccount: mint,
  buyTokenAmount: new anchor.BN('1000000'),
  maxSolAmount: new anchor.BN('2000000000'),
  payer: wallet.publicKey
});

// Sell tokens
const sellResult = await sdk.trading.sell({
  mintAccount: mint,
  sellTokenAmount: new anchor.BN('1000000'),
  minSolOutput: new anchor.BN('1800000000'),
  payer: wallet.publicKey
});

Margin Trading

// Open long position
const longResult = await sdk.trading.long({
  mintAccount: mint,
  buyTokenAmount: new anchor.BN('10000000'),
  maxSolAmount: new anchor.BN('20000000000'),
  marginSol: new anchor.BN('5000000000'),
  closePrice: new anchor.BN('...'),
  closeInsertIndices: [...],
  payer: wallet.publicKey
});

// Close long position
const closeResult = await sdk.trading.closeLong({
  mintAccount: mint,
  sellTokenAmount: new anchor.BN('10000000'),
  minSolOutput: new anchor.BN('18000000000'),
  closeOrderId: orderId,
  closeOrderIndices: [...],
  payer: wallet.publicKey,
  userSolAccount: orderOwner
});

Data Queries

// Get token list
const tokens = await sdk.fast.mints({ limit: 10 });

// Get token price
const price = await sdk.data.price(mint);

// Get orders
const orders = await sdk.data.orders(mint, { type: 'down_orders' });

// Get user orders
const userOrders = await sdk.data.user_orders(userAddress, mint);

Trade Simulation

// Simulate buy before execution
const simulation = await sdk.simulator.simulateTokenBuy(mint, buyTokenAmount);

console.log('Completion:', simulation.completion + '%');
console.log('Slippage:', simulation.slippage + '%');
console.log('Suggested SOL:', simulation.suggestedSolAmount);

// Use simulation results in actual trade
const result = await sdk.trading.buy({
  mintAccount: mint,
  buyTokenAmount: new anchor.BN(buyTokenAmount),
  maxSolAmount: new anchor.BN(simulation.suggestedSolAmount),
  payer: wallet.publicKey
});

Development

Build

npm run build          # Build all distribution formats (CJS, ESM, UMD)
npm run build:dev      # Watch mode for development

Testing

# Run individual test files
node tests/example-trading-buy.js
node tests/test-closeShort.js

# Standard test commands (coming soon)
npm test

Linting

npm run lint

Important Notes

1. Data Source Selection

   • fast (API) - Fast responses, may have slight delays during peak times
   • chain (Direct) - More reliable, slower, no third-party dependencies

2. Transaction Signing

   • SDK returns unsigned transactions
   • Signing must be done externally for security
   • Compatible with hardware wallets and browser extensions

3. Error Handling

   • All async methods can throw exceptions
   • Always implement proper error handling
   • Use try-catch blocks around SDK calls

4. Precision

   • Always use anchor.BN for amounts
   • Remember decimal places: SOL (9), Token (6)
   • Use CurveAMM utilities for price conversions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Documentation: ./doc/README.md
• Issues: GitHub Issues
• Discord: Join our community

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Links

• SpinPet Protocol
• Solana Documentation
• Anchor Framework

Version: 2.0.0 Last Updated: 2024-12-09