{"id":19864390,"url":"https://github.com/balmy-protocol/sdk","last_synced_at":"2025-05-02T05:31:09.176Z","repository":{"id":149509817,"uuid":"587440464","full_name":"Balmy-protocol/sdk","owner":"Balmy-protocol","description":"An SDK for all things Balmy (and more)","archived":false,"fork":false,"pushed_at":"2025-04-22T20:59:31.000Z","size":2603,"stargazers_count":19,"open_issues_count":12,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-22T21:46:52.552Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://balmy.xyz","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Balmy-protocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-10T18:57:26.000Z","updated_at":"2025-04-18T15:49:06.000Z","dependencies_parsed_at":"2023-10-26T18:27:56.341Z","dependency_job_id":"84f10cf4-7178-477e-9432-fdd99a154e41","html_url":"https://github.com/Balmy-protocol/sdk","commit_stats":null,"previous_names":["balmy-protocol/sdk"],"tags_count":290,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fsdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fsdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fsdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fsdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Balmy-protocol","download_url":"https://codeload.github.com/Balmy-protocol/sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251992747,"owners_count":21677020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T15:18:31.493Z","updated_at":"2025-05-02T05:31:09.170Z","avatar_url":"https://github.com/Balmy-protocol.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Balmy SDK\n\nA comprehensive TypeScript SDK for interacting with the Balmy protocol and various blockchain networks.\n\n## 🧪 Installation\n\n### Yarn\n\n```bash\nyarn add @balmy/sdk\n```\n\n### NPM\n\n```bash\nnpm install @balmy/sdk\n```\n\n## Quick Start\n\n### 👷🏽‍♀️ Building the SDK\n\n```typescript\nimport { buildSDK } from \"@balmy/sdk\";\n\nconst sdk = buildSDK(config);\n```\n\n### ⚖️ Getting Balance for Multiple Tokens\n\n```typescript\nconst accountBalances = await sdk.balanceService.getBalancesForTokens({\n  account: \"0x000000000000000000000000000000000000dead\",\n  tokens: {\n    [Chains.ETHEREUM.chainId]: [\n      \"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\", // USDC\n      \"0x6b175474e89094c44da98b954eedeac495271d0f\", // DAI\n    ],\n    [Chains.OPTIMISM.chainId]: [\n      \"0x7f5c764cbc14f9669b88837ca1490cca17c31607\", // USDC\n      \"0xda10009cbd5d07dd0cecc66161fc93d7c9000da1\", // DAI\n    ],\n  },\n  config: {\n    timeout: \"30s\",\n  },\n});\n```\n\n### 💸 Getting Allowances\n\n```typescript\nconst accountAllowances = await sdk.allowanceService.getAllowances({\n  chainId: Chains.ETHEREUM.chainId,\n  token: \"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\", // USDC\n  owner: \"0x000000000000000000000000000000000000dead\",\n  spenders: [\"0x6666666600000000000000000000000000009999\"],\n});\n```\n\n### 🔄 Getting Trade Quotes\n\n```typescript\nconst allQuotes = await sdk.quoteService.getAllQuotesWithTxs({\n  request: {\n    chainId: Chains.ETHEREUM.chainId,\n    sellToken: \"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\n    buyToken: \"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\n    order: {\n      type: \"sell\",\n      sellAmount: utils.parseUnits(\"1000\", 6), // 1000 USDC\n    },\n    slippagePercentage: 1,\n    takerAddress: signer.address,\n    gasSpeed: {\n      speed: \"instant\",\n    },\n  },\n  config: {\n    sort: {\n      by: \"most-swapped-accounting-for-gas\",\n    },\n  },\n});\n```\n\n## Overview\n\nThe Balmy SDK is a comprehensive TypeScript library that provides a unified interface for interacting with the Balmy protocol and various blockchain networks. The Balmy SDK allows you to interact with the Balmy protocol, providing efficient tools to manage token balances, retrieve trade quotes from DEX aggregators, and check token holdings across multiple chains. It's designed to be modular, with each functionality organized into specialized services that handle specific aspects of blockchain interaction.\n\n### Available Services\n\nThe SDK is divided into the following services:\n\n- **[Allowances Service](#allowances-service)**: Manage token approvals and permissions across different chains\n- **[Balances Service](#balances-service)**: Query token balances across multiple chains and tokens\n- **[Quotes Service](#quotes-service)**: Get optimized swap quotes from various DEX aggregators\n- **[Gas Service](#gas-service)**: Optimize transaction costs and estimate gas prices\n- **[Prices Service](#prices-service)**: Retrieve token price information across multiple chains\n- **[Metadata Service](#metadata-service)**: Access token metadata and information\n- **[Permit2 Service](#permit2-service)**: Manage token approvals using the Permit2 protocol\n- **[DCA Service](#dca-service)**: Set up and manage Dollar Cost Averaging positions\n- **[Earn Service](#earn-service)**: Handle yield farming operations\n\nEach service provides a focused set of functionality while maintaining a consistent interface and error handling approach. This modular design allows developers to use only the services they need while ensuring a cohesive experience across the entire SDK.\n\n## Services\n\n### Allowances Service\n\nThe Allowances Service provides functionality to check and manage token allowances across different chains.\n\n#### Objective and Potential\n\n- **Objective**: Enable efficient management of token approvals across multiple chains and protocols\n- **Potential Use Cases**:\n  - Batch checking multiple token approvals in a single call\n  - Optimizing gas costs by checking approvals before transactions\n  - Managing permissions for DeFi protocols and dApps\n  - Cross-chain allowance monitoring and management\n\n#### Methods\n\n##### `supportedChains()`\n\nReturns an array of chain IDs that are supported by the service.\n\n```typescript\nconst chains = sdk.allowanceService.supportedChains();\n```\n\n##### `getAllowanceInChain(params)`\n\nGets the allowance for a specific token and spender on a given chain.\n\n```typescript\nconst allowance = await sdk.allowanceService.getAllowanceInChain({\n  chainId: Chains.ETHEREUM.chainId,\n  token: \"0x...\", // Token address\n  owner: \"0x...\", // Owner address\n  spender: \"0x...\", // Spender address\n  config: { timeout: TimeString },\n});\n```\n\n##### `getAllowancesInChain(params)`\n\nGets multiple allowances in a single call for a specific chain.\n\n```typescript\nconst allowances = await sdk.allowanceService.getAllowancesInChain({\n  chainId: Chains.ETHEREUM.chainId,\n  allowances: [\n    { token: \"0x...\", owner: \"0x...\", spender: \"0x...\" },\n    { token: \"0x...\", owner: \"0x...\", spender: \"0x...\" },\n  ],\n  config: { timeout: TimeString },\n});\n```\n\n##### `getAllowances(params)`\n\nGets allowances across multiple chains in a single call.\n\n```typescript\nconst allowances = await sdk.allowanceService.getAllowances({\n  allowances: [\n    {\n      chainId: Chains.ETHEREUM.chainId,\n      token: \"0x...\",\n      owner: \"0x...\",\n      spender: \"0x...\",\n    },\n    {\n      chainId: Chains.OPTIMISM.chainId,\n      token: \"0x...\",\n      owner: \"0x...\",\n      spender: \"0x...\",\n    },\n  ],\n  config: { timeout: TimeString },\n});\n```\n\n### Balances Service\n\nThe Balances Service allows querying token balances across multiple chains and tokens.\n\n#### Objective and Potential\n\n- **Objective**: Provide a unified interface for retrieving token balances across multiple chains\n- **Potential Use Cases**:\n  - Portfolio tracking across multiple chains\n  - Balance monitoring for DeFi positions\n  - Multi-chain wallet integration\n  - Automated balance checks for trading strategies\n\n#### Methods\n\n##### `supportedChains()`\n\nReturns an array of chain IDs that are supported by the service.\n\n```typescript\nconst chains = sdk.balanceService.supportedChains();\n```\n\n##### `getBalancesForAccountInChain(params)`\n\nGets balances for a specific account in a single chain.\n\n```typescript\nconst balances = await sdk.balanceService.getBalancesForAccountInChain({\n  chainId: Chains.ETHEREUM.chainId,\n  account: \"0x...\",\n  tokens: [\"0x...\", \"0x...\"],\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getBalancesForAccount(params)`\n\nGets balances for a specific account across multiple chains.\n\n```typescript\nconst balances = await sdk.balanceService.getBalancesForAccount({\n  account: \"0x...\",\n  tokens: [\n    { chainId: Chains.ETHEREUM.chainId, token: \"0x...\" },\n    { chainId: Chains.OPTIMISM.chainId, token: \"0x...\" },\n  ],\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getBalancesInChain(params)`\n\nGets balances for multiple accounts in a single chain.\n\n```typescript\nconst balances = await sdk.balanceService.getBalancesInChain({\n  chainId: Chains.ETHEREUM.chainId,\n  tokens: [\n    { account: \"0x...\", token: \"0x...\" },\n    { account: \"0x...\", token: \"0x...\" },\n  ],\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getBalances(params)`\n\nGets balances for multiple accounts across multiple chains.\n\n```typescript\nconst balances = await sdk.balanceService.getBalances({\n  tokens: [\n    { chainId: Chains.ETHEREUM.chainId, account: \"0x...\", token: \"0x...\" },\n    { chainId: Chains.OPTIMISM.chainId, account: \"0x...\", token: \"0x...\" },\n  ],\n  config: { timeout: \"30s\" },\n});\n```\n\n### Quotes Service\n\nThe Quotes Service provides comprehensive functionality for getting trade quotes from various DEX aggregators.\n\n#### Objective and Potential\n\n- **Objective**: Aggregate and optimize trade quotes from multiple DEX sources\n- **Potential Use Cases**:\n  - Finding the best trade routes across multiple DEXs\n  - Gas-optimized trading strategies\n  - Cross-chain arbitrage opportunities\n  - Automated trading systems\n  - Price impact analysis\n\n#### Methods\n\n##### `supportedSources()`\n\nReturns metadata about all supported quote sources.\n\n```typescript\nconst sources = sdk.quoteService.supportedSources();\n```\n\n##### `supportedChains()`\n\nReturns an array of chain IDs that are supported by the service.\n\n```typescript\nconst chains = sdk.quoteService.supportedChains();\n```\n\n##### `supportedSourcesInChain(params)`\n\nReturns metadata about quote sources supported in a specific chain.\n\n```typescript\nconst sources = sdk.quoteService.supportedSourcesInChain({\n  chainId: Chains.ETHEREUM.chainId,\n});\n```\n\n##### `supportedGasSpeeds()`\n\nReturns supported gas speeds for each chain.\n\n```typescript\nconst gasSpeeds = sdk.quoteService.supportedGasSpeeds();\n```\n\n##### `estimateQuotes(params)`\n\nGets estimated quotes from all sources without transaction details.\n\n```typescript\nconst quotes = sdk.quoteService.estimateQuotes({\n  request: {\n    chainId: Chains.ETHEREUM.chainId,\n    sellToken: \"0x...\",\n    buyToken: \"0x...\",\n    order: { type: \"sell\", sellAmount: BigInt(\"1000000\") },\n    slippagePercentage: 1,\n  },\n  config: { timeout: TimeString },\n});\n```\n\n##### `estimateAllQuotes(params)`\n\nGets estimated quotes from all sources and returns them in a sorted array.\n\n```typescript\nconst quotes = await sdk.quoteService.estimateAllQuotes({\n  request: {\n    chainId: Chains.ETHEREUM.chainId,\n    sellToken: \"0x...\",\n    buyToken: \"0x...\",\n    order: { type: \"sell\", sellAmount: BigInt(\"1000000\") },\n    slippagePercentage: 1,\n  },\n  config: {\n    ignoredFailed: boolean,\n    sort: { by: \"most-swapped-accounting-for-gas\", using: \"gas-price\" },\n    timeout: TimeString,\n  },\n});\n```\n\n##### `getQuotes(params)`\n\nGets quotes from all sources with transaction details.\n\n```typescript\nconst quotes = sdk.quoteService.getQuotes({\n  request: {\n    chainId: Chains.ETHEREUM.chainId,\n    sellToken: \"0x...\",\n    buyToken: \"0x...\",\n    order: { type: \"sell\", sellAmount: BigInt(\"1000000\") },\n    slippagePercentage: 1,\n    takerAddress: \"0x...\",\n  },\n  config: { timeout: TimeString },\n});\n```\n\n##### `getAllQuotes(params)`\n\nGets quotes from all sources and returns them in a sorted array.\n\n```typescript\nconst quotes = await sdk.quoteService.getAllQuotes({\n  request: {\n    chainId: Chains.ETHEREUM.chainId,\n    sellToken: \"0x...\",\n    buyToken: \"0x...\",\n    order: { type: \"sell\", sellAmount: BigInt(\"1000000\") },\n    slippagePercentage: 1,\n    takerAddress: \"0x...\",\n  },\n  config: {\n    ignoredFailed: boolean,\n    sort: { by: \"most-swapped-accounting-for-gas\", using: \"gas-price\" },\n    timeout: TimeString,\n  },\n});\n```\n\n##### `getBestQuote(params)`\n\nGets the best quote according to specified criteria.\n\n```typescript\nconst bestQuote = await sdk.quoteService.getBestQuote({\n  request: {\n    chainId: Chains.ETHEREUM.chainId,\n    sellToken: \"0x...\",\n    buyToken: \"0x...\",\n    order: { type: \"sell\", sellAmount: BigInt(\"1000000\") },\n    slippagePercentage: 1,\n    takerAddress: \"0x...\",\n  },\n  config: {\n    choose: { by: \"most-swapped-accounting-for-gas\", using: \"gas-price\" },\n    timeout: TimeString,\n  },\n});\n```\n\n##### `getAllQuotesWithTxs(params)`\n\nGets quotes with built transactions from all sources.\n\n```typescript\nconst quotesWithTxs = await sdk.quoteService.getAllQuotesWithTxs({\n  request: {\n    chainId: Chains.ETHEREUM.chainId,\n    sellToken: \"0x...\",\n    buyToken: \"0x...\",\n    order: { type: \"sell\", sellAmount: BigInt(\"1000000\") },\n    slippagePercentage: 1,\n    takerAddress: \"0x...\",\n  },\n  config: {\n    ignoredFailed: boolean,\n    sort: { by: \"most-swapped-accounting-for-gas\", using: \"gas-price\" },\n    timeout: TimeString,\n  },\n});\n```\n\n##### `buildTxs(params)`\n\nBuilds transactions for given quotes.\n\n```typescript\nconst txs = sdk.quoteService.buildTxs({\n  quotes: quotes,\n  sourceConfig: SourceConfig,\n  config: { timeout: TimeString },\n});\n```\n\n##### `buildAllTxs(params)`\n\nBuilds transactions for all quotes and returns them in a sorted array.\n\n```typescript\nconst allTxs = await sdk.quoteService.buildAllTxs({\n  quotes: quotes,\n  sourceConfig: SourceConfig,\n  config: {\n    timeout: TimeString,\n    ignoredFailed: boolean,\n  },\n});\n```\n\n### DCA Service\n\nThe DCA (Dollar Cost Averaging) Service provides functionality for setting up and managing DCA positions.\n\n#### Objective and Potential\n\n- **Objective**: Enable automated dollar-cost averaging strategies for any token pair\n- **Potential Use Cases**:\n  - Automated investment strategies\n  - Risk management through periodic investments\n  - Customizable DCA schedules\n  - Multi-chain DCA positions\n  - Permission management for shared positions\n\n#### Methods\n\n##### `getAllowanceTarget(params)`\n\nGets the allowance target address for a DCA position.\n\n```typescript\nconst target = sdk.dcaService.getAllowanceTarget({\n  chainId: Chains.ETHEREUM.chainId,\n  from: \"0x...\", // Token to sell\n  depositWith: \"0x...\", // Token to deposit with\n  usePermit2: boolean,\n});\n```\n\n##### `preparePermitData(params)`\n\nPrepares permit data for token approvals.\n\n```typescript\nconst permitData = await sdk.dcaService.preparePermitData({\n  // Permit2 parameters\n});\n```\n\n##### `buildCreatePositionTx(params)`\n\nBuilds a transaction to create a new DCA position.\n\n```typescript\nconst tx = await sdk.dcaService.buildCreatePositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  from: { address: \"0x...\", variantId: \"...\" },\n  to: { address: \"0x...\", variantId: \"...\" },\n  swapInterval: DCASwapInterval.ONE_DAY,\n  amountOfSwaps: 30,\n  owner: \"0x...\",\n  permissions: [{ operator: \"0x...\", permissions: [DCAPermission.INCREASE] }],\n  deposit: { token: \"0x...\", amount: BigInt(\"1000000\") },\n});\n```\n\n##### `buildIncreasePositionTx(params)`\n\nBuilds a transaction to increase an existing DCA position.\n\n```typescript\nconst tx = await sdk.dcaService.buildIncreasePositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"123\",\n  increase: { token: \"0x...\", amount: BigInt(\"1000000\") },\n  amountOfSwaps: 30,\n});\n```\n\n##### `buildReducePositionTx(params)`\n\nBuilds a transaction to reduce an existing DCA position.\n\n```typescript\nconst tx = await sdk.dcaService.buildReducePositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"123\",\n  amountOfSwaps: 15,\n  reduce: { amount: BigInt(\"500000\") },\n  recipient: \"0x...\",\n});\n```\n\n##### `buildReduceToBuyPositionTx(params)`\n\nBuilds a transaction to reduce a position to buy a specific amount.\n\n```typescript\nconst tx = await sdk.dcaService.buildReduceToBuyPositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"123\",\n  amountOfSwaps: 15,\n  reduce: { amountToBuy: BigInt(\"500000\") },\n  recipient: \"0x...\",\n});\n```\n\n##### `buildWithdrawPositionTx(params)`\n\nBuilds a transaction to withdraw from a DCA position.\n\n```typescript\nconst tx = await sdk.dcaService.buildWithdrawPositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"123\",\n  withdraw: {},\n  recipient: \"0x...\",\n});\n```\n\n##### `buildTerminatePositionTx(params)`\n\nBuilds a transaction to terminate a DCA position.\n\n```typescript\nconst tx = await sdk.dcaService.buildTerminatePositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"123\",\n  withdraw: {},\n  recipient: \"0x...\",\n});\n```\n\n##### `buildMigratePositionTx(params)`\n\nBuilds a transaction to migrate a DCA position to a new hub.\n\n```typescript\nconst tx = await sdk.dcaService.buildMigratePositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  sourceHub: \"0x...\",\n  targetHub: \"0x...\",\n  positionId: \"123\",\n  migration: { useFundsFrom: \"swapped\", sendUnusedFundsTo: \"0x...\" },\n});\n```\n\n##### `getSupportedPairs(params)`\n\nGets supported token pairs for DCA positions.\n\n```typescript\nconst pairs = await sdk.dcaService.getSupportedPairs({\n  chains: [Chains.ETHEREUM.chainId],\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getPositionsByAccount(params)`\n\nGets DCA positions for specific accounts.\n\n```typescript\nconst positions = await sdk.dcaService.getPositionsByAccount({\n  accounts: [\"0x...\"],\n  chains: [Chains.ETHEREUM.chainId],\n  includeHistory: true,\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getPositionsById(params)`\n\nGets DCA positions by their IDs.\n\n```typescript\nconst positions = await sdk.dcaService.getPositionsById({\n  ids: [{ chainId: Chains.ETHEREUM.chainId, hub: \"0x...\", positionId: 123 }],\n  includeHistory: true,\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getPairSwaps(params)`\n\nGets swap history for a token pair.\n\n```typescript\nconst swaps = await sdk.dcaService.getPairSwaps({\n  chainId: Chains.ETHEREUM.chainId,\n  variantTokenA: \"...\",\n  variantTokenB: \"...\",\n  config: { timeout: \"30s\" },\n});\n```\n\n### Gas Service\n\nThe Gas Service provides gas price estimation and optimization across different chains.\n\n#### Objective and Potential\n\n- **Objective**: Optimize transaction costs across different chains and networks\n- **Potential Use Cases**:\n  - Gas price monitoring and optimization\n  - Transaction cost estimation\n  - Gas-aware trading strategies\n  - Multi-chain gas price comparison\n  - Automated gas price optimization\n\n#### Methods\n\n##### `supportedChains()`\n\nReturns an array of chain IDs that are supported by the service.\n\n```typescript\nconst chains = sdk.gasService.supportedChains();\n```\n\n##### `supportedSpeeds()`\n\nReturns supported gas speeds for each chain.\n\n```typescript\nconst speeds = sdk.gasService.supportedSpeeds();\n```\n\n##### `estimateGas(params)`\n\nEstimates gas usage for a transaction.\n\n```typescript\nconst gasEstimation = await sdk.gasService.estimateGas({\n  chainId: Chains.ETHEREUM.chainId,\n  tx: {\n    from: \"0x...\",\n    to: \"0x...\",\n    data: \"0x...\",\n  },\n  config: { timeout: TimeString },\n});\n```\n\n##### `getGasPrice(params)`\n\nGets gas prices for different speeds on a chain.\n\n```typescript\nconst gasPrices = await sdk.gasService.getGasPrice({\n  chainId: Chains.ETHEREUM.chainId,\n  config: {\n    timeout: TimeString,\n    fields: {\n      standard: \"required\" | \"best effort\" | \"can ignore\",\n      fast: \"required\" | \"best effort\" | \"can ignore\",\n      instant: \"required\" | \"best effort\" | \"can ignore\",\n    },\n  },\n});\n```\n\n##### `calculateGasCost(params)`\n\nCalculates gas cost for a transaction.\n\n```typescript\nconst gasCost = await sdk.gasService.calculateGasCost({\n  chainId: Chains.ETHEREUM.chainId,\n  gasEstimation: BigInt(\"21000\"),\n  tx: {\n    from: \"0x...\",\n    to: \"0x...\",\n    data: \"0x...\",\n  },\n  config: {\n    timeout: TimeString,\n    fields: {\n      standard: \"required\" | \"best effort\" | \"can ignore\",\n      fast: \"required\" | \"best effort\" | \"can ignore\",\n      instant: \"required\" | \"best effort\" | \"can ignore\",\n    },\n  },\n});\n```\n\n##### `getQuickGasCalculator(params)`\n\nGets a quick gas calculator for a specific chain.\n\n```typescript\nconst calculator = await sdk.gasService.getQuickGasCalculator({\n  chainId: Chains.ETHEREUM.chainId,\n  config: {\n    timeout: TimeString,\n    fields: {\n      standard: \"required\" | \"best effort\" | \"can ignore\",\n      fast: \"required\" | \"best effort\" | \"can ignore\",\n      instant: \"required\" | \"best effort\" | \"can ignore\",\n    },\n  },\n});\n\n// Use the calculator\nconst gasPrices = calculator.getGasPrice();\nconst gasCost = calculator.calculateGasCost({\n  gasEstimation: BigInt(\"21000\"),\n  tx: {\n    from: \"0x...\",\n    to: \"0x...\",\n    data: \"0x...\",\n  },\n});\n```\n\n### Prices Service\n\nThe Prices Service provides token price information across multiple chains.\n\n#### Objective and Potential\n\n- **Objective**: Provide a unified interface for retrieving token prices across multiple chains\n- **Potential Use Cases**:\n  - Price feeds for DeFi applications\n  - Token value calculations\n  - Historical price analysis\n  - Price chart generation\n  - Multi-chain price aggregation\n\n#### Methods\n\n##### `supportedChains()`\n\nReturns an array of chain IDs that are supported by the service.\n\n```typescript\nconst chains = sdk.pricesService.supportedChains();\n```\n\n##### `supportedQueries()`\n\nReturns the supported price queries for each chain.\n\n```typescript\nconst queries = sdk.pricesService.supportedQueries();\n```\n\n##### `getCurrentPricesInChain(params)`\n\nGets current prices for tokens in a specific chain.\n\n```typescript\nconst prices = await sdk.pricesService.getCurrentPricesInChain({\n  chainId: Chains.ETHEREUM.chainId,\n  tokens: [\"0x...\", \"0x...\"],\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getCurrentPrices(params)`\n\nGets current prices for tokens across multiple chains.\n\n```typescript\nconst prices = await sdk.pricesService.getCurrentPrices({\n  tokens: [\n    { chainId: Chains.ETHEREUM.chainId, token: \"0x...\" },\n    { chainId: Chains.OPTIMISM.chainId, token: \"0x...\" },\n  ],\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getHistoricalPricesInChain(params)`\n\nGets historical prices for tokens in a specific chain at a given timestamp.\n\n```typescript\nconst prices = await sdk.pricesService.getHistoricalPricesInChain({\n  chainId: Chains.ETHEREUM.chainId,\n  tokens: [\"0x...\", \"0x...\"],\n  timestamp: 1234567890,\n  searchWidth: \"1h\",\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getHistoricalPrices(params)`\n\nGets historical prices for tokens across multiple chains at a given timestamp.\n\n```typescript\nconst prices = await sdk.pricesService.getHistoricalPrices({\n  tokens: [\n    { chainId: Chains.ETHEREUM.chainId, token: \"0x...\" },\n    { chainId: Chains.OPTIMISM.chainId, token: \"0x...\" },\n  ],\n  timestamp: 1234567890,\n  searchWidth: \"1h\",\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getBulkHistoricalPrices(params)`\n\nGets historical prices for multiple tokens at different timestamps.\n\n```typescript\nconst prices = await sdk.pricesService.getBulkHistoricalPrices({\n  tokens: [\n    { chainId: Chains.ETHEREUM.chainId, token: \"0x...\", timestamp: 1234567890 },\n    { chainId: Chains.OPTIMISM.chainId, token: \"0x...\", timestamp: 1234567890 },\n  ],\n  searchWidth: \"1h\",\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getChart(params)`\n\nGets price chart data for tokens over a specified time period.\n\n```typescript\nconst chart = await sdk.pricesService.getChart({\n  tokens: [\n    { chainId: Chains.ETHEREUM.chainId, token: \"0x...\" },\n    { chainId: Chains.OPTIMISM.chainId, token: \"0x...\" },\n  ],\n  span: 100,\n  period: \"1d\",\n  bound: { from: 1234567890 },\n  searchWidth: \"1h\",\n});\n```\n\n### Metadata Service\n\nThe Metadata Service provides token metadata information across multiple chains.\n\n#### Objective and Potential\n\n- **Objective**: Provide a unified interface for retrieving token metadata across multiple chains\n- **Potential Use Cases**:\n  - Token information display in UIs\n  - Token validation and verification\n  - Multi-chain token management\n  - Token data aggregation\n\n#### Methods\n\n##### `supportedChains()`\n\nReturns an array of chain IDs that are supported by the service.\n\n```typescript\nconst chains = sdk.metadataService.supportedChains();\n```\n\n##### `supportedProperties()`\n\nReturns the supported metadata properties for each chain.\n\n```typescript\nconst properties = sdk.metadataService.supportedProperties();\n```\n\n##### `getMetadataInChain(params)`\n\nGets metadata for tokens in a specific chain.\n\n```typescript\nconst metadata = await sdk.metadataService.getMetadataInChain({\n  chainId: Chains.ETHEREUM.chainId,\n  tokens: [\"0x...\", \"0x...\"],\n  config: {\n    fields: { symbol: \"required\", decimals: \"required\" },\n    timeout: \"30s\",\n  },\n});\n```\n\n##### `getMetadata(params)`\n\nGets metadata for tokens across multiple chains.\n\n```typescript\nconst metadata = await sdk.metadataService.getMetadata({\n  tokens: [\n    { chainId: Chains.ETHEREUM.chainId, token: \"0x...\" },\n    { chainId: Chains.OPTIMISM.chainId, token: \"0x...\" },\n  ],\n  config: {\n    fields: { symbol: \"required\", decimals: \"required\" },\n    timeout: \"30s\",\n  },\n});\n```\n\n### Permit2 Service\n\nThe Permit2 Service provides functionality for managing token approvals using the Permit2 protocol.\n\n#### Objective and Potential\n\n- **Objective**: Enable efficient and secure token approvals using the Permit2 standard\n- **Potential Use Cases**:\n  - Gas-optimized token approvals\n  - Batch approvals\n  - Cross-protocol permission management\n  - Automated approval systems\n  - Security-focused approval workflows\n\n```typescript\n// Get permit2 allowance\nconst allowance = await sdk.permit2Service.getAllowance({\n  chainId: Chains.ETHEREUM.chainId,\n  token: \"0x...\",\n  owner: \"0x...\",\n  spender: \"0x...\",\n});\n```\n\n### Earn Service\n\nThe Earn Service provides functionality for yield farming and staking operations.\n\n#### Objective and Potential\n\n- **Objective**: Enable efficient yield farming and staking operations across multiple protocols\n- **Potential Use Cases**:\n  - Yield farming strategy management\n  - Automated position management\n  - Cross-protocol yield optimization\n  - Permission-based position sharing\n  - Delayed withdrawal management\n  - Strategy migration and optimization\n\n#### Methods\n\n##### `getAllowanceTarget(params)`\n\nGets the allowance target address for a strategy.\n\n```typescript\nconst target = await sdk.earnService.getAllowanceTarget({\n  chainId: Chains.ETHEREUM.chainId,\n  strategyId: \"1-0x1234567890123456789012345678901234567890-42\", // Format: chainId-registryAddress-strategyNumber\n  depositWith: \"0x...\", // Token to deposit with\n  usePermit2: boolean,\n});\n```\n\n##### `preparePermitData(params)`\n\nPrepares permit data for token approvals.\n\n```typescript\nconst permitData = await sdk.earnService.preparePermitData({\n  chainId: Chains.ETHEREUM.chainId,\n  token: \"0x...\",\n  amount: \"1000000\",\n  spender: \"0x...\",\n});\n```\n\n##### `preparePermissionData(params)`\n\nPrepares permission data for position management.\n\n```typescript\nconst permissionData = await sdk.earnService.preparePermissionData({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"1-0xabcdef1234567890123456789012345678901234-1337\", // Format: chainId-vaultAddress-positionNumber\n  permissions: [{ operator: \"0x...\", permissions: [EarnPermission.INCREASE] }],\n  signerAddress: \"0x...\",\n  signatureValidFor: \"1w\",\n});\n```\n\n##### `buildCreatePositionTx(params)`\n\nBuilds a transaction to create a new earn position.\n\n```typescript\nconst tx = await sdk.earnService.buildCreatePositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  strategyId: \"1-0x1234567890123456789012345678901234567890-42\", // Format: chainId-registryAddress-strategyNumber\n  owner: \"0x...\",\n  permissions: [{ operator: \"0x...\", permissions: [EarnPermission.INCREASE] }],\n  deposit: { token: \"0x...\", amount: \"1000000\" },\n});\n```\n\n##### `buildIncreasePositionTx(params)`\n\nBuilds a transaction to increase an existing position.\n\n```typescript\nconst tx = await sdk.earnService.buildIncreasePositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"1-0xabcdef1234567890123456789012345678901234-1337\", // Format: chainId-vaultAddress-positionNumber\n  increase: { token: \"0x...\", amount: \"1000000\" },\n});\n```\n\n##### `buildWithdrawPositionTx(params)`\n\nBuilds a transaction to withdraw from a position.\n\n```typescript\nconst tx = await sdk.earnService.buildWithdrawPositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"1-0xabcdef1234567890123456789012345678901234-1337\", // Format: chainId-vaultAddress-positionNumber\n  withdraw: { type: \"market\", token: \"0x...\", amount: \"1000000\" },\n});\n```\n\n##### `buildClaimDelayedWithdrawPositionTx(params)`\n\nBuilds a transaction to claim a delayed withdrawal.\n\n```typescript\nconst tx = await sdk.earnService.buildClaimDelayedWithdrawPositionTx({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"1-0xabcdef1234567890123456789012345678901234-1337\", // Format: chainId-vaultAddress-positionNumber\n});\n```\n\n##### `estimateMarketWithdraw(params)`\n\nEstimates the amount of tokens that would be received from a market withdrawal.\n\n```typescript\nconst estimation = await sdk.earnService.estimateMarketWithdraw({\n  chainId: Chains.ETHEREUM.chainId,\n  positionId: \"1-0xabcdef1234567890123456789012345678901234-1337\", // Format: chainId-vaultAddress-positionNumber\n  token: \"0x...\",\n  amount: \"1000000\",\n  swapConfig: {\n    slippagePercentage: 1,\n    txValidFor: \"1w\",\n  },\n});\n```\n\n##### `getSupportedStrategies(params)`\n\nGets supported strategies for yield farming.\n\n```typescript\nconst strategies = await sdk.earnService.getSupportedStrategies({\n  chains: [Chains.ETHEREUM.chainId],\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getStrategy(params)`\n\nGets detailed information about a specific strategy.\n\n```typescript\nconst strategy = await sdk.earnService.getStrategy({\n  strategy: \"1-0x1234567890123456789012345678901234567890-42\", // Format: chainId-registryAddress-strategyNumber\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getPositionsByAccount(params)`\n\nGets earn positions for specific accounts.\n\n```typescript\nconst positions = await sdk.earnService.getPositionsByAccount({\n  accounts: [\"0x...\"],\n  chains: [Chains.ETHEREUM.chainId],\n  includeHistory: true,\n  includeHistoricalBalancesFrom: 1672531200,\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getPositionsById(params)`\n\nGets earn positions by their IDs.\n\n```typescript\nconst positions = await sdk.earnService.getPositionsById({\n  ids: [\"1-0xabcdef1234567890123456789012345678901234-1337\"], // Format: chainId-vaultAddress-positionNumber\n  includeHistory: true,\n  includeHistoricalBalancesFrom: 1672531200,\n  config: { timeout: \"30s\" },\n});\n```\n\n##### `getStrategyAsset(params)`\n\nGets the asset token for a strategy or position.\n\n```typescript\nconst asset = await sdk.earnService.getStrategyAsset({\n  chainId: Chains.ETHEREUM.chainId,\n  strategyId: \"1-0x1234567890123456789012345678901234567890-42\", // Format: chainId-registryAddress-strategyNumber\n  // or positionId: \"1-0xabcdef1234567890123456789012345678901234-1337\" // Format: chainId-vaultAddress-positionNumber\n});\n```\n\n## Advanced Usage\n\n### Error Handling\n\nThe SDK provides comprehensive error handling for all services:\n\n```typescript\ntry {\n  const quotes = await sdk.quoteService.getAllQuotes({...});\n} catch (error) {\n  if (error instanceof FailedToGenerateAnyQuotesError) {\n    // Handle quote generation failure\n  }\n}\n```\n\n### Configuration\n\nEach service can be configured with custom timeouts and other parameters:\n\n```typescript\nconst quotes = await sdk.quoteService.getAllQuotes({\n  request: {...},\n  config: {\n    timeout: \"30s\",\n    ignoredFailed: true,\n    sort: {\n      by: \"most-swapped-accounting-for-gas\",\n      using: \"gas-price\"\n    }\n  }\n});\n```\n\n### Multi-chain Support\n\nAll services support operations across multiple chains:\n\n```typescript\nconst balances = await sdk.balanceService.getBalancesForTokens({\n  account: \"0x...\",\n  tokens: {\n    [Chains.ETHEREUM.chainId]: [\"0x...\"],\n    [Chains.OPTIMISM.chainId]: [\"0x...\"],\n    [Chains.ARBITRUM.chainId]: [\"0x...\"],\n  },\n});\n```\n\n## 👨‍💻 Development\n\n### Environment Setup\n\n```bash\nyarn install\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### [Docs](https://docs.balmy.xyz) | [X](https://x.com/balmy_xyz) | [Discord](http://discord.balmy.xyz/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalmy-protocol%2Fsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbalmy-protocol%2Fsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalmy-protocol%2Fsdk/lists"}