npm package: @mvstp3fn/moneyfi-ts-sdk
Description: MoneyFi TypeScript SDK
Latest version: 0.2.10

# MoneyFi SDK

A TypeScript SDK for interacting with **MoneyFi strategies across multiple blockchain networks**, providing seamless integration for DeFi operations including deposits, withdrawals, and account management.

This library provides **ready-to-use transaction payloads** and API methods so frontend dApps can integrate **deposit**, **withdraw**, **user management**, and **statistics** features with various blockchain wallets.

## 📦 Installation

```bash
npm install @moneyfi/ts-sdk
yarn add @moneyfi/ts-sdk
```

## 🚀 Quick Start

### 1. Import & Initialize

```typescript
import type { UserStatistic } from '@moneyfi/ts-sdk';
import { MoneyFi } from '@moneyfi/ts-sdk';

// Initialize SDK
const moneyFi = new MoneyFi("integration_code");
```

### 2. Basic Usage Example in the Aptos blockchain

```typescript
// Create or get user
const user = await moneyFi.createUser({
  user_address: 'your-wallet-address',
});

// Check if wallet account exists
const hasAccount = await moneyFi.hasWalletAccount({
  sender: 'your-wallet-address'
});

// Get deposit transaction payload
const depositPayload = await moneyFi.getDepositTxPayload({
  type: PayloadType.Aptos,
  sender: 'your-wallet-address',
  token_address: 'token-contract-address',
  amount: 100000
});
```

### 3. Basic Usage Example in the EVM-compatible blockchains

```typescript
// Create or get user
const user = await moneyFi.createUser({
  user_address: 'your-wallet-address',
});

// Get deposit transaction payload
const depositPayload = await moneyFi.getDepositTxPayload({
  type: PayloadType.Evm,
  chain_id: 'chain-id',
  token_address: 'token-contract-address',
  amount: 100_000, 
  target_chain: 'aptos_chain_id'
});
```

## 📖 API Reference

### Core Methods

#### 🔹 Constructor

```typescript
new MoneyFi(config)
```

**Parameters**
- `config` → Containing `integration_code`.

**Throws**
- Error when config array is empty

---

#### 🔹 createUser(payload)

Creates or registers a user in the MoneyFi backend.

**Parameters**
- `payload: CreateUserPayload` → User creation data including address.

**Returns**
- `Promise<User>` → User object with registration details

---

#### 🔹 hasWalletAccount(params)

Checks if a given Aptos account already has a MoneyFi wallet account initialized on-chain.

Useful before calling getDepositTxPayload or getInitializationWalletAccountTxPayload.

**Parameters**
- `params: HasWalletAccountParam` → Parameters including user address

**Returns**
- `Promise<boolean>` → True if wallet account exists, false otherwise

---

#### 🔹 getInitializationWalletAccountTxPayload(params)

Requests initialization transaction for creating a wallet account (Aptos specific).
User must be create wallet account before depositing in Aptos. Each Aptos account corresponds to only one wallet account.

**Parameters**
- `params: TxInitializationWalletAccountParam` → Wallet initialization parameters

**Returns**
- `Promise<string>` → Signed transaction string prepared by backend

---

### Transaction Methods

#### 🔹 getDepositTxPayload(params)

Builds a raw transaction payload (BCS-encoded) for depositing supported tokens (USDC or USDT) into the MoneyFi protocol.
This transaction can then be signed and submitted by the user’s wallet.

**Parameters**
- `params: TxPayloadDepositParam` → Tx payload deposit parameters

**Returns**
- `Promise<TxPayloadDepositResponse>` → Raw transaction bytes (BCS-encoded) ready for signing & submitting.

---

#### 🔹 getWithdrawTxPayload(params)

Builds a raw transaction payload (BCS-encoded) for withdrawing supported tokens (USDC/USDT) from the MoneyFi protocol.
This transaction can then be signed and submitted by the user’s wallet.

**Parameters**
- `params: TxPayloadWithdrawParam` → Tx payload withdrawal parameters

**Returns**
- `Promise<TxPayloadWithdrawResponse>` →  Raw transaction bytes (BCS-encoded) ready for signing & submitting.

