{"_id":"@byreal-io/byreal-sdk","name":"@byreal-io/byreal-sdk","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.1":{"name":"@byreal-io/byreal-sdk","version":"0.2.1","description":"Full-featured Byreal DEX SDK for Solana - API client, CLMM position management, swap, and more","type":"module","main":"./dist/esm/index.js","types":"./dist/esm/index.d.ts","exports":{".":{"types":"./dist/esm/index.d.ts","import":"./dist/esm/index.js"},"./api":{"types":"./dist/esm/api/index.d.ts","import":"./dist/esm/api/index.js"},"./types":{"types":"./dist/esm/types/index.d.ts","import":"./dist/esm/types/index.js"},"./package.json":"./package.json"},"scripts":{"build":"tsc","dev":"tsc --watch","typecheck":"tsc --noEmit","format":"prettier --write \"src/**/*.ts\" \"examples/**/*.ts\"","prepublishOnly":"npm run build","postversion":"git push && git push --tags"},"dependencies":{"@byreal-io/byreal-clmm-sdk":"^0.2.2","@solana/spl-token":"^0.4.14","@solana/web3.js":"^1.98.4","bn.js":"^5.2.3","decimal.js":"^10.5.0"},"devDependencies":{"@types/bn.js":"^5.2.0","bs58":"^6.0.0","dotenv":"^17.3.1","prettier":"^3.8.1","tsx":"^4.21.0","typescript":"^5.7.3"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/byreal-io/byreal-sdk.git"},"keywords":["byreal","solana","dex","clmm","sdk","defi"],"_id":"@byreal-io/byreal-sdk@0.2.1","gitHead":"a9ad70c044233f6c55a069f081e1f3af45a4a239","bugs":{"url":"https://github.com/byreal-io/byreal-sdk/issues"},"homepage":"https://github.com/byreal-io/byreal-sdk#readme","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-KhQoM8ORJKu5zSBviiWI7h3tQdH25MnWdUgpVQw6MwsuA/EZEWWddPrHTLwRxnJ6Nf6Ttkftq2SM63JV7uw8nA==","shasum":"c8628966a50bb424c6e9f8d40b6a44f949331de4","tarball":"https://registry.npmjs.org/@byreal-io/byreal-sdk/-/byreal-sdk-0.2.1.tgz","fileCount":198,"unpackedSize":257381,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDW3+z1RGJmCSDMCW0YZgpDD1dXQ8RmOjQcfsjSQ+QVuwIgIitbuwwdnpI5qBkOe05uHeXsMZr28hLKos4xm4Y6cb4="}]},"_npmUser":{"name":"wangyulue","email":"wangyulue@gmail.com"},"directories":{},"maintainers":[{"name":"joe1.hw","email":"joe.he1@bybit.com"},{"name":"wangyulue","email":"wangyulue@gmail.com"},{"name":"byreal-admin","email":"app@byreal.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/byreal-sdk_0.2.1_1773736592483_0.31311967040754984"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-17T08:36:32.337Z","0.2.1":"2026-03-17T08:36:32.648Z","modified":"2026-03-17T08:36:33.011Z"},"maintainers":[{"name":"joe1.hw","email":"joe.he1@bybit.com"},{"name":"wangyulue","email":"wangyulue@gmail.com"},{"name":"byreal-admin","email":"app@byreal.io"}],"description":"Full-featured Byreal DEX SDK for Solana - API client, CLMM position management, swap, and more","homepage":"https://github.com/byreal-io/byreal-sdk#readme","keywords":["byreal","solana","dex","clmm","sdk","defi"],"repository":{"type":"git","url":"git+https://github.com/byreal-io/byreal-sdk.git"},"bugs":{"url":"https://github.com/byreal-io/byreal-sdk/issues"},"license":"MIT","readme":"# Byreal SDK\n\nFull-featured Byreal DEX SDK for Solana — API client, CLMM position management, swap, and more.\n\n## Installation\n\n```bash\nnpm install @byreal-io/byreal-sdk\n```\n\n## Quick Start\n\n### Initialize SDK\n\n```typescript\nimport { Connection } from \"@solana/web3.js\";\nimport { ByrealSDK } from \"@byreal-io/byreal-sdk\";\n\nconst connection = new Connection(\"https://api.mainnet-beta.solana.com\");\n\nconst sdk = new ByrealSDK({ connection });\n```\n\n## Core Features\n\n### 1. Query Pools\n\nList, search, and get pool details.\n\n```typescript\n// List pools sorted by TVL\nconst poolsResult = await sdk.pools.list({\n  pageSize: 10,\n  sortField: \"tvl\",\n  sortType: \"desc\",\n});\n\nif (poolsResult.ok) {\n  for (const pool of poolsResult.value.items) {\n    console.log(`${pool.pair} | TVL: $${pool.tvl_usd} | APR: ${pool.apr}%`);\n  }\n}\n\n// Get pool details\nconst detailResult = await sdk.pools.getDetail(\"pool-address\");\n\n// Get K-line data\nconst klines = await sdk.pools.getKlines({\n  poolAddress: \"pool-address\",\n  tokenAddress: \"token-mint\",\n  klineType: \"1h\",\n});\n```\n\n### 2. Query Tokens\n\n```typescript\n// List tokens\nconst tokensResult = await sdk.tokens.list({\n  searchKey: \"SOL\",\n  pageSize: 10,\n});\n\n// Batch fetch prices\nconst prices = await sdk.tokens.getPrices([\n  \"So11111111111111111111111111111111111111112\",\n  \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n]);\n```\n\n### 3. Global Overview\n\n```typescript\nconst overview = await sdk.overview.getGlobal();\n\nif (overview.ok) {\n  console.log(`TVL: $${overview.value.tvl}`);\n  console.log(`24h Volume: $${overview.value.volume_24h_usd}`);\n  console.log(`24h Fees: $${overview.value.fee_24h_usd}`);\n  console.log(`Pools: ${overview.value.pools_count}`);\n}\n```\n\n### 4. Swap Tokens\n\nGet quotes and execute swaps through the Byreal router (AMM + RFQ auto-routing).\n\n```typescript\n// Preview swap (quote only)\nconst quote = await sdk.swap.getQuote({\n  inputMint: \"So11111111111111111111111111111111111111112\",\n  outputMint: \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n  amount: \"1000000000\", // 1 SOL in lamports\n  swapMode: \"in\",\n  slippageBps: 200,\n  userPublicKey: wallet.publicKey.toBase58(),\n});\n\n// Execute swap with signing\nconst swapResult = await sdk.swap.executeSwap({\n  inputMint: \"So11111111111111111111111111111111111111112\",\n  outputMint: \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n  amount: \"1000000000\",\n  swapMode: \"in\",\n  userPublicKey: wallet.publicKey.toBase58(),\n  signerCallback: async (tx) => {\n    tx.sign([wallet]);\n    return tx;\n  },\n});\n\nif (swapResult.ok) {\n  console.log(\"Swap signatures:\", swapResult.value.signatures);\n  console.log(\"Confirmed:\", swapResult.value.confirmed);\n}\n```\n\n### 5. Manage Positions\n\nOpen, close, and claim fees for CLMM liquidity positions.\n\n#### Open Position\n\n```typescript\n// Open position with USD amount (auto token split)\nconst openResult = await sdk.positions.openPosition({\n  poolAddress: \"pool-address\",\n  priceLower: \"0.998\",\n  priceUpper: \"1.002\",\n  amountUsd: 1000, // $1000 investment\n  userAddress: wallet.publicKey.toBase58(),\n  signerCallback: async (tx) => {\n    tx.sign([wallet]);\n    return tx;\n  },\n});\n\n// Or with explicit token amount\nconst openResult2 = await sdk.positions.openPosition({\n  poolAddress: \"pool-address\",\n  priceLower: \"0.998\",\n  priceUpper: \"1.002\",\n  base: \"MintA\",\n  amount: \"100\", // 100 TokenA (UI amount)\n  userAddress: wallet.publicKey.toBase58(),\n  signerCallback: async (tx) => {\n    tx.sign([wallet]);\n    return tx;\n  },\n});\n```\n\n#### Close Position\n\n```typescript\nconst closeResult = await sdk.positions.closePosition({\n  nftMint: \"position-nft-mint-address\",\n  userAddress: wallet.publicKey.toBase58(),\n  signerCallback: async (tx) => {\n    tx.sign([wallet]);\n    return tx;\n  },\n});\n```\n\n#### Claim Fees\n\n```typescript\nconst claimResult = await sdk.positions.claimFees({\n  nftMints: [\"nft-mint-1\", \"nft-mint-2\"],\n  userAddress: wallet.publicKey.toBase58(),\n  signerCallback: async (tx) => {\n    tx.sign([wallet]);\n    return tx;\n  },\n});\n```\n\n#### List & Query Positions\n\n```typescript\n// List positions\nconst positions = await sdk.positions.list({\n  userAddress: wallet.publicKey.toBase58(),\n  status: 0, // 0 = active\n});\n\n// Get unclaimed fees\nconst unclaimed = await sdk.positions.getUnclaimed(wallet.publicKey.toBase58());\n```\n\n### 6. Copy Farming\n\nDiscover top-performing positions and copy their strategies.\n\n```typescript\n// Get top positions for a pool\nconst topPositions = await sdk.copyFarmer.getTopPositions({\n  poolAddress: \"pool-address\",\n  sortField: \"liquidity\",\n  sortType: \"desc\",\n  pageSize: 10,\n});\n\n// Copy a position\nconst copyResult = await sdk.copyFarmer.copyPosition({\n  sourcePositionAddress: \"position-address\",\n  amountUsd: 500,\n  userAddress: wallet.publicKey.toBase58(),\n  signerCallback: async (tx) => {\n    tx.sign([wallet]);\n    return tx;\n  },\n});\n```\n\n### 7. Priority Fees\n\n```typescript\nconst feeResult = await sdk.fees.getAutoFee();\nif (feeResult.ok) {\n  console.log(\"High:\", feeResult.value.high);\n  console.log(\"Medium:\", feeResult.value.medium);\n  console.log(\"Extreme:\", feeResult.value.extreme);\n}\n```\n\n## Architecture\n\nThe SDK has a three-layer architecture:\n\n```\n┌──────────────────────────────────────────────┐\n│  ByrealSDK (Facade)                          │\n│  sdk.pools / sdk.tokens / sdk.swap / ...     │\n├──────────────────────────────────────────────┤\n│  Services Layer (Business Logic)             │\n│  Composes API + CLMM SDK operations          │\n├──────────────────────────────────────────────┤\n│  API Client Layer (HTTP Endpoints)           │\n│  1:1 mapping to all backend endpoints        │\n├──────────────────────────────────────────────┤\n│  Types + Errors + Utils                      │\n└──────────────────────────────────────────────┘\n```\n\n- **API Layer**: Covers 40+ backend endpoints using native `fetch` (zero HTTP dependencies)\n- **Services Layer**: 7 business services composing API calls + on-chain CLMM SDK operations\n- **CLMM SDK**: Imported via npm (`@byreal-io/byreal-clmm-sdk`) for on-chain position management\n\n## Low-level API Access\n\nFor advanced use cases, you can access the API client directly:\n\n```typescript\nimport { ApiClient, API_ENDPOINTS } from \"@byreal-io/byreal-sdk/api\";\n\nconst client = new ApiClient({ baseUrl: \"https://api2.byreal.io\" });\n\n// Call any endpoint directly\nconst result = await client.get(API_ENDPOINTS.POOLS_LIST, {\n  page: 1,\n  pageSize: 10,\n  sortField: \"tvl\",\n});\n```\n\n## Utility Functions\n\n```typescript\nimport {\n  uiToRaw,\n  rawToUi,\n  calculateTickAlignedPriceRange,\n  calculateTokenAmountsFromUsd,\n} from \"@byreal-io/byreal-sdk\";\n\n// Amount conversion\nuiToRaw(\"1.5\", 9); // '1500000000'\nrawToUi(\"1500000000\", 9); // '1.5'\n\n// Tick-aligned price range\nconst { priceInTickLower, priceInTickUpper } = calculateTickAlignedPriceRange({\n  tickSpacing: 1,\n  mintDecimalsA: 9,\n  mintDecimalsB: 6,\n  startPrice: \"0.998\",\n  endPrice: \"1.002\",\n});\n```\n\n## Integration with Solana Agent Kit\n\nThe SDK is designed for easy integration with `solana-agent-kit`:\n\n```typescript\nimport { ByrealSDK } from \"@byreal-io/byreal-sdk\";\n\n// In your agent-kit plugin tool:\nasync function byrealSwap(agent, input) {\n  const sdk = new ByrealSDK({ connection: agent.connection });\n\n  const result = await sdk.swap.executeSwap({\n    ...input,\n    userPublicKey: agent.wallet.publicKey.toBase58(),\n    signerCallback: (tx) => agent.wallet.signTransaction(tx),\n  });\n\n  return result;\n}\n```\n\n## Examples\n\nMore examples are available in the [examples](./examples) directory:\n\n- Query: `01_list_pools.ts`, `02_get_pool_detail.ts`, `03_list_tokens.ts`, `04_global_overview.ts`\n- Swap: `05_swap_quote.ts`, `06_swap_execute.ts`\n- Positions: `07_list_positions.ts`, `08_open_position.ts`, `09_close_position.ts`, `10_claim_fees.ts`\n- Copy Farming: `11_top_positions.ts`, `12_copy_position.ts`\n- Utility: `13_priority_fees.ts`, `14_tick_aligned_price.ts`, `15_token_prices.ts`, `16_kline_data.ts`\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Type check\nnpm run typecheck\n\n# Run examples\nnpx tsx examples/01_list_pools.ts\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-60dcfc2ac3c10c9aae36ef6358932e17"}