{"_id":"@elisedd/solana-sdk","_rev":"19-ce3b272fda2efac3a0afd7a1a29df9ab","name":"@elisedd/solana-sdk","dist-tags":{"latest":"1.0.11"},"versions":{"1.0.10":{"name":"@elisedd/solana-sdk","version":"1.0.10","keywords":["solana","wallet","swap","portfolio"],"author":{"name":"Elisedd"},"license":"MIT","_id":"@elisedd/solana-sdk@1.0.10","maintainers":[{"name":"elisedd","email":"ernst1789@gmail.com"}],"dist":{"shasum":"295ae3550035384a3be16c7395d54738640b5453","tarball":"https://registry.npmjs.org/@elisedd/solana-sdk/-/solana-sdk-1.0.10.tgz","fileCount":18,"integrity":"sha512-nujXr4+LCMvf2mjolewJuCh4Cwax6MurGU15TjopRGZmoy3LK6a4S2PO9xwF6aeBX0sYsBB8qSoZtCowErWLZw==","signatures":[{"sig":"MEYCIQDofvqxdU/+C7AaZb/UV9XvlA4xStJVlxnWXO2sw+Ta2wIhAJkZ9ESQ0tsMrdfLa7Vsf3RWNKb3A0cgLHAT+BeOTzy9","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2625263},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"node build.js","build:js":"esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js","build:types":"tsc --emitDeclarationOnly --outDir dist","prepublishOnly":"npm run build"},"_npmUser":{"name":"elisedd","email":"ernst1789@gmail.com"},"_npmVersion":"11.1.0","description":"Light unofficial Solana SDK for wallets, balances, and swaps.","directories":{},"sideEffects":false,"_nodeVersion":"22.12.0","dependencies":{"bs58":"^5.0.0","@solana/web3.js":"^1.95.0","@solana/spl-token":"^0.4.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"esbuild":"^0.21.4","typescript":"^5.4.0"},"_npmOperationalInternal":{"tmp":"tmp/solana-sdk_1.0.10_1760870002111_0.9942837381686505","host":"s3://npm-registry-packages-npm-production"}},"1.0.11":{"name":"@elisedd/solana-sdk","version":"1.0.11","description":"Light unofficial Solana SDK for wallets, balances, and swaps.","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"node build.js","build:types":"tsc --emitDeclarationOnly --outDir dist","build:js":"esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js","prepublishOnly":"npm run build"},"keywords":["solana","wallet","swap","portfolio"],"author":{"name":"Elisedd"},"license":"MIT","dependencies":{"@solana/spl-token":"^0.4.0","@solana/web3.js":"^1.95.0","bs58":"^5.0.0"},"devDependencies":{"esbuild":"^0.21.4","typescript":"^5.4.0"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"sideEffects":false,"_id":"@elisedd/solana-sdk@1.0.11","_nodeVersion":"22.12.0","_npmVersion":"11.1.0","dist":{"integrity":"sha512-7xRuCtJeF+F0wN9n5KOylhuHUzAIXd/6SfMrNiWQRKSuzB8fo3K56WjseDCjjqxTDfRUAnGhOjdjMbr1p7zxCA==","shasum":"28cad6cd962ab883547f0754326cd5600024287b","tarball":"https://registry.npmjs.org/@elisedd/solana-sdk/-/solana-sdk-1.0.11.tgz","fileCount":18,"unpackedSize":2625991,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDFNH3IzHi12lk+XlfqixRr/ikdRm04z+EdAgYIeiElcQIhAM60pMKz0rDz9wpTvCDoHEvDMVoMTVtNXxf4UMZUPSWR"}]},"_npmUser":{"name":"elisedd","email":"ernst1789@gmail.com"},"directories":{},"maintainers":[{"name":"elisedd","email":"ernst1789@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/solana-sdk_1.0.11_1761068381448_0.5828097191722825"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-19T10:33:22.000Z","modified":"2025-10-21T17:39:41.892Z","1.0.0":"2025-10-18T19:21:02.794Z","1.0.1":"2025-10-18T19:49:14.748Z","1.0.2":"2025-10-18T20:01:25.346Z","1.0.3":"2025-10-18T20:04:03.581Z","1.0.4":"2025-10-18T20:12:37.488Z","1.0.5":"2025-10-18T20:22:40.093Z","1.0.6":"2025-10-19T08:39:41.365Z","1.0.7":"2025-10-19T09:40:33.265Z","1.0.8":"2025-10-19T09:55:47.294Z","1.0.9":"2025-10-19T10:01:46.340Z","1.0.10":"2025-10-19T10:33:22.370Z","1.0.11":"2025-10-21T17:39:41.706Z"},"author":{"name":"Elisedd"},"license":"MIT","keywords":["solana","wallet","swap","portfolio"],"description":"Light unofficial Solana SDK for wallets, balances, and swaps.","maintainers":[{"name":"elisedd","email":"ernst1789@gmail.com"}],"readme":"# @elisedd/solana-sdk\n\nA lightweight TypeScript toolkit for common Solana tasks:\n\n- **Balance and portfolio**: SOL and SPL token balances by address.\n- **Wallet management**: Multiple local wallets in `wallet.json`.\n- **Transfers**: Send SOL from a wallet.\n- **Swaps**: Buy/sell tokens via Pump.fun or Jupiter.\n\nExports:\n\n- getBalanceByAddress()\n- getPortfolioByAddress()\n- buyToken(), sellToken()\n- walletManager()\n\n## Installation\n\n- Node.js 18+ (required for global `fetch`)\n- Install from npm:\n\n```bash\nnpm install @elisedd/solana-sdk\n```\n\n## Quick Start\n\n```ts\nimport {\n  getBalanceByAddress,\n  getPortfolioByAddress,\n  buyToken,\n  sellToken,\n  walletManager,\n} from \"@elisedd/solana-sdk\";\n\nconst sol = await getBalanceByAddress(\"YourPublicKeyHere\");\nconsole.log(sol);\n\nconst portfolio = await getPortfolioByAddress(\n  \"YourPublicKeyHere\",\n  \"https://api.mainnet-beta.solana.com\",\n  \"confirmed\",\n  {\n    includeZeroBalances: false,\n    tryTokenList: true,\n  }\n);\nconsole.log(portfolio);\n\nconst wm = walletManager();\nconst { name, keypair } = wm.addNew(\"trader\");\nconsole.log(name, keypair.publicKey.toBase58());\n\nconst txBuy = await buyToken(\n  \"https://api.mainnet-beta.solana.com\",\n  \"BASE58_PRIVATE_KEY\",\n  \"MintAddress\",\n  0.05,\n  0.05\n);\nconsole.log(\"Buy sig\", txBuy);\n\nconst txSell = await sellToken(\n  \"https://api.mainnet-beta.solana.com\",\n  \"BASE58_PRIVATE_KEY\",\n  \"MintAddress\",\n  10,\n  0.05\n);\nconsole.log(\"Sell sig\", txSell);\n```\n\nCommonJS:\n\n```js\nconst {\n  getBalanceByAddress,\n  getPortfolioByAddress,\n  buyToken,\n  sellToken,\n  walletManager,\n} = require(\"@elisedd/solana-sdk\");\n\n(async () => {\n  const sol = await getBalanceByAddress(\"YourPublicKeyHere\");\n  console.log(sol);\n})();\n```\n\n## Runtime and Network\n\n- Default RPC: `https://api.mainnet-beta.solana.com`\n- Commitment defaults to `\"confirmed\"` where applicable.\n- For best reliability use your own RPC endpoint.\n\n---\n\n# API Reference\n\n## Balance\n\n- **getBalanceByAddress(address, rpc?, commitment?) => Promise<number>**\n  - Returns SOL balance in SOL units.\n  - Parameters:\n    - `address: string` base58 wallet address.\n    - `rpc?: string` default mainnet RPC.\n    - `commitment?: Commitment` defaults to `\"confirmed\"`.\n  - Throws on invalid address or RPC error.\n\nExample:\n\n```ts\nimport { getBalanceByAddress } from \"@elisedd/solana-sdk\";\n\nconst balance = await getBalanceByAddress(\"8F...abc\");\nconsole.log(`Balance: ${balance} SOL`);\n```\n\n## Portfolio\n\n- Types:\n\n  - `TokenPosition`\n    - `tokenAccount: string`\n    - `mint: string`\n    - `amount: string`\n    - `uiAmount: number | null`\n    - `decimals: number | null`\n    - `isNFT: boolean` (heuristic: decimals === 0 and uiAmount === 1)\n    - `name?: string`\n    - `symbol?: string`\n  - `Portfolio`\n    - `address: string`\n    - `sol: number`\n    - `tokens: TokenPosition[]`\n    - `message?: string`\n\n- **getPortfolioByAddress(address, rpc?, commitment?, opts?) => Promise<Portfolio>**\n  - Fetches SOL balance and all SPL token accounts (parsed).\n  - Parameters:\n    - `address: string`\n    - `rpc?: string` default mainnet RPC.\n    - `commitment?: Commitment` default `\"confirmed\"`.\n    - `opts?: { includeZeroBalances?: boolean; tryTokenList?: boolean }`\n      - `includeZeroBalances` default `false` to omit zero uiAmount tokens.\n      - `tryTokenList` default `true`, attempts to enrich with name/symbol via `@solana/spl-token-registry`.\n        - Loaded dynamically; if unavailable or fails, names will be omitted.\n\nExample:\n\n```ts\nimport { getPortfolioByAddress } from \"@elisedd/solana-sdk\";\n\nconst portfolio = await getPortfolioByAddress(\n  \"8F...abc\",\n  undefined,\n  \"confirmed\",\n  {\n    includeZeroBalances: false,\n    tryTokenList: true,\n  }\n);\n\nconsole.log(\"SOL\", portfolio.sol);\nfor (const t of portfolio.tokens) {\n  console.log(t.mint, t.uiAmount, t.symbol ?? \"\");\n}\n```\n\nNotes:\n\n- Malformed token accounts are skipped, not fatal.\n- The token list uses chainId 101 (mainnet). On devnet, disable `tryTokenList`.\n\n## Wallets\n\n- Local multi-wallet management stored in `wallet.json` at the current working directory.\n- Format:\n\n```json\n{\n  \"wallet 1\": {\n    \"publicKey\": \"Base58Pubkey\",\n    \"privateKey\": \"Base58SecretKey\"\n  },\n  \"trader\": {\n    \"publicKey\": \"Base58Pubkey\",\n    \"privateKey\": \"Base58SecretKey\"\n  }\n}\n```\n\n- Migration is automatic from several older formats:\n\n  - `{ wallet: { publicKey, privateKey } }` with privateKey either base58 or number array.\n  - `{ secretKey: number[] }`.\n\n- **walletManager()**\n  - Methods:\n    - readFile(): MultiWalletsFile\n    - writeFile(data: MultiWalletsFile): void\n    - getAll(): Map<string, Keypair>\n    - get(name: string): Keypair | undefined\n    - addNew(name?: string): { name: string; keypair: Keypair }\n      - Creates a new random Keypair and persists it. Returns final unique name.\n    - addFromSecret(secret: string | Uint8Array | number[], name?: string): string\n      - Imports an existing secret. Secret can be base58 string, `Uint8Array`, or legacy number array. Returns final unique name.\n    - remove(name: string): boolean\n    - save(mapLike: Map<string, Keypair> | MultiWalletsFile): void\n    - printInfo(connection?: Connection): Promise<void>\n      - Without `connection`, prints wallet names and addresses.\n      - With a `Connection`, prints each balance and total.\n\nExamples:\n\n```ts\nimport { walletManager } from \"@elisedd/solana-sdk\";\nimport { Connection } from \"@solana/web3.js\";\n\nconst wm = walletManager();\n\nconst { name, keypair } = wm.addNew(\"trader\");\nconsole.log(name, keypair.publicKey.toBase58());\n\nconst importedName = wm.addFromSecret(\"BASE58_SECRET\", \"cold\");\nconsole.log(importedName);\n\nfor (const [n, kp] of wm.getAll()) {\n  console.log(n, kp.publicKey.toBase58());\n}\n\nconst conn = new Connection(\"https://api.mainnet-beta.solana.com\", \"confirmed\");\nawait wm.printInfo(conn);\n\nwm.remove(\"trader\");\n```\n\nSecurity:\n\n- `wallet.json` is written with mode `0o600` where supported. Keep it private.\n- Do not commit `wallet.json` to version control.\n\n## Send SOL\n\nUse the exported functions in your app. There is no CLI in the package. For example, to transfer SOL you can build a small script using `@solana/web3.js` and a `Keypair` from `walletManager()`.\n\n## Swap\n\nExports:\n\n- **buyToken(rpc, secret, mint, solAmount, maxSlippage?) => Promise<string>**\n\n  - Buys `mint` using SOL. Returns transaction signature.\n  - Parameters:\n    - `rpc: string`\n    - `secret: string` base58 private key\n    - `mint: string` token mint address\n    - `solAmount: number` amount of SOL to spend\n    - `maxSlippage?: number` default `0.05` (5%)\n  - Flow:\n    - If token is on Pump.fun, executes a Pump.fun buy.\n    - Otherwise, falls back to Jupiter swap (SOL -> token).\n\n- **sellToken(rpc, secret, mint, tokenAmount, maxSlippage?) => Promise<string>**\n  - Sells `tokenAmount` of `mint` into SOL. Returns transaction signature.\n  - Parameters:\n    - `rpc: string`\n    - `secret: string` base58 private key\n    - `mint: string`\n    - `tokenAmount: number` amount in UI units\n    - `maxSlippage?: number` default `0.05`\n  - Flow:\n    - Tries Pump.fun sell first.\n    - If it fails (not a Pump.fun token or on-chain mismatch), falls back to Jupiter swap (token -> SOL).\n\nUnder the hood:\n\n- Pump.fun integration:\n  - Checks bonding curve account discriminator.\n  - Creates ATA if needed.\n  - Adds compute budget instructions.\n  - Sends legacy transaction with `sendAndConfirmTransaction`.\n- Jupiter integration:\n  - Uses `/quote` to find a route.\n  - Uses `/swap` to get a serialized v0 transaction.\n  - Signs as a `VersionedTransaction` when possible, otherwise legacy.\n  - Sends raw transaction, confirms at `\"confirmed\"`.\n\nExamples:\n\n```ts\nimport { buyToken, sellToken } from \"@elisedd/solana-sdk\";\n\nconst rpc = \"https://api.mainnet-beta.solana.com\";\nconst secret = \"BASE58_PRIVATE_KEY\";\nconst mint = \"TokenMintAddress\";\nconst buySig = await buyToken(rpc, secret, mint, 0.02, 0.03);\nconsole.log(\"Buy sig:\", buySig);\n\nconst sellSig = await sellToken(rpc, secret, mint, 100, 0.03);\nconsole.log(\"Sell sig:\", sellSig);\n```\n\nNotes:\n\n- Node 18+ recommended for global `fetch`.\n- Jupiter endpoints: `https://lite-api.jup.ag` are used. If they rate limit or change, adjust accordingly.\n- `tokenAmount` conversion for Pump.fun assumes 6 decimals in this implementation. Verify mint decimals if you need exact raw amounts.\n- For Pump.fun buy, the program uses a fee recipient `FEE_RECIPIENT`. Ensure you understand fees and risks.\n\n---\n\n---\n\n---\n\n# Error Handling\n\n- Functions throw `Error` with helpful messages on RPC failures or invalid inputs.\n- Wrap calls in try/catch in production code.\n- Network hiccups are common on public RPCs; prefer a stable provider.\n\nExample:\n\n```ts\ntry {\n  const sol = await getBalanceByAddress(\"8F...abc\");\n  console.log(sol);\n} catch (e) {\n  console.error(\"Could not fetch balance:\", (e as Error).message);\n}\n```\n\n---\n\n# Security\n\n- Never commit `wallet.json` or private keys.\n- Use environment variables or secure secret managers for keys.\n- Consider hardware wallets or custodial solutions for significant funds.\n- Always verify mint addresses and slippage settings.\n\n---\n\n# Testing on Devnet\n\n- Many features are oriented to mainnet (`token-registry` chainId 101).\n- For devnet:\n  - Use a devnet RPC.\n  - Disable `tryTokenList`.\n  - Fund wallets with airdrops where applicable.\n\nExample:\n\n```ts\nimport { getPortfolioByAddress } from \"@elisedd/solana-sdk\";\n\nconst devnetRPC = \"https://api.devnet.solana.com\";\nconst portfolio = await getPortfolioByAddress(\n  \"DevnetPubkey\",\n  devnetRPC,\n  \"confirmed\",\n  {\n    includeZeroBalances: true,\n    tryTokenList: false,\n  }\n);\nconsole.log(portfolio);\n```\n\n## Connect\n\n[![GitHub](https://img.shields.io/badge/GitHub-selimann-181717?logo=github&logoColor=white)](https://github.com/selimann)\n[![@elisedd14](https://img.shields.io/badge/%40elisedd14-black?logo=x&logoColor=white)](https://x.com/elisedd14)\n\n---\n\n## Support the Project\n\nIf you like this SDK and want to support further development:\n\n[![Solana Donate](https://img.shields.io/badge/Solana-Donate-9945FF?logo=solana&logoColor=white)](https://explorer.solana.com/address/So1aNa111YourWalletAddress111111111111111111111)\n\n**Solana Address:**  \n`EnG5LZ3SAuYSz9CRXMAePQPXnqS3fFUR45GNyVLsZh5W`\n","readmeFilename":"README.md"}