---

#### 🔹 reqWithdraw(address, payload)

Initiates an off-chain withdraw request.
The request is verified using a signature + public key and then processed by the MoneyFi backend.
You can later track its progress with getWithdrawStatus.

**Parameters**
- `address: string` → User wallet address
- `payload: ReqWithdrawPayload` → Withdrawal request details

**Returns**
- `Promise<void>`

---

#### 🔹 getWithdrawStatus(address)

Gets the processing status of a withdrawal request.

**Parameters**
- `address: string` → User wallet address

**Returns**
- `Promise<WithdrawStatusResponse>` → The status withdraw request from  reqWithdraw..

---

### Information Methods

#### 🔹 getUserStatistic(params)

Fetches user statistics for a specific chain.

**Parameters**
- `params: UserStaticsParam` → User statics param

**Returns**
- `Promise<UserStatistic>` → User statistics and performance data

---

#### 🔹 getSupportedChains()

Lists all supported blockchain networks.

**Returns**
- `Promise<SupportedChains>` → Available chains and their configurations

---

#### 🔹 getSupportedTokens()

Lists all supported tokens across networks.

**Returns**
- `Promise<SupportedTokens>` → Available tokens and their details

---

#### 🔹 getUserInformation(address)

Fetches detailed user information by wallet address.

**Parameters**
- `address: string` → User wallet address

**Returns**
- `Promise<User>` → Complete user profile and account details

---

#### 🔹 getMaxQuotesAmount(params)

Gets pricing and quote information for trading operations.

**Parameters**
- `params: GetQuoteParam` → Quote request parameters.

**Returns**
- `Promise<GetQuoteResponse>` → Quote information and pricing details

---

#### 🔹 getWalletAccountAssets(params)

Retrieve available assets in wallet account - only in Aptos network.

**Parameters**
- `params: GetWalletAccountAssetsParam` → Wallet account assets parameters.

**Returns**
- `Promise<GetWalletAccountAssetsResponses>` → Wallet account assets response

---

#### 🔹 getUserAssetBalance(params)

Retrieve user asset balance for a specific chain.

**Parameters**
- `params: GetUserAssetBalanceParam` → Asset balance query parameters.
  - `sender: string` → User wallet address
  - `chain_id: number` → Chain ID (e.g., 8453 for Base)
  - `token?: string` → Optional token address filter

**Returns**
- `Promise<GetUserAssetBalanceResponse>` → User's asset balance info

**Example**
```typescript
const balance = await moneyFi.getUserAssetBalance({
  sender: "0x8648511f4afa5d127c4381f992904bce332b5617",
  chain_id: 8453,
  token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" // USDC on Base
});
console.log(balance); // { balance: 3 }
```

---

#### 🔹 getTransactionHistory(params)

Retrieve paginated transaction history for a user with optional filters.

**Parameters**
- `params: GetTransactionHistoryParam` → Transaction history query parameters.
  - `limit?: number` → Number of transactions per page (default: 100, max: 100)
  - `page?: number` → Page number (default: 1, min: 1)
  - `address?: string` → Optional wallet address filter
  - `chain_id?: number` → Optional chain ID filter
  - `only_deposit_withdraw?: boolean` → Filter for deposit/withdraw transactions only

**Returns**
- `Promise<GetTransactionHistoryResponse>` → Paginated transaction history
  - `total: number` → Total number of transactions
  - `page: number` → Current page number
  - `nodes: Transaction[]` → Array of transaction records

**Transaction Object**
```typescript
interface Transaction {
  hash: string;
  method: TransactionMethod; // Withdraw, WithdrawRequest, Distribute, Deposit, TransferFund
  created_at: string;
  from: string;
  to: string;
  network: number;
  to_network?: number;
  protocol?: string;
  protocol_name?: string;
  amount: string;
  token: string;
  from_address_type?: AddressType; // StargateBridge, FundVault
  to_address_type?: AddressType;
  token_decimals?: number;
  strategy_name?: string;
}
```

