{"id":27066003,"url":"https://github.com/balancednetwork/balanced-intents-sdk","last_synced_at":"2025-06-17T06:05:45.842Z","repository":{"id":280011438,"uuid":"876464204","full_name":"balancednetwork/balanced-intents-sdk","owner":"balancednetwork","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-25T09:44:21.000Z","size":43,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-05T18:51:29.817Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/balancednetwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-10-22T02:35:06.000Z","updated_at":"2024-11-25T09:44:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"aacbd346-7fad-451a-a536-9366dae9caa8","html_url":"https://github.com/balancednetwork/balanced-intents-sdk","commit_stats":null,"previous_names":["balancednetwork/balanced-intents-sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/balancednetwork/balanced-intents-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancednetwork%2Fbalanced-intents-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancednetwork%2Fbalanced-intents-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancednetwork%2Fbalanced-intents-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancednetwork%2Fbalanced-intents-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/balancednetwork","download_url":"https://codeload.github.com/balancednetwork/balanced-intents-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancednetwork%2Fbalanced-intents-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260301992,"owners_count":22988721,"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":"2025-04-05T18:34:42.295Z","updated_at":"2025-06-17T06:05:45.831Z","avatar_url":"https://github.com/balancednetwork.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Balanced Intent Solver SDK (Alpha)\n\nBalanced Intent Solver SDK provides abstractions to assist you with interacting with the cross-chain Intent Smart Contracts and Solver.\n\n**Note** SDK is currently in alpha testing stage and is subject to change!\n\n## Installation\n\n### NPM\n\nInstalling through npm:\n\n`npm i --save @balanced/solver-sdk`\n\n**NOTE** Package is not yet published to the npm registry!!!\n\n### Local\n\nPackage can be locally installed by following this steps:\n\n1. Clone this repository to your local machine.\n2. `cd` into repository folder location.\n3. Execute `npm install` command in your CLI to install dependencies.\n4. Execute `npm run build` to build the package.\n5. In your app repository `package.json` file, define dependency named `\"@balanced/solver-sdk\"` under `\"dependencies\"`.\n   Instead of version define absolute path to your SDK repository `\"file:\u003csdk-repository-path\u003e\"` (e.g. `\"file:/Users/dev/balanced-solver-sdk\"`).\n   Full example: `\"@balanced/solver-sdk\": \"file:/Users/dev/balanced-solver-sdk\"`.\n\n## Local Development\n\nHow to setup local development\n\n1. Clone repository.\n2. Make sure you have [Node.js](https://nodejs.org/en/download/package-manager) v18+ and corresponding npm installed on your system.\n3. Execute `npm install` command in your CLI to install dependencies.\n4. Make code changes.\n   1. Do not forget to export TS files in same folder `index.ts`.\n   2. Always import files using `.js` postfix.\n5. Before commiting execute `npm run prepublishOnly` in order to verify build, format and exports.\n\n## Load SDK Config\n\nSDK includes predefined configurations of supported chains, tokens and other relevant information for the client to consume.\n\n```typescript\nimport { ChainName, ChainConfig, chainConfig, Token, IntentService } from \"@balanced/solver-sdk\"\n\n// all supported Intent chains\nconst supportedChains: ChainName[] = IntentService.getSupportedChains()\n\n// retrieve arbitrum chain config\nconst arbChainConfig: EvmChainConfig = IntentService.getChainConfig(\"arb\")\n\n// example of how to construct token per chain map using supported chains array\nconst supportedTokensPerChain: Map\u003cChainName, Token[]\u003e = new Map(\n  supportedChains.map((chain) =\u003e {\n    return [chain, IntentService.getChainConfig(chain).supportedTokens]\n  }),\n)\n\n// example of how to construct chain name to chain config map\nconst chainConfigs: Map\u003cChainName, ChainConfig\u003e = new Map(\n  supportedChains.map((chain) =\u003e {\n    return [chain, IntentService.getChainConfig(chain)]\n  }),\n)\n```\n\n## Request a Quote\n\nRequesting a quote should require you to just consume user input amount and converting it to the appropriate token amount (scaled by token decimals).\nAll the required configurations (chain id [nid], token decimals and address) should be loaded as described in [Load SDK Config](#load-sdk-config).\n\n```typescript\nimport { IntentService } from \"@balanced/solver-sdk\"\n\nconst quoteResult = await IntentService.getQuote({\n  token_src: \"0x82af49447d8a07e3bd95bd0d56f35241523fbab1\",\n  token_src_blockchain_id: \"0xa4b1.arbitrum\",\n  token_dst: \"0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI\",\n  token_dst_blockchain_id: \"sui\",\n  src_amount: \"100000000000000000\",\n})\n\n/**\n * Example response (quoteResult)\n * {\n *   \"ok\": true,\n *   \"value\": {\n *      \"output\": {\n *        \"expected_output\":\"1000000000000\", // to be used in create intent order as toAmount\n *        \"uuid\":\"e2795d2c-14a5-4d18-9be6-a257d7c9d274\" // to be used in create intent order as quote_uuid\n *      }\n *   }\n * }\n */\n```\n\n## Initialising Providers\n\nSDK abstracts away the wallet and public RPC clients using `ChainProviderType` TS type which can be one of the following:\n\n- `EvmProvider`: Provider used for EVM type chains (ETH, BSC, etc..). Implemented using [viem](https://viem.sh/docs/clients/wallet#json-rpc-accounts).\n- `SuiProvider`: Provider used for SUI type chains (SUI). Implemented using [@mysten/sui](https://github.com/MystenLabs/sui) and [@mysten/wallet-standard](https://docs.sui.io/standards/wallet-standard).\n\nOptionally, you can supply EVM providers (wallet and public clients) yourself (see `EvmInitializedConfig`).\nSUI accepts only initialized Wallet, Account and Client.\n\nProviders are used to request wallet actions (prompts wallet extension) and make RPC calls to the RPC nodes.\n\nEVM Provider example:\n\n```typescript\nimport { EvmProvider } from \"@balanced/solver-sdk\"\n\n// NOTE: user address should be provided by application when user connects wallet\nconst evmProvider = new EvmProvider({\n  userAddress: \"0x601020c5797Cdd34f64476b9bf887a353150Cb9a\",\n  chain: \"arb\",\n  provider: (window as any).ethereum,\n})\n```\n\nSUI Provider example (uses [SUI dApp Kit](https://sdk.mystenlabs.com/dapp-kit/):\n\n```typescript\nimport { SuiProvider } from \"@balanced/solver-sdk\"\nimport { useCurrentWallet, useCurrentAccount } from \"@mysten/dapp-kit\"\n\nconst account = useCurrentAccount()\nconst { currentWallet, connectionStatus } = useCurrentWallet()\n\n// check that wallet is connected and account is defined\nif (connectionStatus === \"connected\" \u0026\u0026 account) {\n  const suiProvider = new SuiProvider({ wallet, account, client })\n} else {\n  throw new Error(\"Wallet or Account undefined. Please connect wallet and select account.\")\n}\n```\n\n## Create Intent Order\n\nCreating Intent Order requires creating provider for the chain that intent is going to be created on (`fromChain`).\n\nExample for ARB -\u003e SUI Intent Order:\n\n```typescript\nimport { IntentService, EvmProvider, CreateIntentOrderPayload, IntentStatusCode } from \"@balanced/solver-sdk\"\n\n// create EVM provider because \"arb\" is of ChainType \"evm\" (defined in ChainConfig type - see section Load SDK Config)\n// NOTE: window can only be accessed client side (browser)\nconst evmProvider = new EvmProvider({\n  userAddress: \"0x601020c5797Cdd34f64476b9bf887a353150Cb9a\",\n  chain: \"arb\",\n  provider: (window as any).ethereum,\n})\n\nconst intentOrderPayload: CreateIntentOrderPayload = {\n  quote_uuid: \"a0dd7652-b360-4123-ab2d-78cfbcd20c6b\",\n  fromAddress: \"0x601020c5797Cdd34f64476b9bf887a353150Cb9a\", // address we are sending funds from (fromChain)\n  toAddress: \"0x81600ec58a2efd97f41380370cddf25b7a416d03ee081552becfa9710ea30878\", // destination address where funds are transfered to (toChain)\n  fromChain: \"arb\", // ChainName\n  toChain: \"sui\", // ChainName\n  token: \"0x82af49447d8a07e3bd95bd0d56f35241523fbab1\",\n  amount: BigInt(\"100000000000000000\"),\n  toToken: \"0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI\",\n  toAmount: BigInt(\"1000000000000\"),\n} as const\n\n// checks if token transfer amount is approved (required for EVM, can be skipped for SUI as it defaults to true)\nconst isAllowanceValid = await IntentService.isAllowanceValid(intentOrderPayload, evmProvider)\n\nif (isAllowanceValid.ok) {\n  if (!isAllowanceValid.value) {\n    // allowance invalid, prompt approval\n    const approvalResult = await IntentService.approve(\n      \"0x82af49447d8a07e3bd95bd0d56f35241523fbab1\",\n      BigInt(\"100000000000000000\"),\n      IntentService.getChainConfig(\"arb\").intentContract,\n      evmProvider,\n    )\n\n    if (approvalResult.ok) {\n      const executionResult = await IntentService.executeIntentOrder(intentOrderPayload, evmProvider)\n\n      if (executionResult.ok) {\n        const intentStatus = await IntentService.getStatus({\n          task_id: executionResult.value.task_id,\n        })\n\n        if (intentStatus.ok) {\n          console.log(intentStatus)\n\n          /**\n           * Example status\n           * {\n           *   \"ok\": true,\n           *   \"value\": {\n           *      \"output\": {\n           *        \"status\":3, // use IntentStatusCode to map status code\n           *        \"tx_hash\":\"0xabcdefasdasdsafssadasdsadsadasdsadasdsadsa\"\n           *      }\n           *   }\n           * }\n           */\n        } else {\n          // handle error\n        }\n      } else {\n        // handle error\n      }\n    } else {\n      // handle error\n    }\n  } else {\n    // allowance is valid\n\n    const executionResult = await IntentService.executeIntentOrder(intentOrderPayload, evmProvider)\n    // ...rest of result check and status check logic as above\n  }\n} else {\n  // handle error\n}\n```\n\n## Cancel Intent Order\n\nActive Intent Order can be cancelled using order ID obtained as explained in [Get Intent Order](#get-intent-order).\n\nExample cancel order:\n\n```typescript\nimport { IntentService, SwapOrder, EvmProvider } from \"@balanced/solver-sdk\"\n\nconst evmProvider = new EvmProvider({\n   userAddress: \"0x601020c5797Cdd34f64476b9bf887a353150Cb9a\",\n   chain: \"arb\",\n   provider: (window as any).ethereum\n})\nconst intentOrder: Result\u003cSwapOrder\u003e = await IntentService.getOrder(\n  \"0xabcdefasdasdsafssadasdsadsadasdsadasdsadsa\",\n  IntentService.getChainConfig(\"arb\").intentContract,\n  evmProvider,\n)\n\nif (intentOrder.ok) {\n   const cancelResult: Result\u003cstring\u003e = await IntentService.cancelIntentOrder(\n      intentOrder.value.id,\n      \"arb\",\n      evmProvider,\n   )\n\n   if (cancelResult.ok) {\n      const txHash = cancelResult.value\n      ..\n   } else {\n      // handle error\n   }\n} else {\n   // handle error\n}\n\n\n```\n\n## Get Intent Order\n\nAfter the Intent order is created (`executeIntentOrder`), the resulting `txHash` can be used to query created on-chain order data.\nIntent order id is assigned as a part of tx execution, thus if you want to grab an actual order id to be potentially canceled in future\nyou should invoke `IntentService.getOrder(..)` function.\n\nExample get order:\n\n```typescript\nimport { IntentService, SwapOrder, EvmProvider } from \"@balanced/solver-sdk\"\n\nconst evmProvider = new EvmProvider({\n  userAddress: \"0x601020c5797Cdd34f64476b9bf887a353150Cb9a\",\n  chain: \"arb\",\n  provider: (window as any).ethereum,\n})\nconst intentOrder: Result\u003cSwapOrder\u003e = await IntentService.getOrder(\n  \"0xabcdefasdasdsafssadasdsadsadasdsadasdsadsa\",\n  IntentService.getChainConfig(\"arb\").intentContract,\n  evmProvider,\n)\n```\n\n## Get Intent Status\n\nAfter Intent Order is created, the resulting `task_id` can be used to query the status of the task.\n\nExample status check:\n\n```typescript\nimport { IntentService } from \"@balanced/solver-sdk\"\n\nconst intentStatus = await IntentService.getStatus({\n  task_id: \"a0dd7652-b360-4123-ab2d-78cfbcd20c6b\",\n})\n\n/**\n * Example intentStatus response\n * {\n *   \"ok\": true,\n *   \"value\": {\n *      \"output\": {\n *        \"status\":3, // use IntentStatusCode to map status code\n *        \"tx_hash\":\"0xabcdefasdasdsafssadasdsadsadasdsadasdsadsa\"\n *      }\n *   }\n * }\n */\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalancednetwork%2Fbalanced-intents-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbalancednetwork%2Fbalanced-intents-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalancednetwork%2Fbalanced-intents-sdk/lists"}