\n\n# Scallop TypeScript SDK\n\nTypeScript SDK for integrating with the Scallop lending protocol on Sui.\n\nCurrent package: `@scallop-io/sui-scallop-sdk` v5.x. ESM package, Node `>=22`, peer dependencies `@mysten/sui@>=2.22.0`, `@scallop-io/sui-kit@~2.2.0`, `@tanstack/query-core@>=5.95.2`.\n\n## Install\n\n```bash\npnpm add @scallop-io/sui-scallop-sdk @mysten/sui @scallop-io/sui-kit @tanstack/query-core\n```\n\n## Public Entry Points\n\nRoot export:\n\n```ts\nimport {\n Scallop,\n ScallopClient,\n ScallopBuilder,\n ScallopQuery,\n ScallopUtils,\n ScallopConstants,\n ScallopAddress,\n} from '@scallop-io/sui-scallop-sdk';\n```\n\nSubpath exports:\n\n```ts\nimport { ScallopClient } from '@scallop-io/sui-scallop-sdk/client';\nimport { ScallopBuilder } from '@scallop-io/sui-scallop-sdk/builder';\nimport { ScallopQuery } from '@scallop-io/sui-scallop-sdk/query';\nimport type { ScallopTxBlock } from '@scallop-io/sui-scallop-sdk/types';\nimport { ScallopError } from '@scallop-io/sui-scallop-sdk/errors';\nimport { consoleLogger } from '@scallop-io/sui-scallop-sdk/logger';\n```\n\nSupported subpaths:\n\n- `@scallop-io/sui-scallop-sdk`\n- `@scallop-io/sui-scallop-sdk/client`\n- `@scallop-io/sui-scallop-sdk/query`\n- `@scallop-io/sui-scallop-sdk/builder`\n- `@scallop-io/sui-scallop-sdk/errors`\n- `@scallop-io/sui-scallop-sdk/logger`\n- `@scallop-io/sui-scallop-sdk/types`\n\n## Main Models\n\n`Scallop` is the convenience factory. It owns one initialized `ScallopClient` and exposes factory methods for the other facades.\n\n```text\nScallop\n -> ScallopClient write facade; signs/sends user actions\n -> ScallopBuilder tx-block builder; owns SuiKit + TransactionExecutor\n -> ScallopQuery read facade; delegates to repositories\n -> ScallopUtils\n -> ScallopConstants\n -> ScallopAddress\n```\n\nImportant details:\n\n- `ScallopIndexer` model was removed. Query/indexer access is internal to repositories.\n- `ScallopConstants` composes `ScallopAddress`; use `constants.address` for the address adapter.\n- Back-compatible address forwarders remain on constants: `get`, `set`, `getAddresses`, `getAllAddresses`, `switchCurrentAddresses`. `read` and `isSeeded` are not forwarded — call them on `constants.address`.\n- Write-path signer/executor lives on `builder.executor`; raw SuiKit lives on `builder.suiKit`.\n\n## Create SDK\n\nMainnet example:\n\n### gRPC\n\n```ts\nimport { Scallop } from '@scallop-io/sui-scallop-sdk';\n\nconst sdk = new Scallop({\n addressId: '695fcdc084f790c04eb068dc',\n network: 'mainnet',\n fullnodeUrl: 'https://fullnode.mainnet.sui.io:443',\n secretKey: process.env.SECRET_KEY,\n pythEndpoints: ['https://pyth.dourolabs.app/hermes'],\n});\n\nconst client = await sdk.createScallopClient();\nconst query = await sdk.createScallopQuery();\nconst builder = await sdk.createScallopBuilder();\nconst utils = await sdk.createScallopUtils();\nconst constants = await sdk.getScallopConstants();\n```\n\nRead-only example:\n\n```ts\nconst sdk = new Scallop({\n addressId: '695fcdc084f790c04eb068dc',\n network: 'mainnet',\n fullnodeUrl: 'https://fullnode.mainnet.sui.io:443',\n walletAddress: '0x...',\n pythEndpoints: ['https://pyth.dourolabs.app/hermes'],\n});\n\nconst query = await sdk.createScallopQuery();\nconst pools = await query.getMarketPools();\n```\n\n### GraphQL\n\n`readTransport: 'graphql'` does **not** replace gRPC — Core reads and **all writes still go over gRPC**. `fullnodeUrl` (a gRPC fullnode) is optional here and defaults to the mainnet fullnode; set it to point Core reads and writes at your own node. The flag only makes balance reads and the heavy dynamic-field repos prefer native GraphQL queries. Point GraphQL at its own endpoint with `graphqlUrl` (defaults to mainnet), or inject a preconfigured `graphqlClient`:\n\n```ts\nconst sdk = new Scallop({\n addressId: '695fcdc084f790c04eb068dc',\n network: 'mainnet',\n readTransport: 'graphql',\n fullnodeUrl: 'https://fullnode.mainnet.sui.io:443', // gRPC node for Core reads + writes (optional; defaults to mainnet)\n graphqlUrl: 'https://graphql.mainnet.sui.io/graphql', // GraphQL endpoint (optional; defaults to mainnet)\n walletAddress: '0x...',\n pythEndpoints: ['https://pyth.dourolabs.app/hermes'],\n});\n```\n\nThe transport options are mutually exclusive at the type level: with `readTransport: 'grpc'` (or omitted — grpc is the default) `graphqlUrl` / `graphqlClient` are rejected, and with `readTransport: 'graphql'` an injected gRPC `suiClient` is rejected.\n\nManual construction is supported. Call `.init()` before use:\n\n```ts\nimport { ScallopQuery } from '@scallop-io/sui-scallop-sdk/query';\n\nconst query = new ScallopQuery({\n addressId: '695fcdc084f790c04eb068dc',\n network: 'mainnet',\n fullnodeUrl: 'https://fullnode.mainnet.sui.io:443',\n walletAddress: '0x...',\n});\n\nawait query.init();\n```\n\n## Constructor Options\n\nCommon required options:\n\n- `addressId`: Scallop API address config id.\n- `network`: Sui network, usually `'mainnet'`.\n- `fullnodeUrl`: Sui RPC URL.\n- `walletAddress`: required for read-only/wallet-scoped queries when no signer is supplied.\n- `secretKey` or `mnemonics`: required for signing via `ScallopClient`.\n\nCommon optional options:\n\n- `readTransport`: read transport, `'grpc'` (default) or `'graphql'`. **The Core read path and all writes always use gRPC** (via `fullnodeUrl`, which defaults to mainnet) regardless of this setting. `'graphql'` only makes the GraphQL-capable reads prefer GraphQL: balance reads via `GraphQLDataSource`, plus some heavy dynamic-field reads (e.g. pool addresses, xOracle, veSCA) that use single nested GraphQL queries instead of the gRPC multi-call fan-out. The transport is selected strictly — there is **no automatic fallback** between GraphQL and gRPC, so a failing read on the selected transport propagates its error (fail-loud) rather than silently degrading.\n- `graphqlUrl` / `graphqlClient`: Sui GraphQL endpoint / preconfigured `SuiGraphQLClient`. **Only accepted with `readTransport: 'graphql'`** (rejected at the type level otherwise); `graphqlClient` takes precedence over `graphqlUrl`, and the endpoint defaults to mainnet when neither is given.\n- `pythEndpoints`: Pyth Hermes endpoints for price-update flows. Default `https://pyth.dourolabs.app/hermes`.\n- `pythApiKey`: Pyth (Hermes) API access token. The hosted Pyth endpoint now requires a key. When set, Pyth coin prices are read **directly from the Pyth API** (sent as the Hermes `accessToken`); when omitted, prices are read from the **Scallop indexer** instead. Either way, `getPythCoinPrice(s)` falls back to on-chain feed objects if the API source fails.\n- `queryClient` / `queryClientConfig`: custom `@tanstack/query-core` cache. Wallet-balance reads are memoised through this cache with a **5s TTL** (`staleTime`/`gcTime`). On the gRPC transport, coin-amount readers share one `listBalances` snapshot per node + address, so a balance read within ~5s of a supply/withdraw can return the pre-write amount. If you need read-your-write freshness right after a mutation, invalidate the `getAllCoinBalances` (and per-coin `getCoinBalance`) query-key prefixes on your `queryClient`, or shorten the TTL via `queryClientConfig`.\n- `priceTimeout`: cache lifetime (ms) for the full Pyth price-feed list. Default `5_000`. Within this window, single/subset price reads are served from one cached full-list fetch instead of re-hitting the Pyth API; a longer value cuts API traffic at the cost of price staleness.\n- `logger`: SDK logger. Default is silent `noopLogger`; pass `consoleLogger` to opt into console output.\n- `strictInit`: when `true`, `init()` throws `ScallopConfigError` if required config is missing.\n- `tokensPerSecond`: RPC read rate limit.\n- `usePythPullModel`, `useOnChainXOracleList`, `sponsoredFeeds`: tx-builder oracle behavior.\n\n### Overriding the underlying clients\n\nThe SDK builds its own transport clients by default, but you can inject your own:\n\n- `suiClient` (`ClientWithCoreApi` from `@mysten/sui`): overrides the Sui RPC client used for on-chain reads. When omitted, the SDK builds a `SuiGrpcClient` from `network` + `fullnodeUrl`. Accepted by `ScallopUtils` / `ScallopQuery` / `ScallopBuilder` / `ScallopClient` / `Scallop`.\n- `httpClient` (`AxiosInstance`): overrides the HTTP client used for Scallop API / address-config fetches. When omitted, the SDK creates an Axios instance from the API `url` + `timeout`. Accepted anywhere `ScallopAddress` config flows (`Scallop`, `ScallopConstants`, `ScallopAddress`).\n- `client` (`ScallopClient`): only on the top-level `Scallop` constructor — reuse an already-built `ScallopClient` instead of constructing a new one. Unrelated to the two transport clients above.\n\n```ts\nimport { Scallop } from '@scallop-io/sui-scallop-sdk';\nimport { SuiClient } from '@mysten/sui/client';\nimport axios from 'axios';\n\nconst sdk = new Scallop({\n addressId: '695fcdc084f790c04eb068dc',\n network: 'mainnet',\n fullnodeUrl: 'https://fullnode.mainnet.sui.io:443',\n walletAddress: '0x...',\n suiClient: new SuiClient({ url: 'https://fullnode.mainnet.sui.io:443' }), // custom Sui RPC client\n httpClient: axios.create({ timeout: 15_000 }), // custom HTTP client for API/address fetches\n});\n```\n\n> Note: prior to v4.3.0 these were all named `client` and collided into an unusable intersection type. Use `suiClient` / `httpClient` (and the top-level `client`) on v4.3.0+.\n\n## Query Examples\n\n```ts\nconst marketPools = await query.getMarketPools();\nconst suiPool = await query.getMarketPool('sui');\nconst collaterals = await query.getMarketCollaterals();\n\nconst obligations = await query.getObligations('0xOwner');\nconst obligation = await query.queryObligation('0xObligationId');\nconst portfolio = await query.getUserPortfolio({ walletAddress: '0xOwner' });\n\nconst prices = await query.getPythCoinPrices({ coinNames: ['sui', 'usdc'] });\nconst allPrices = await query.getAllCoinPrices();\n\nconst stakeAccounts = await query.getAllStakeAccounts('0xOwner');\nconst tvl = await query.getTvl();\n```\n\nRead source selection is available on supported facade methods via legacy-compatible flags:\n\n```ts\nawait query.getMarketPools(undefined, { source: 'rpc' }); // on-chain RPC\nawait query.getMarketPools(undefined, { source: 'indexer' }); // API/indexer only\nawait query.getMarketPools(undefined, { source: 'indexer-first' }); // API/indexer with RPC fallback\nawait query.getMarketPools(undefined, { indexer: true }); // same as indexer-first\n```\n\nRepository internals normalize those values to `onchain`, `api`, or `api-first`.\n\n## Client Examples\n\n`ScallopClient` methods sign and execute by default. Pass `false` where supported to receive an unsigned transaction instead.\n\n```ts\nconst result = await client.openObligation();\n\nawait client.supply('sui', 1_000_000_000);\nawait client.depositCollateral('sui', 1_000_000_000);\nawait client.withdraw('sui', 1_000_000_000);\nawait client.withdrawCollateral('sui', 1_000_000_000);\n\nawait client.borrow(\n 'usdc',\n 1_000_000,\n true,\n '0xObligationId',\n '0xObligationKey'\n);\nawait client.repay(\n 'usdc',\n 1_000_000,\n true,\n '0xObligationId',\n '0xObligationKey'\n);\n\nconst tx = await client.supply('sui', 1_000_000_000, false);\n```\n\nOther write helpers include:\n\n- lending: `supply`, `withdraw`, `flashLoan`\n- collateral: `depositCollateral`, `withdrawCollateral`\n- borrow: `openObligation`, `borrow`, `repay`\n- spool: `createStakeAccount`, `stake`, `unstake`, `claim`, `supplyAndStake`, `unstakeAndWithdraw`\n- veSCA / incentives: `stakeObligation`, `unstakeObligation`, `claimBorrowIncentive`, `claimAllUnlockedSca`\n- migration/test helpers: `migrateAllMarketCoin`, `mintTestCoin`\n\n## Transaction Builder\n\nUse `ScallopBuilder` for custom transaction composition.\n\n```ts\nconst tx = builder.createTxBlock();\n\nawait tx.supplyQuick('sui', 1_000_000_000);\nawait tx.depositCollateralQuick('sui', 1_000_000_000);\n\nconst result = await builder.executor.signAndSendTxn(tx);\n```\n\n`ScallopTxBlock` exposes both flat methods and module-grouped methods. References are identity-equal:\n\n```ts\ntx.supplyQuick === tx.core.supplyQuick; // true\ntx.stake === tx.spool.stake; // true\n```\n\nModules:\n\n- `tx.core`: lending, collateral, borrow, liquidations, flash loans\n- `tx.spool`: staking market coins\n- `tx.vesca`: veSCA lock/split/merge/redeem flows\n- `tx.borrowIncentive`: obligation staking and incentive claims\n- `tx.referral`: referral binding/revenue flows\n- `tx.loyalty`: loyalty reward claims\n- `tx.sCoin`: sCoin mint/burn\n\nMethod conventions:\n\n- normal methods are synchronous Move-call wrappers and return `TransactionResult`.\n- `*Quick` methods are async helpers that fetch required coins/objects/oracle updates, call normal methods, and return leftovers where needed.\n- canonical lending names are `supply` / `supplyQuick` / `depositCollateral` / `depositCollateralQuick`.\n- legacy `deposit*` and `addCollateral*` names are deprecated.\n\n## Constants And Addresses\n\n```ts\nconst constants = await sdk.getScallopConstants();\n\nconst corePackage = constants.get('core.packages.protocol.id');\nconst allAddresses = constants.getAddresses();\n\nconst addressAdapter = constants.address;\nconst addressId = addressAdapter.addressId;\n```\n\n`constants.whitelist` and `constants.poolAddresses` are frozen snapshots after `init()`.\n\n## Errors And Logging\n\nSDK internals throw typed errors:\n\n- `ScallopRpcError`: Sui RPC / gRPC failures\n- `ScallopIndexerError`: Scallop API/indexer HTTP failures\n- `ScallopParseError`: invalid or unexpected payload\n- `ScallopConfigError`: config validation failure\n- `ScallopTransactionBuildError`: tx construction failure\n\n```ts\nimport { ScallopError } from '@scallop-io/sui-scallop-sdk/errors';\nimport { consoleLogger } from '@scallop-io/sui-scallop-sdk/logger';\n\nconst sdk = new Scallop({\n addressId: '695fcdc084f790c04eb068dc',\n network: 'mainnet',\n fullnodeUrl: 'https://fullnode.mainnet.sui.io:443',\n walletAddress: '0x...',\n logger: consoleLogger,\n});\n\ntry {\n await query.getMarketPools();\n} catch (error) {\n if (error instanceof ScallopError) {\n // error.cause and error.context are available where provided\n }\n}\n```\n\n## Local Development\n\n```bash\npnpm install\npnpm run build\npnpm run test:typecheck\npnpm run test:unit\n```\n\nUseful scripts:\n\n```bash\npnpm run build # production build\npnpm run build:dev # development build\npnpm run test # typecheck + all tests\npnpm run test:typecheck # TypeScript checks for tests\npnpm run test:no-console # no console.* in SDK internals\npnpm run test:unit # network-free unit tests\npnpm run test:repo # repository unit tests only\npnpm run test:integration # integration tests; needs network + local env setup\npnpm run test:watch # watch mode\npnpm run lint:fix\npnpm run format:fix\npnpm run doc # generate typedoc output into docs/\n```\n\nIntegration/query/full test runs require local environment variables such as `SECRET_KEY`. Do not commit secrets.\n\n## More Docs\n\n- Contributor architecture: [`llm-docs/SDK_STRUCTURE.md`](llm-docs/SDK_STRUCTURE.md)\n- Client guide: [`document/client.md`](document/client.md)\n- Query guide: [`document/query.md`](document/query.md)\n- Address guide: [`document/address.md`](document/address.md)\n- Builder guide: [`document/builder.md`](document/builder.md)\n- Utils guide: [`document/utils.md`](document/utils.md)\n- Constants guide: [`document/constants.md`](document/constants.md)\n\n## License\n\n[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0)\n\n[](https://deepwiki.com/scallop-io/sui-scallop-sdk)\n","readmeFilename":"README.md"}
![\"scallop\"](\"https://i.imgur.com/g7Y4MIj.png\")
\n \n![\"GitHub](\"https://img.shields.io/github/v/release/scallop-io/sui-scallop-sdk?display_name=tag\")
\n ![\"GitHub](\"https://img.shields.io/github/license/scallop-io/sui-scallop-sdk?logoColor=blue\")
\n