**Example**
```typescript
const history = await moneyFi.getTransactionHistory({
  address: "0x23042F2D5B10cb21512c0a5a65a50cb8F5a24D67",
  limit: 10,
  page: 1,
  chain_id: 8453, // Base chain
  only_deposit_withdraw: true
});
console.log(history);
// {
//   total: 7,
//   page: 1,
//   nodes: [{ hash: "...", method: "Deposit", amount: "43000000", ... }]
// }
```

---

## Frontend Integration Flow in Aptos blockchain
### User Management
1. Use `createUser(payload)` to register new users if not exist
2. Call `hasWalletAccount(params)` to check wallet account exist in Aptos
3. Use `getInitializationWalletAccountTxPayload(params)` if wallet account setup is needed in Aptos and then submit the signed transaction to the blockchain
4. Deserialize the transaction in case of in Aptos transaction using Aptos SDK helpers
5. Extract the operator authentication from the signed transaction
6. Construct a multi-agent transaction
7. Submit the signed transaction to the blockchain
8. Monitor transaction status

### Deposit Flow
- Pre-requirement: 
1. Aptos: Create user off-chain and initialize wallet account on-chain before making deposit
- Flow:
1. Call `getDepositTxPayload(params)` with deposit details
2. Deserialize the transaction in case of in Aptos transaction using Aptos SDK helpers
3. Pass returned payload to the connected wallet for user signing
4. Submit the signed transaction to the blockchain
5. Monitor transaction status

### Withdrawal Flow
1. Call `reqWithdraw(address, payload)` for off-chain processing
2. Use `getWithdrawStatus(address)` to monitor withdrawal progress
3. Call `getWithdrawTxPayload(params)` for on-chain withdrawal
4. Deserialize the transaction in case of in Aptos transaction using Aptos SDK helpers
5. Pass returned payload to the connected wallet for user signing
6. Submit the signed transaction to the blockchain
7. Monitor transaction status

### Claim referral reward Flow 
1. Call `getWithdrawTxPayload(params)` for on-chain withdrawal
2. Deserialize the transaction in case of in Aptos transaction using Aptos SDK helpers
3. Pass returned payload to the connected wallet for user signing
4. Submit the signed transaction to the blockchain
5. Monitor transaction status

### User Information
1. Call `getUserStatistic(params)` to retrieve a user's investment analytics
2. Call `getUserInformation(address)` to retrieve a user's general information
3. Call `getWalletAccountAssets(params)` to retrieve available assets in wallet account - only in Aptos network
4. Call `getUserAssetBalance(params)` to retrieve user asset balance for a specific chain
5. Call `getTransactionHistory(params)` to retrieve paginated transaction history

### Supported chains and tokens
1. Call `getSupportedChains()` to retrieve list of supported chain
2. Call `getSupportedTokens()` to retrieve list of supported token


## Frontend Integration Flow in the EVM-compatible blockchains
### User Management
1. Use `createUser(payload)` to register new users if not exist

### Deposit Flow
- Pre-requirement: 
1. EVM: Create user off-chain before making a deposit
- Flow:
1. Call `getDepositTxPayload(params)` with deposit details
3. Pass returned payload to the connected wallet for user signing
4. Submit the signed transaction to the blockchain
5. Monitor transaction status

### Withdrawal Flow
1. Call `reqWithdraw(address, payload)` for off-chain processing
2. Pass returned payload to the connected wallet for user signing
3. Submit the signed transaction to the blockchain
4. Monitor transaction status

### User Information
1. Call `getUserStatistic(params)` to retrieve a user's investment analytics
2. Call `getUserInformation(address)` to retrieve a user's general information
3. Call `getUserAssetBalance(params)` to retrieve user asset balance for a specific chain
4. Call `getTransactionHistory(params)` to retrieve paginated transaction history

### Supported chains and tokens
1. Call `getSupportedChains()` to retrieve list of supported chain
2. Call `getSupportedTokens()` to retrieve list of supported token

## Documentation
- [API Reference](https://github.com/MoneyFi-fund/moneyFi-SDK/blob/main/docs/api.md)
- [Examples](https://github.com/MoneyFi-fund/moneyfi-SDK-example)